1 /*
   2  * Copyright (c) 1997, 2024, Oracle and/or its affiliates. All rights reserved.
   3  * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
   4  *
   5  * This code is free software; you can redistribute it and/or modify it
   6  * under the terms of the GNU General Public License version 2 only, as
   7  * published by the Free Software Foundation.  Oracle designates this
   8  * particular file as subject to the "Classpath" exception as provided
   9  * by Oracle in the LICENSE file that accompanied this code.
  10  *
  11  * This code is distributed in the hope that it will be useful, but WITHOUT
  12  * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  13  * FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
  14  * version 2 for more details (a copy is included in the LICENSE file that
  15  * accompanied this code).
  16  *
  17  * You should have received a copy of the GNU General Public License version
  18  * 2 along with this work; if not, write to the Free Software Foundation,
  19  * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
  20  *
  21  * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
  22  * or visit www.oracle.com if you need additional information or have any
  23  * questions.
  24  */
  25 
  26 package java.util;
  27 
  28 import jdk.internal.util.ArraysSupport;

  29 import jdk.internal.vm.annotation.IntrinsicCandidate;
  30 
  31 import java.io.Serializable;
  32 import java.lang.reflect.Array;
  33 import java.util.concurrent.ForkJoinPool;
  34 import java.util.function.BinaryOperator;
  35 import java.util.function.Consumer;
  36 import java.util.function.DoubleBinaryOperator;
  37 import java.util.function.IntBinaryOperator;
  38 import java.util.function.IntFunction;
  39 import java.util.function.IntToDoubleFunction;
  40 import java.util.function.IntToLongFunction;
  41 import java.util.function.IntUnaryOperator;
  42 import java.util.function.LongBinaryOperator;
  43 import java.util.function.UnaryOperator;
  44 import java.util.stream.DoubleStream;
  45 import java.util.stream.IntStream;
  46 import java.util.stream.LongStream;
  47 import java.util.stream.Stream;
  48 import java.util.stream.StreamSupport;
  49 
  50 /**
  51  * This class contains various methods for manipulating arrays (such as
  52  * sorting and searching). This class also contains a static factory
  53  * that allows arrays to be viewed as lists.
  54  *
  55  * <p>The methods in this class all throw a {@code NullPointerException},
  56  * if the specified array reference is null, except where noted.
  57  *
  58  * <p>The documentation for the methods contained in this class includes
  59  * brief descriptions of the <i>implementations</i>. Such descriptions should
  60  * be regarded as <i>implementation notes</i>, rather than parts of the
  61  * <i>specification</i>. Implementors should feel free to substitute other
  62  * algorithms, so long as the specification itself is adhered to. (For
  63  * example, the algorithm used by {@code sort(Object[])} does not have to be
  64  * a MergeSort, but it does have to be <i>stable</i>.)
  65  *
  66  * <p>This class is a member of the
  67  * <a href="{@docRoot}/java.base/java/util/package-summary.html#CollectionsFramework">
  68  * Java Collections Framework</a>.
  69  *
  70  * @author Josh Bloch
  71  * @author Neal Gafter
  72  * @author John Rose
  73  * @since  1.2
  74  */
  75 public final class Arrays {
  76 
  77     // Suppresses default constructor, ensuring non-instantiability.
  78     private Arrays() {}
  79 
  80     /*
  81      * Sorting methods. Note that all public "sort" methods take the
  82      * same form: performing argument checks if necessary, and then
  83      * expanding arguments into those required for the internal
  84      * implementation methods residing in other package-private
  85      * classes (except for legacyMergeSort, included in this class).
  86      */
  87 
  88     /**
  89      * Sorts the specified array into ascending numerical order.
  90      *
  91      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
  92      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
  93      * offers O(n log(n)) performance on all data sets, and is typically
  94      * faster than traditional (one-pivot) Quicksort implementations.
  95      *
  96      * @param a the array to be sorted
  97      */
  98     public static void sort(int[] a) {
  99         DualPivotQuicksort.sort(a, 0, 0, a.length);
 100     }
 101 
 102     /**
 103      * Sorts the specified range of the array into ascending order. The range
 104      * to be sorted extends from the index {@code fromIndex}, inclusive, to
 105      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
 106      * the range to be sorted is empty.
 107      *
 108      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 109      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 110      * offers O(n log(n)) performance on all data sets, and is typically
 111      * faster than traditional (one-pivot) Quicksort implementations.
 112      *
 113      * @param a the array to be sorted
 114      * @param fromIndex the index of the first element, inclusive, to be sorted
 115      * @param toIndex the index of the last element, exclusive, to be sorted
 116      *
 117      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 118      * @throws ArrayIndexOutOfBoundsException
 119      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 120      */
 121     public static void sort(int[] a, int fromIndex, int toIndex) {
 122         rangeCheck(a.length, fromIndex, toIndex);
 123         DualPivotQuicksort.sort(a, 0, fromIndex, toIndex);
 124     }
 125 
 126     /**
 127      * Sorts the specified array into ascending numerical order.
 128      *
 129      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 130      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 131      * offers O(n log(n)) performance on all data sets, and is typically
 132      * faster than traditional (one-pivot) Quicksort implementations.
 133      *
 134      * @param a the array to be sorted
 135      */
 136     public static void sort(long[] a) {
 137         DualPivotQuicksort.sort(a, 0, 0, a.length);
 138     }
 139 
 140     /**
 141      * Sorts the specified range of the array into ascending order. The range
 142      * to be sorted extends from the index {@code fromIndex}, inclusive, to
 143      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
 144      * the range to be sorted is empty.
 145      *
 146      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 147      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 148      * offers O(n log(n)) performance on all data sets, and is typically
 149      * faster than traditional (one-pivot) Quicksort implementations.
 150      *
 151      * @param a the array to be sorted
 152      * @param fromIndex the index of the first element, inclusive, to be sorted
 153      * @param toIndex the index of the last element, exclusive, to be sorted
 154      *
 155      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 156      * @throws ArrayIndexOutOfBoundsException
 157      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 158      */
 159     public static void sort(long[] a, int fromIndex, int toIndex) {
 160         rangeCheck(a.length, fromIndex, toIndex);
 161         DualPivotQuicksort.sort(a, 0, fromIndex, toIndex);
 162     }
 163 
 164     /**
 165      * Sorts the specified array into ascending numerical order.
 166      *
 167      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 168      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 169      * offers O(n log(n)) performance on all data sets, and is typically
 170      * faster than traditional (one-pivot) Quicksort implementations.
 171      *
 172      * @param a the array to be sorted
 173      */
 174     public static void sort(short[] a) {
 175         DualPivotQuicksort.sort(a, 0, a.length);
 176     }
 177 
 178     /**
 179      * Sorts the specified range of the array into ascending order. The range
 180      * to be sorted extends from the index {@code fromIndex}, inclusive, to
 181      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
 182      * the range to be sorted is empty.
 183      *
 184      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 185      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 186      * offers O(n log(n)) performance on all data sets, and is typically
 187      * faster than traditional (one-pivot) Quicksort implementations.
 188      *
 189      * @param a the array to be sorted
 190      * @param fromIndex the index of the first element, inclusive, to be sorted
 191      * @param toIndex the index of the last element, exclusive, to be sorted
 192      *
 193      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 194      * @throws ArrayIndexOutOfBoundsException
 195      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 196      */
 197     public static void sort(short[] a, int fromIndex, int toIndex) {
 198         rangeCheck(a.length, fromIndex, toIndex);
 199         DualPivotQuicksort.sort(a, fromIndex, toIndex);
 200     }
 201 
 202     /**
 203      * Sorts the specified array into ascending numerical order.
 204      *
 205      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 206      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 207      * offers O(n log(n)) performance on all data sets, and is typically
 208      * faster than traditional (one-pivot) Quicksort implementations.
 209      *
 210      * @param a the array to be sorted
 211      */
 212     public static void sort(char[] a) {
 213         DualPivotQuicksort.sort(a, 0, a.length);
 214     }
 215 
 216     /**
 217      * Sorts the specified range of the array into ascending order. The range
 218      * to be sorted extends from the index {@code fromIndex}, inclusive, to
 219      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
 220      * the range to be sorted is empty.
 221      *
 222      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 223      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 224      * offers O(n log(n)) performance on all data sets, and is typically
 225      * faster than traditional (one-pivot) Quicksort implementations.
 226      *
 227      * @param a the array to be sorted
 228      * @param fromIndex the index of the first element, inclusive, to be sorted
 229      * @param toIndex the index of the last element, exclusive, to be sorted
 230      *
 231      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 232      * @throws ArrayIndexOutOfBoundsException
 233      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 234      */
 235     public static void sort(char[] a, int fromIndex, int toIndex) {
 236         rangeCheck(a.length, fromIndex, toIndex);
 237         DualPivotQuicksort.sort(a, fromIndex, toIndex);
 238     }
 239 
 240     /**
 241      * Sorts the specified array into ascending numerical order.
 242      *
 243      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 244      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 245      * offers O(n log(n)) performance on all data sets, and is typically
 246      * faster than traditional (one-pivot) Quicksort implementations.
 247      *
 248      * @param a the array to be sorted
 249      */
 250     public static void sort(byte[] a) {
 251         DualPivotQuicksort.sort(a, 0, a.length);
 252     }
 253 
 254     /**
 255      * Sorts the specified range of the array into ascending order. The range
 256      * to be sorted extends from the index {@code fromIndex}, inclusive, to
 257      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
 258      * the range to be sorted is empty.
 259      *
 260      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 261      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 262      * offers O(n log(n)) performance on all data sets, and is typically
 263      * faster than traditional (one-pivot) Quicksort implementations.
 264      *
 265      * @param a the array to be sorted
 266      * @param fromIndex the index of the first element, inclusive, to be sorted
 267      * @param toIndex the index of the last element, exclusive, to be sorted
 268      *
 269      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 270      * @throws ArrayIndexOutOfBoundsException
 271      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 272      */
 273     public static void sort(byte[] a, int fromIndex, int toIndex) {
 274         rangeCheck(a.length, fromIndex, toIndex);
 275         DualPivotQuicksort.sort(a, fromIndex, toIndex);
 276     }
 277 
 278     /**
 279      * Sorts the specified array into ascending numerical order.
 280      *
 281      * <p>The {@code <} relation does not provide a total order on all float
 282      * values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
 283      * value compares neither less than, greater than, nor equal to any value,
 284      * even itself. This method uses the total order imposed by the method
 285      * {@link Float#compareTo}: {@code -0.0f} is treated as less than value
 286      * {@code 0.0f} and {@code Float.NaN} is considered greater than any
 287      * other value and all {@code Float.NaN} values are considered equal.
 288      *
 289      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 290      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 291      * offers O(n log(n)) performance on all data sets, and is typically
 292      * faster than traditional (one-pivot) Quicksort implementations.
 293      *
 294      * @param a the array to be sorted
 295      */
 296     public static void sort(float[] a) {
 297         DualPivotQuicksort.sort(a, 0, 0, a.length);
 298     }
 299 
 300     /**
 301      * Sorts the specified range of the array into ascending order. The range
 302      * to be sorted extends from the index {@code fromIndex}, inclusive, to
 303      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
 304      * the range to be sorted is empty.
 305      *
 306      * <p>The {@code <} relation does not provide a total order on all float
 307      * values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
 308      * value compares neither less than, greater than, nor equal to any value,
 309      * even itself. This method uses the total order imposed by the method
 310      * {@link Float#compareTo}: {@code -0.0f} is treated as less than value
 311      * {@code 0.0f} and {@code Float.NaN} is considered greater than any
 312      * other value and all {@code Float.NaN} values are considered equal.
 313      *
 314      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 315      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 316      * offers O(n log(n)) performance on all data sets, and is typically
 317      * faster than traditional (one-pivot) Quicksort implementations.
 318      *
 319      * @param a the array to be sorted
 320      * @param fromIndex the index of the first element, inclusive, to be sorted
 321      * @param toIndex the index of the last element, exclusive, to be sorted
 322      *
 323      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 324      * @throws ArrayIndexOutOfBoundsException
 325      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 326      */
 327     public static void sort(float[] a, int fromIndex, int toIndex) {
 328         rangeCheck(a.length, fromIndex, toIndex);
 329         DualPivotQuicksort.sort(a, 0, fromIndex, toIndex);
 330     }
 331 
 332     /**
 333      * Sorts the specified array into ascending numerical order.
 334      *
 335      * <p>The {@code <} relation does not provide a total order on all double
 336      * values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
 337      * value compares neither less than, greater than, nor equal to any value,
 338      * even itself. This method uses the total order imposed by the method
 339      * {@link Double#compareTo}: {@code -0.0d} is treated as less than value
 340      * {@code 0.0d} and {@code Double.NaN} is considered greater than any
 341      * other value and all {@code Double.NaN} values are considered equal.
 342      *
 343      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 344      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 345      * offers O(n log(n)) performance on all data sets, and is typically
 346      * faster than traditional (one-pivot) Quicksort implementations.
 347      *
 348      * @param a the array to be sorted
 349      */
 350     public static void sort(double[] a) {
 351         DualPivotQuicksort.sort(a, 0, 0, a.length);
 352     }
 353 
 354     /**
 355      * Sorts the specified range of the array into ascending order. The range
 356      * to be sorted extends from the index {@code fromIndex}, inclusive, to
 357      * the index {@code toIndex}, exclusive. If {@code fromIndex == toIndex},
 358      * the range to be sorted is empty.
 359      *
 360      * <p>The {@code <} relation does not provide a total order on all double
 361      * values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
 362      * value compares neither less than, greater than, nor equal to any value,
 363      * even itself. This method uses the total order imposed by the method
 364      * {@link Double#compareTo}: {@code -0.0d} is treated as less than value
 365      * {@code 0.0d} and {@code Double.NaN} is considered greater than any
 366      * other value and all {@code Double.NaN} values are considered equal.
 367      *
 368      * @implNote The sorting algorithm is a Dual-Pivot Quicksort
 369      * by Vladimir Yaroslavskiy, Jon Bentley, and Joshua Bloch. This algorithm
 370      * offers O(n log(n)) performance on all data sets, and is typically
 371      * faster than traditional (one-pivot) Quicksort implementations.
 372      *
 373      * @param a the array to be sorted
 374      * @param fromIndex the index of the first element, inclusive, to be sorted
 375      * @param toIndex the index of the last element, exclusive, to be sorted
 376      *
 377      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 378      * @throws ArrayIndexOutOfBoundsException
 379      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 380      */
 381     public static void sort(double[] a, int fromIndex, int toIndex) {
 382         rangeCheck(a.length, fromIndex, toIndex);
 383         DualPivotQuicksort.sort(a, 0, fromIndex, toIndex);
 384     }
 385 
 386     /**
 387      * Sorts the specified array into ascending numerical order.
 388      *
 389      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 390      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 391      * offers O(n log(n)) performance on all data sets, and is typically
 392      * faster than traditional (one-pivot) Quicksort implementations.
 393      *
 394      * @param a the array to be sorted
 395      *
 396      * @since 1.8
 397      */
 398     public static void parallelSort(byte[] a) {
 399         DualPivotQuicksort.sort(a, 0, a.length);
 400     }
 401 
 402     /**
 403      * Sorts the specified range of the array into ascending numerical order.
 404      * The range to be sorted extends from the index {@code fromIndex},
 405      * inclusive, to the index {@code toIndex}, exclusive. If
 406      * {@code fromIndex == toIndex}, the range to be sorted is empty.
 407      *
 408      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 409      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 410      * offers O(n log(n)) performance on all data sets, and is typically
 411      * faster than traditional (one-pivot) Quicksort implementations.
 412      *
 413      * @param a the array to be sorted
 414      * @param fromIndex the index of the first element, inclusive, to be sorted
 415      * @param toIndex the index of the last element, exclusive, to be sorted
 416      *
 417      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 418      * @throws ArrayIndexOutOfBoundsException
 419      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 420      *
 421      * @since 1.8
 422      */
 423     public static void parallelSort(byte[] a, int fromIndex, int toIndex) {
 424         rangeCheck(a.length, fromIndex, toIndex);
 425         DualPivotQuicksort.sort(a, fromIndex, toIndex);
 426     }
 427 
 428     /**
 429      * Sorts the specified array into ascending numerical order.
 430      *
 431      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 432      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 433      * offers O(n log(n)) performance on all data sets, and is typically
 434      * faster than traditional (one-pivot) Quicksort implementations.
 435      *
 436      * @param a the array to be sorted
 437      *
 438      * @since 1.8
 439      */
 440     public static void parallelSort(char[] a) {
 441         DualPivotQuicksort.sort(a, 0, a.length);
 442     }
 443 
 444     /**
 445      * Sorts the specified range of the array into ascending numerical order.
 446      * The range to be sorted extends from the index {@code fromIndex},
 447      * inclusive, to the index {@code toIndex}, exclusive. If
 448      * {@code fromIndex == toIndex}, the range to be sorted is empty.
 449      *
 450      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 451      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 452      * offers O(n log(n)) performance on all data sets, and is typically
 453      * faster than traditional (one-pivot) Quicksort implementations.
 454      *
 455      * @param a the array to be sorted
 456      * @param fromIndex the index of the first element, inclusive, to be sorted
 457      * @param toIndex the index of the last element, exclusive, to be sorted
 458      *
 459      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 460      * @throws ArrayIndexOutOfBoundsException
 461      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 462      *
 463      * @since 1.8
 464      */
 465     public static void parallelSort(char[] a, int fromIndex, int toIndex) {
 466         rangeCheck(a.length, fromIndex, toIndex);
 467         DualPivotQuicksort.sort(a, fromIndex, toIndex);
 468     }
 469 
 470     /**
 471      * Sorts the specified array into ascending numerical order.
 472      *
 473      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 474      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 475      * offers O(n log(n)) performance on all data sets, and is typically
 476      * faster than traditional (one-pivot) Quicksort implementations.
 477      *
 478      * @param a the array to be sorted
 479      *
 480      * @since 1.8
 481      */
 482     public static void parallelSort(short[] a) {
 483         DualPivotQuicksort.sort(a, 0, a.length);
 484     }
 485 
 486     /**
 487      * Sorts the specified range of the array into ascending numerical order.
 488      * The range to be sorted extends from the index {@code fromIndex},
 489      * inclusive, to the index {@code toIndex}, exclusive. If
 490      * {@code fromIndex == toIndex}, the range to be sorted is empty.
 491      *
 492      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 493      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 494      * offers O(n log(n)) performance on all data sets, and is typically
 495      * faster than traditional (one-pivot) Quicksort implementations.
 496      *
 497      * @param a the array to be sorted
 498      * @param fromIndex the index of the first element, inclusive, to be sorted
 499      * @param toIndex the index of the last element, exclusive, to be sorted
 500      *
 501      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 502      * @throws ArrayIndexOutOfBoundsException
 503      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 504      *
 505      * @since 1.8
 506      */
 507     public static void parallelSort(short[] a, int fromIndex, int toIndex) {
 508         rangeCheck(a.length, fromIndex, toIndex);
 509         DualPivotQuicksort.sort(a, fromIndex, toIndex);
 510     }
 511 
 512     /**
 513      * Sorts the specified array into ascending numerical order.
 514      *
 515      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 516      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 517      * offers O(n log(n)) performance on all data sets, and is typically
 518      * faster than traditional (one-pivot) Quicksort implementations.
 519      *
 520      * @param a the array to be sorted
 521      *
 522      * @since 1.8
 523      */
 524     public static void parallelSort(int[] a) {
 525         DualPivotQuicksort.sort(a, ForkJoinPool.getCommonPoolParallelism(), 0, a.length);
 526     }
 527 
 528     /**
 529      * Sorts the specified range of the array into ascending numerical order.
 530      * The range to be sorted extends from the index {@code fromIndex},
 531      * inclusive, to the index {@code toIndex}, exclusive. If
 532      * {@code fromIndex == toIndex}, the range to be sorted is empty.
 533      *
 534      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 535      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 536      * offers O(n log(n)) performance on all data sets, and is typically
 537      * faster than traditional (one-pivot) Quicksort implementations.
 538      *
 539      * @param a the array to be sorted
 540      * @param fromIndex the index of the first element, inclusive, to be sorted
 541      * @param toIndex the index of the last element, exclusive, to be sorted
 542      *
 543      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 544      * @throws ArrayIndexOutOfBoundsException
 545      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 546      *
 547      * @since 1.8
 548      */
 549     public static void parallelSort(int[] a, int fromIndex, int toIndex) {
 550         rangeCheck(a.length, fromIndex, toIndex);
 551         DualPivotQuicksort.sort(a, ForkJoinPool.getCommonPoolParallelism(), fromIndex, toIndex);
 552     }
 553 
 554     /**
 555      * Sorts the specified array into ascending numerical order.
 556      *
 557      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 558      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 559      * offers O(n log(n)) performance on all data sets, and is typically
 560      * faster than traditional (one-pivot) Quicksort implementations.
 561      *
 562      * @param a the array to be sorted
 563      *
 564      * @since 1.8
 565      */
 566     public static void parallelSort(long[] a) {
 567         DualPivotQuicksort.sort(a, ForkJoinPool.getCommonPoolParallelism(), 0, a.length);
 568     }
 569 
 570     /**
 571      * Sorts the specified range of the array into ascending numerical order.
 572      * The range to be sorted extends from the index {@code fromIndex},
 573      * inclusive, to the index {@code toIndex}, exclusive. If
 574      * {@code fromIndex == toIndex}, the range to be sorted is empty.
 575      *
 576      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 577      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 578      * offers O(n log(n)) performance on all data sets, and is typically
 579      * faster than traditional (one-pivot) Quicksort implementations.
 580      *
 581      * @param a the array to be sorted
 582      * @param fromIndex the index of the first element, inclusive, to be sorted
 583      * @param toIndex the index of the last element, exclusive, to be sorted
 584      *
 585      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 586      * @throws ArrayIndexOutOfBoundsException
 587      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 588      *
 589      * @since 1.8
 590      */
 591     public static void parallelSort(long[] a, int fromIndex, int toIndex) {
 592         rangeCheck(a.length, fromIndex, toIndex);
 593         DualPivotQuicksort.sort(a, ForkJoinPool.getCommonPoolParallelism(), fromIndex, toIndex);
 594     }
 595 
 596     /**
 597      * Sorts the specified array into ascending numerical order.
 598      *
 599      * <p>The {@code <} relation does not provide a total order on all float
 600      * values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
 601      * value compares neither less than, greater than, nor equal to any value,
 602      * even itself. This method uses the total order imposed by the method
 603      * {@link Float#compareTo}: {@code -0.0f} is treated as less than value
 604      * {@code 0.0f} and {@code Float.NaN} is considered greater than any
 605      * other value and all {@code Float.NaN} values are considered equal.
 606      *
 607      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 608      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 609      * offers O(n log(n)) performance on all data sets, and is typically
 610      * faster than traditional (one-pivot) Quicksort implementations.
 611      *
 612      * @param a the array to be sorted
 613      *
 614      * @since 1.8
 615      */
 616     public static void parallelSort(float[] a) {
 617         DualPivotQuicksort.sort(a, ForkJoinPool.getCommonPoolParallelism(), 0, a.length);
 618     }
 619 
 620     /**
 621      * Sorts the specified range of the array into ascending numerical order.
 622      * The range to be sorted extends from the index {@code fromIndex},
 623      * inclusive, to the index {@code toIndex}, exclusive. If
 624      * {@code fromIndex == toIndex}, the range to be sorted is empty.
 625      *
 626      * <p>The {@code <} relation does not provide a total order on all float
 627      * values: {@code -0.0f == 0.0f} is {@code true} and a {@code Float.NaN}
 628      * value compares neither less than, greater than, nor equal to any value,
 629      * even itself. This method uses the total order imposed by the method
 630      * {@link Float#compareTo}: {@code -0.0f} is treated as less than value
 631      * {@code 0.0f} and {@code Float.NaN} is considered greater than any
 632      * other value and all {@code Float.NaN} values are considered equal.
 633      *
 634      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 635      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 636      * offers O(n log(n)) performance on all data sets, and is typically
 637      * faster than traditional (one-pivot) Quicksort implementations.
 638      *
 639      * @param a the array to be sorted
 640      * @param fromIndex the index of the first element, inclusive, to be sorted
 641      * @param toIndex the index of the last element, exclusive, to be sorted
 642      *
 643      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 644      * @throws ArrayIndexOutOfBoundsException
 645      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 646      *
 647      * @since 1.8
 648      */
 649     public static void parallelSort(float[] a, int fromIndex, int toIndex) {
 650         rangeCheck(a.length, fromIndex, toIndex);
 651         DualPivotQuicksort.sort(a, ForkJoinPool.getCommonPoolParallelism(), fromIndex, toIndex);
 652     }
 653 
 654     /**
 655      * Sorts the specified array into ascending numerical order.
 656      *
 657      * <p>The {@code <} relation does not provide a total order on all double
 658      * values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
 659      * value compares neither less than, greater than, nor equal to any value,
 660      * even itself. This method uses the total order imposed by the method
 661      * {@link Double#compareTo}: {@code -0.0d} is treated as less than value
 662      * {@code 0.0d} and {@code Double.NaN} is considered greater than any
 663      * other value and all {@code Double.NaN} values are considered equal.
 664      *
 665      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 666      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 667      * offers O(n log(n)) performance on all data sets, and is typically
 668      * faster than traditional (one-pivot) Quicksort implementations.
 669      *
 670      * @param a the array to be sorted
 671      *
 672      * @since 1.8
 673      */
 674     public static void parallelSort(double[] a) {
 675         DualPivotQuicksort.sort(a, ForkJoinPool.getCommonPoolParallelism(), 0, a.length);
 676     }
 677 
 678     /**
 679      * Sorts the specified range of the array into ascending numerical order.
 680      * The range to be sorted extends from the index {@code fromIndex},
 681      * inclusive, to the index {@code toIndex}, exclusive. If
 682      * {@code fromIndex == toIndex}, the range to be sorted is empty.
 683      *
 684      * <p>The {@code <} relation does not provide a total order on all double
 685      * values: {@code -0.0d == 0.0d} is {@code true} and a {@code Double.NaN}
 686      * value compares neither less than, greater than, nor equal to any value,
 687      * even itself. This method uses the total order imposed by the method
 688      * {@link Double#compareTo}: {@code -0.0d} is treated as less than value
 689      * {@code 0.0d} and {@code Double.NaN} is considered greater than any
 690      * other value and all {@code Double.NaN} values are considered equal.
 691      *
 692      * @implNote The sorting algorithm is a Dual-Pivot Quicksort by
 693      * Vladimir Yaroslavskiy, Jon Bentley and Josh Bloch. This algorithm
 694      * offers O(n log(n)) performance on all data sets, and is typically
 695      * faster than traditional (one-pivot) Quicksort implementations.
 696      *
 697      * @param a the array to be sorted
 698      * @param fromIndex the index of the first element, inclusive, to be sorted
 699      * @param toIndex the index of the last element, exclusive, to be sorted
 700      *
 701      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
 702      * @throws ArrayIndexOutOfBoundsException
 703      *     if {@code fromIndex < 0} or {@code toIndex > a.length}
 704      *
 705      * @since 1.8
 706      */
 707     public static void parallelSort(double[] a, int fromIndex, int toIndex) {
 708         rangeCheck(a.length, fromIndex, toIndex);
 709         DualPivotQuicksort.sort(a, ForkJoinPool.getCommonPoolParallelism(), fromIndex, toIndex);
 710     }
 711 
 712     /**
 713      * Checks that {@code fromIndex} and {@code toIndex} are in
 714      * the range and throws an exception if they aren't.
 715      */
 716     static void rangeCheck(int arrayLength, int fromIndex, int toIndex) {
 717         if (fromIndex > toIndex) {
 718             throw new IllegalArgumentException(
 719                 "fromIndex(" + fromIndex + ") > toIndex(" + toIndex + ")");
 720         }
 721         if (fromIndex < 0) {
 722             throw new ArrayIndexOutOfBoundsException(fromIndex);
 723         }
 724         if (toIndex > arrayLength) {
 725             throw new ArrayIndexOutOfBoundsException(toIndex);
 726         }
 727     }
 728 
 729     /**
 730      * A comparator that implements the natural ordering of a group of
 731      * mutually comparable elements. May be used when a supplied
 732      * comparator is null. To simplify code-sharing within underlying
 733      * implementations, the compare method only declares type Object
 734      * for its second argument.
 735      *
 736      * Arrays class implementor's note: It is an empirical matter
 737      * whether ComparableTimSort offers any performance benefit over
 738      * TimSort used with this comparator.  If not, you are better off
 739      * deleting or bypassing ComparableTimSort.  There is currently no
 740      * empirical case for separating them for parallel sorting, so all
 741      * public Object parallelSort methods use the same comparator
 742      * based implementation.
 743      */
 744     static final class NaturalOrder implements Comparator<Object> {
 745         @SuppressWarnings("unchecked")
 746         public int compare(Object first, Object second) {
 747             return ((Comparable<Object>)first).compareTo(second);
 748         }
 749         static final NaturalOrder INSTANCE = new NaturalOrder();
 750     }
 751 
 752     /**
 753      * The minimum array length below which a parallel sorting
 754      * algorithm will not further partition the sorting task. Using
 755      * smaller sizes typically results in memory contention across
 756      * tasks that makes parallel speedups unlikely.
 757      */
 758     private static final int MIN_ARRAY_SORT_GRAN = 1 << 13;
 759 
 760     /**
 761      * Sorts the specified array of objects into ascending order, according
 762      * to the {@linkplain Comparable natural ordering} of its elements.
 763      * All elements in the array must implement the {@link Comparable}
 764      * interface.  Furthermore, all elements in the array must be
 765      * <i>mutually comparable</i> (that is, {@code e1.compareTo(e2)} must
 766      * not throw a {@code ClassCastException} for any elements {@code e1}
 767      * and {@code e2} in the array).
 768      *
 769      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
 770      * not be reordered as a result of the sort.
 771      *
 772      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
 773      * array into sub-arrays that are themselves sorted and then merged. When
 774      * the sub-array length reaches a minimum granularity, the sub-array is
 775      * sorted using the appropriate {@link Arrays#sort(Object[]) Arrays.sort}
 776      * method. If the length of the specified array is less than the minimum
 777      * granularity, then it is sorted using the appropriate {@link
 778      * Arrays#sort(Object[]) Arrays.sort} method. The algorithm requires a
 779      * working space no greater than the size of the original array. The
 780      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
 781      * execute any parallel tasks.
 782      *
 783      * @param <T> the class of the objects to be sorted
 784      * @param a the array to be sorted
 785      *
 786      * @throws ClassCastException if the array contains elements that are not
 787      *         <i>mutually comparable</i> (for example, strings and integers)
 788      * @throws IllegalArgumentException (optional) if the natural
 789      *         ordering of the array elements is found to violate the
 790      *         {@link Comparable} contract
 791      *
 792      * @since 1.8
 793      */
 794     @SuppressWarnings("unchecked")
 795     public static <T extends Comparable<? super T>> void parallelSort(T[] a) {
 796         int n = a.length, p, g;
 797         if (n <= MIN_ARRAY_SORT_GRAN ||
 798             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
 799             TimSort.sort(a, 0, n, NaturalOrder.INSTANCE, null, 0, 0);
 800         else
 801             new ArraysParallelSortHelpers.FJObject.Sorter<>
 802                 (null, a,
 803                  (T[])Array.newInstance(a.getClass().getComponentType(), n),
 804                  0, n, 0, ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
 805                  MIN_ARRAY_SORT_GRAN : g, NaturalOrder.INSTANCE).invoke();
 806     }
 807 
 808     /**
 809      * Sorts the specified range of the specified array of objects into
 810      * ascending order, according to the
 811      * {@linkplain Comparable natural ordering} of its
 812      * elements.  The range to be sorted extends from index
 813      * {@code fromIndex}, inclusive, to index {@code toIndex}, exclusive.
 814      * (If {@code fromIndex==toIndex}, the range to be sorted is empty.)  All
 815      * elements in this range must implement the {@link Comparable}
 816      * interface.  Furthermore, all elements in this range must be <i>mutually
 817      * comparable</i> (that is, {@code e1.compareTo(e2)} must not throw a
 818      * {@code ClassCastException} for any elements {@code e1} and
 819      * {@code e2} in the array).
 820      *
 821      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
 822      * not be reordered as a result of the sort.
 823      *
 824      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
 825      * array into sub-arrays that are themselves sorted and then merged. When
 826      * the sub-array length reaches a minimum granularity, the sub-array is
 827      * sorted using the appropriate {@link Arrays#sort(Object[]) Arrays.sort}
 828      * method. If the length of the specified array is less than the minimum
 829      * granularity, then it is sorted using the appropriate {@link
 830      * Arrays#sort(Object[]) Arrays.sort} method. The algorithm requires a working
 831      * space no greater than the size of the specified range of the original
 832      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
 833      * used to execute any parallel tasks.
 834      *
 835      * @param <T> the class of the objects to be sorted
 836      * @param a the array to be sorted
 837      * @param fromIndex the index of the first element (inclusive) to be
 838      *        sorted
 839      * @param toIndex the index of the last element (exclusive) to be sorted
 840      * @throws IllegalArgumentException if {@code fromIndex > toIndex} or
 841      *         (optional) if the natural ordering of the array elements is
 842      *         found to violate the {@link Comparable} contract
 843      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
 844      *         {@code toIndex > a.length}
 845      * @throws ClassCastException if the array contains elements that are
 846      *         not <i>mutually comparable</i> (for example, strings and
 847      *         integers).
 848      *
 849      * @since 1.8
 850      */
 851     @SuppressWarnings("unchecked")
 852     public static <T extends Comparable<? super T>>
 853     void parallelSort(T[] a, int fromIndex, int toIndex) {
 854         rangeCheck(a.length, fromIndex, toIndex);
 855         int n = toIndex - fromIndex, p, g;
 856         if (n <= MIN_ARRAY_SORT_GRAN ||
 857             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
 858             TimSort.sort(a, fromIndex, toIndex, NaturalOrder.INSTANCE, null, 0, 0);
 859         else
 860             new ArraysParallelSortHelpers.FJObject.Sorter<>
 861                 (null, a,
 862                  (T[])Array.newInstance(a.getClass().getComponentType(), n),
 863                  fromIndex, n, 0, ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
 864                  MIN_ARRAY_SORT_GRAN : g, NaturalOrder.INSTANCE).invoke();
 865     }
 866 
 867     /**
 868      * Sorts the specified array of objects according to the order induced by
 869      * the specified comparator.  All elements in the array must be
 870      * <i>mutually comparable</i> by the specified comparator (that is,
 871      * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
 872      * for any elements {@code e1} and {@code e2} in the array).
 873      *
 874      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
 875      * not be reordered as a result of the sort.
 876      *
 877      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
 878      * array into sub-arrays that are themselves sorted and then merged. When
 879      * the sub-array length reaches a minimum granularity, the sub-array is
 880      * sorted using the appropriate {@link Arrays#sort(Object[]) Arrays.sort}
 881      * method. If the length of the specified array is less than the minimum
 882      * granularity, then it is sorted using the appropriate {@link
 883      * Arrays#sort(Object[]) Arrays.sort} method. The algorithm requires a
 884      * working space no greater than the size of the original array. The
 885      * {@link ForkJoinPool#commonPool() ForkJoin common pool} is used to
 886      * execute any parallel tasks.
 887      *
 888      * @param <T> the class of the objects to be sorted
 889      * @param a the array to be sorted
 890      * @param cmp the comparator to determine the order of the array.  A
 891      *        {@code null} value indicates that the elements'
 892      *        {@linkplain Comparable natural ordering} should be used.
 893      * @throws ClassCastException if the array contains elements that are
 894      *         not <i>mutually comparable</i> using the specified comparator
 895      * @throws IllegalArgumentException (optional) if the comparator is
 896      *         found to violate the {@link java.util.Comparator} contract
 897      *
 898      * @since 1.8
 899      */
 900     @SuppressWarnings("unchecked")
 901     public static <T> void parallelSort(T[] a, Comparator<? super T> cmp) {
 902         if (cmp == null)
 903             cmp = NaturalOrder.INSTANCE;
 904         int n = a.length, p, g;
 905         if (n <= MIN_ARRAY_SORT_GRAN ||
 906             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
 907             TimSort.sort(a, 0, n, cmp, null, 0, 0);
 908         else
 909             new ArraysParallelSortHelpers.FJObject.Sorter<>
 910                 (null, a,
 911                  (T[])Array.newInstance(a.getClass().getComponentType(), n),
 912                  0, n, 0, ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
 913                  MIN_ARRAY_SORT_GRAN : g, cmp).invoke();
 914     }
 915 
 916     /**
 917      * Sorts the specified range of the specified array of objects according
 918      * to the order induced by the specified comparator.  The range to be
 919      * sorted extends from index {@code fromIndex}, inclusive, to index
 920      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
 921      * range to be sorted is empty.)  All elements in the range must be
 922      * <i>mutually comparable</i> by the specified comparator (that is,
 923      * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
 924      * for any elements {@code e1} and {@code e2} in the range).
 925      *
 926      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
 927      * not be reordered as a result of the sort.
 928      *
 929      * @implNote The sorting algorithm is a parallel sort-merge that breaks the
 930      * array into sub-arrays that are themselves sorted and then merged. When
 931      * the sub-array length reaches a minimum granularity, the sub-array is
 932      * sorted using the appropriate {@link Arrays#sort(Object[]) Arrays.sort}
 933      * method. If the length of the specified array is less than the minimum
 934      * granularity, then it is sorted using the appropriate {@link
 935      * Arrays#sort(Object[]) Arrays.sort} method. The algorithm requires a working
 936      * space no greater than the size of the specified range of the original
 937      * array. The {@link ForkJoinPool#commonPool() ForkJoin common pool} is
 938      * used to execute any parallel tasks.
 939      *
 940      * @param <T> the class of the objects to be sorted
 941      * @param a the array to be sorted
 942      * @param fromIndex the index of the first element (inclusive) to be
 943      *        sorted
 944      * @param toIndex the index of the last element (exclusive) to be sorted
 945      * @param cmp the comparator to determine the order of the array.  A
 946      *        {@code null} value indicates that the elements'
 947      *        {@linkplain Comparable natural ordering} should be used.
 948      * @throws IllegalArgumentException if {@code fromIndex > toIndex} or
 949      *         (optional) if the natural ordering of the array elements is
 950      *         found to violate the {@link Comparable} contract
 951      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
 952      *         {@code toIndex > a.length}
 953      * @throws ClassCastException if the array contains elements that are
 954      *         not <i>mutually comparable</i> (for example, strings and
 955      *         integers).
 956      *
 957      * @since 1.8
 958      */
 959     @SuppressWarnings("unchecked")
 960     public static <T> void parallelSort(T[] a, int fromIndex, int toIndex,
 961                                         Comparator<? super T> cmp) {
 962         rangeCheck(a.length, fromIndex, toIndex);
 963         if (cmp == null)
 964             cmp = NaturalOrder.INSTANCE;
 965         int n = toIndex - fromIndex, p, g;
 966         if (n <= MIN_ARRAY_SORT_GRAN ||
 967             (p = ForkJoinPool.getCommonPoolParallelism()) == 1)
 968             TimSort.sort(a, fromIndex, toIndex, cmp, null, 0, 0);
 969         else
 970             new ArraysParallelSortHelpers.FJObject.Sorter<>
 971                 (null, a,
 972                  (T[])Array.newInstance(a.getClass().getComponentType(), n),
 973                  fromIndex, n, 0, ((g = n / (p << 2)) <= MIN_ARRAY_SORT_GRAN) ?
 974                  MIN_ARRAY_SORT_GRAN : g, cmp).invoke();
 975     }
 976 
 977     /*
 978      * Sorting of complex type arrays.
 979      */
 980 
 981     /**
 982      * Old merge sort implementation can be selected (for
 983      * compatibility with broken comparators) using a system property.
 984      * Cannot be a static boolean in the enclosing class due to
 985      * circular dependencies. To be removed in a future release.
 986      */
 987     static final class LegacyMergeSort {
 988         @SuppressWarnings("removal")
 989         private static final boolean userRequested =
 990             java.security.AccessController.doPrivileged(
 991                 new sun.security.action.GetBooleanAction(
 992                     "java.util.Arrays.useLegacyMergeSort")).booleanValue();
 993     }
 994 
 995     /**
 996      * Sorts the specified array of objects into ascending order, according
 997      * to the {@linkplain Comparable natural ordering} of its elements.
 998      * All elements in the array must implement the {@link Comparable}
 999      * interface.  Furthermore, all elements in the array must be
1000      * <i>mutually comparable</i> (that is, {@code e1.compareTo(e2)} must
1001      * not throw a {@code ClassCastException} for any elements {@code e1}
1002      * and {@code e2} in the array).
1003      *
1004      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
1005      * not be reordered as a result of the sort.
1006      *
1007      * <p>Implementation note: This implementation is a stable, adaptive,
1008      * iterative mergesort that requires far fewer than n lg(n) comparisons
1009      * when the input array is partially sorted, while offering the
1010      * performance of a traditional mergesort when the input array is
1011      * randomly ordered.  If the input array is nearly sorted, the
1012      * implementation requires approximately n comparisons.  Temporary
1013      * storage requirements vary from a small constant for nearly sorted
1014      * input arrays to n/2 object references for randomly ordered input
1015      * arrays.
1016      *
1017      * <p>The implementation takes equal advantage of ascending and
1018      * descending order in its input array, and can take advantage of
1019      * ascending and descending order in different parts of the same
1020      * input array.  It is well-suited to merging two or more sorted arrays:
1021      * simply concatenate the arrays and sort the resulting array.
1022      *
1023      * <p>The implementation was adapted from Tim Peters's list sort for Python
1024      * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
1025      * TimSort</a>).  It uses techniques from Peter McIlroy's "Optimistic
1026      * Sorting and Information Theoretic Complexity", in Proceedings of the
1027      * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
1028      * January 1993.
1029      *
1030      * @param a the array to be sorted
1031      * @throws ClassCastException if the array contains elements that are not
1032      *         <i>mutually comparable</i> (for example, strings and integers)
1033      * @throws IllegalArgumentException (optional) if the natural
1034      *         ordering of the array elements is found to violate the
1035      *         {@link Comparable} contract
1036      */
1037     public static void sort(Object[] a) {
1038         if (LegacyMergeSort.userRequested)
1039             legacyMergeSort(a);
1040         else
1041             ComparableTimSort.sort(a, 0, a.length, null, 0, 0);
1042     }
1043 
1044     /** To be removed in a future release. */
1045     private static void legacyMergeSort(Object[] a) {
1046         Object[] aux = a.clone();
1047         mergeSort(aux, a, 0, a.length, 0);
1048     }
1049 
1050     /**
1051      * Sorts the specified range of the specified array of objects into
1052      * ascending order, according to the
1053      * {@linkplain Comparable natural ordering} of its
1054      * elements.  The range to be sorted extends from index
1055      * {@code fromIndex}, inclusive, to index {@code toIndex}, exclusive.
1056      * (If {@code fromIndex==toIndex}, the range to be sorted is empty.)  All
1057      * elements in this range must implement the {@link Comparable}
1058      * interface.  Furthermore, all elements in this range must be <i>mutually
1059      * comparable</i> (that is, {@code e1.compareTo(e2)} must not throw a
1060      * {@code ClassCastException} for any elements {@code e1} and
1061      * {@code e2} in the array).
1062      *
1063      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
1064      * not be reordered as a result of the sort.
1065      *
1066      * <p>Implementation note: This implementation is a stable, adaptive,
1067      * iterative mergesort that requires far fewer than n lg(n) comparisons
1068      * when the input array is partially sorted, while offering the
1069      * performance of a traditional mergesort when the input array is
1070      * randomly ordered.  If the input array is nearly sorted, the
1071      * implementation requires approximately n comparisons.  Temporary
1072      * storage requirements vary from a small constant for nearly sorted
1073      * input arrays to n/2 object references for randomly ordered input
1074      * arrays.
1075      *
1076      * <p>The implementation takes equal advantage of ascending and
1077      * descending order in its input array, and can take advantage of
1078      * ascending and descending order in different parts of the same
1079      * input array.  It is well-suited to merging two or more sorted arrays:
1080      * simply concatenate the arrays and sort the resulting array.
1081      *
1082      * <p>The implementation was adapted from Tim Peters's list sort for Python
1083      * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
1084      * TimSort</a>).  It uses techniques from Peter McIlroy's "Optimistic
1085      * Sorting and Information Theoretic Complexity", in Proceedings of the
1086      * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
1087      * January 1993.
1088      *
1089      * @param a the array to be sorted
1090      * @param fromIndex the index of the first element (inclusive) to be
1091      *        sorted
1092      * @param toIndex the index of the last element (exclusive) to be sorted
1093      * @throws IllegalArgumentException if {@code fromIndex > toIndex} or
1094      *         (optional) if the natural ordering of the array elements is
1095      *         found to violate the {@link Comparable} contract
1096      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
1097      *         {@code toIndex > a.length}
1098      * @throws ClassCastException if the array contains elements that are
1099      *         not <i>mutually comparable</i> (for example, strings and
1100      *         integers).
1101      */
1102     public static void sort(Object[] a, int fromIndex, int toIndex) {
1103         rangeCheck(a.length, fromIndex, toIndex);
1104         if (LegacyMergeSort.userRequested)
1105             legacyMergeSort(a, fromIndex, toIndex);
1106         else
1107             ComparableTimSort.sort(a, fromIndex, toIndex, null, 0, 0);
1108     }
1109 
1110     /** To be removed in a future release. */
1111     private static void legacyMergeSort(Object[] a,
1112                                         int fromIndex, int toIndex) {
1113         Object[] aux = copyOfRange(a, fromIndex, toIndex);
1114         mergeSort(aux, a, fromIndex, toIndex, -fromIndex);
1115     }
1116 
1117     /**
1118      * Tuning parameter: list size at or below which insertion sort will be
1119      * used in preference to mergesort.
1120      * To be removed in a future release.
1121      */
1122     private static final int INSERTIONSORT_THRESHOLD = 7;
1123 
1124     /**
1125      * Src is the source array that starts at index 0
1126      * Dest is the (possibly larger) array destination with a possible offset
1127      * low is the index in dest to start sorting
1128      * high is the end index in dest to end sorting
1129      * off is the offset to generate corresponding low, high in src
1130      * To be removed in a future release.
1131      */
1132     @SuppressWarnings({"unchecked", "rawtypes"})
1133     private static void mergeSort(Object[] src,
1134                                   Object[] dest,
1135                                   int low,
1136                                   int high,
1137                                   int off) {
1138         int length = high - low;
1139 
1140         // Insertion sort on smallest arrays
1141         if (length < INSERTIONSORT_THRESHOLD) {
1142             for (int i=low; i<high; i++)
1143                 for (int j=i; j>low &&
1144                          ((Comparable) dest[j-1]).compareTo(dest[j])>0; j--)
1145                     swap(dest, j, j-1);
1146             return;
1147         }
1148 
1149         // Recursively sort halves of dest into src
1150         int destLow  = low;
1151         int destHigh = high;
1152         low  += off;
1153         high += off;
1154         int mid = (low + high) >>> 1;
1155         mergeSort(dest, src, low, mid, -off);
1156         mergeSort(dest, src, mid, high, -off);
1157 
1158         // If list is already sorted, just copy from src to dest.  This is an
1159         // optimization that results in faster sorts for nearly ordered lists.
1160         if (((Comparable)src[mid-1]).compareTo(src[mid]) <= 0) {
1161             System.arraycopy(src, low, dest, destLow, length);
1162             return;
1163         }
1164 
1165         // Merge sorted halves (now in src) into dest
1166         for(int i = destLow, p = low, q = mid; i < destHigh; i++) {
1167             if (q >= high || p < mid && ((Comparable)src[p]).compareTo(src[q])<=0)
1168                 dest[i] = src[p++];
1169             else
1170                 dest[i] = src[q++];
1171         }
1172     }
1173 
1174     /**
1175      * Swaps x[a] with x[b].
1176      */
1177     private static void swap(Object[] x, int a, int b) {
1178         Object t = x[a];
1179         x[a] = x[b];
1180         x[b] = t;
1181     }
1182 
1183     /**
1184      * Sorts the specified array of objects according to the order induced by
1185      * the specified comparator.  All elements in the array must be
1186      * <i>mutually comparable</i> by the specified comparator (that is,
1187      * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
1188      * for any elements {@code e1} and {@code e2} in the array).
1189      *
1190      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
1191      * not be reordered as a result of the sort.
1192      *
1193      * <p>Implementation note: This implementation is a stable, adaptive,
1194      * iterative mergesort that requires far fewer than n lg(n) comparisons
1195      * when the input array is partially sorted, while offering the
1196      * performance of a traditional mergesort when the input array is
1197      * randomly ordered.  If the input array is nearly sorted, the
1198      * implementation requires approximately n comparisons.  Temporary
1199      * storage requirements vary from a small constant for nearly sorted
1200      * input arrays to n/2 object references for randomly ordered input
1201      * arrays.
1202      *
1203      * <p>The implementation takes equal advantage of ascending and
1204      * descending order in its input array, and can take advantage of
1205      * ascending and descending order in different parts of the same
1206      * input array.  It is well-suited to merging two or more sorted arrays:
1207      * simply concatenate the arrays and sort the resulting array.
1208      *
1209      * <p>The implementation was adapted from Tim Peters's list sort for Python
1210      * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
1211      * TimSort</a>).  It uses techniques from Peter McIlroy's "Optimistic
1212      * Sorting and Information Theoretic Complexity", in Proceedings of the
1213      * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
1214      * January 1993.
1215      *
1216      * @param <T> the class of the objects to be sorted
1217      * @param a the array to be sorted
1218      * @param c the comparator to determine the order of the array.  A
1219      *        {@code null} value indicates that the elements'
1220      *        {@linkplain Comparable natural ordering} should be used.
1221      * @throws ClassCastException if the array contains elements that are
1222      *         not <i>mutually comparable</i> using the specified comparator
1223      * @throws IllegalArgumentException (optional) if the comparator is
1224      *         found to violate the {@link Comparator} contract
1225      */
1226     public static <T> void sort(T[] a, Comparator<? super T> c) {
1227         if (c == null) {
1228             sort(a);
1229         } else {
1230             if (LegacyMergeSort.userRequested)
1231                 legacyMergeSort(a, c);
1232             else
1233                 TimSort.sort(a, 0, a.length, c, null, 0, 0);
1234         }
1235     }
1236 
1237     /** To be removed in a future release. */
1238     private static <T> void legacyMergeSort(T[] a, Comparator<? super T> c) {
1239         T[] aux = a.clone();
1240         if (c==null)
1241             mergeSort(aux, a, 0, a.length, 0);
1242         else
1243             mergeSort(aux, a, 0, a.length, 0, c);
1244     }
1245 
1246     /**
1247      * Sorts the specified range of the specified array of objects according
1248      * to the order induced by the specified comparator.  The range to be
1249      * sorted extends from index {@code fromIndex}, inclusive, to index
1250      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
1251      * range to be sorted is empty.)  All elements in the range must be
1252      * <i>mutually comparable</i> by the specified comparator (that is,
1253      * {@code c.compare(e1, e2)} must not throw a {@code ClassCastException}
1254      * for any elements {@code e1} and {@code e2} in the range).
1255      *
1256      * <p>This sort is guaranteed to be <i>stable</i>:  equal elements will
1257      * not be reordered as a result of the sort.
1258      *
1259      * <p>Implementation note: This implementation is a stable, adaptive,
1260      * iterative mergesort that requires far fewer than n lg(n) comparisons
1261      * when the input array is partially sorted, while offering the
1262      * performance of a traditional mergesort when the input array is
1263      * randomly ordered.  If the input array is nearly sorted, the
1264      * implementation requires approximately n comparisons.  Temporary
1265      * storage requirements vary from a small constant for nearly sorted
1266      * input arrays to n/2 object references for randomly ordered input
1267      * arrays.
1268      *
1269      * <p>The implementation takes equal advantage of ascending and
1270      * descending order in its input array, and can take advantage of
1271      * ascending and descending order in different parts of the same
1272      * input array.  It is well-suited to merging two or more sorted arrays:
1273      * simply concatenate the arrays and sort the resulting array.
1274      *
1275      * <p>The implementation was adapted from Tim Peters's list sort for Python
1276      * (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">
1277      * TimSort</a>).  It uses techniques from Peter McIlroy's "Optimistic
1278      * Sorting and Information Theoretic Complexity", in Proceedings of the
1279      * Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, pp 467-474,
1280      * January 1993.
1281      *
1282      * @param <T> the class of the objects to be sorted
1283      * @param a the array to be sorted
1284      * @param fromIndex the index of the first element (inclusive) to be
1285      *        sorted
1286      * @param toIndex the index of the last element (exclusive) to be sorted
1287      * @param c the comparator to determine the order of the array.  A
1288      *        {@code null} value indicates that the elements'
1289      *        {@linkplain Comparable natural ordering} should be used.
1290      * @throws ClassCastException if the array contains elements that are not
1291      *         <i>mutually comparable</i> using the specified comparator.
1292      * @throws IllegalArgumentException if {@code fromIndex > toIndex} or
1293      *         (optional) if the comparator is found to violate the
1294      *         {@link Comparator} contract
1295      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
1296      *         {@code toIndex > a.length}
1297      */
1298     public static <T> void sort(T[] a, int fromIndex, int toIndex,
1299                                 Comparator<? super T> c) {
1300         if (c == null) {
1301             sort(a, fromIndex, toIndex);
1302         } else {
1303             rangeCheck(a.length, fromIndex, toIndex);
1304             if (LegacyMergeSort.userRequested)
1305                 legacyMergeSort(a, fromIndex, toIndex, c);
1306             else
1307                 TimSort.sort(a, fromIndex, toIndex, c, null, 0, 0);
1308         }
1309     }
1310 
1311     /** To be removed in a future release. */
1312     private static <T> void legacyMergeSort(T[] a, int fromIndex, int toIndex,
1313                                             Comparator<? super T> c) {
1314         T[] aux = copyOfRange(a, fromIndex, toIndex);
1315         if (c==null)
1316             mergeSort(aux, a, fromIndex, toIndex, -fromIndex);
1317         else
1318             mergeSort(aux, a, fromIndex, toIndex, -fromIndex, c);
1319     }
1320 
1321     /**
1322      * Src is the source array that starts at index 0
1323      * Dest is the (possibly larger) array destination with a possible offset
1324      * low is the index in dest to start sorting
1325      * high is the end index in dest to end sorting
1326      * off is the offset into src corresponding to low in dest
1327      * To be removed in a future release.
1328      */
1329     @SuppressWarnings({"rawtypes", "unchecked"})
1330     private static void mergeSort(Object[] src,
1331                                   Object[] dest,
1332                                   int low, int high, int off,
1333                                   Comparator c) {
1334         int length = high - low;
1335 
1336         // Insertion sort on smallest arrays
1337         if (length < INSERTIONSORT_THRESHOLD) {
1338             for (int i=low; i<high; i++)
1339                 for (int j=i; j>low && c.compare(dest[j-1], dest[j])>0; j--)
1340                     swap(dest, j, j-1);
1341             return;
1342         }
1343 
1344         // Recursively sort halves of dest into src
1345         int destLow  = low;
1346         int destHigh = high;
1347         low  += off;
1348         high += off;
1349         int mid = (low + high) >>> 1;
1350         mergeSort(dest, src, low, mid, -off, c);
1351         mergeSort(dest, src, mid, high, -off, c);
1352 
1353         // If list is already sorted, just copy from src to dest.  This is an
1354         // optimization that results in faster sorts for nearly ordered lists.
1355         if (c.compare(src[mid-1], src[mid]) <= 0) {
1356            System.arraycopy(src, low, dest, destLow, length);
1357            return;
1358         }
1359 
1360         // Merge sorted halves (now in src) into dest
1361         for(int i = destLow, p = low, q = mid; i < destHigh; i++) {
1362             if (q >= high || p < mid && c.compare(src[p], src[q]) <= 0)
1363                 dest[i] = src[p++];
1364             else
1365                 dest[i] = src[q++];
1366         }
1367     }
1368 
1369     // Parallel prefix
1370 
1371     /**
1372      * Cumulates, in parallel, each element of the given array in place,
1373      * using the supplied function. For example if the array initially
1374      * holds {@code [2, 1, 0, 3]} and the operation performs addition,
1375      * then upon return the array holds {@code [2, 3, 3, 6]}.
1376      * Parallel prefix computation is usually more efficient than
1377      * sequential loops for large arrays.
1378      *
1379      * @param <T> the class of the objects in the array
1380      * @param array the array, which is modified in-place by this method
1381      * @param op a side-effect-free, associative function to perform the
1382      * cumulation
1383      * @throws NullPointerException if the specified array or function is null
1384      * @since 1.8
1385      */
1386     public static <T> void parallelPrefix(T[] array, BinaryOperator<T> op) {
1387         Objects.requireNonNull(op);
1388         if (array.length > 0)
1389             new ArrayPrefixHelpers.CumulateTask<>
1390                     (null, op, array, 0, array.length).invoke();
1391     }
1392 
1393     /**
1394      * Performs {@link #parallelPrefix(Object[], BinaryOperator)}
1395      * for the given subrange of the array.
1396      *
1397      * @param <T> the class of the objects in the array
1398      * @param array the array
1399      * @param fromIndex the index of the first element, inclusive
1400      * @param toIndex the index of the last element, exclusive
1401      * @param op a side-effect-free, associative function to perform the
1402      * cumulation
1403      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
1404      * @throws ArrayIndexOutOfBoundsException
1405      *     if {@code fromIndex < 0} or {@code toIndex > array.length}
1406      * @throws NullPointerException if the specified array or function is null
1407      * @since 1.8
1408      */
1409     public static <T> void parallelPrefix(T[] array, int fromIndex,
1410                                           int toIndex, BinaryOperator<T> op) {
1411         Objects.requireNonNull(op);
1412         rangeCheck(array.length, fromIndex, toIndex);
1413         if (fromIndex < toIndex)
1414             new ArrayPrefixHelpers.CumulateTask<>
1415                     (null, op, array, fromIndex, toIndex).invoke();
1416     }
1417 
1418     /**
1419      * Cumulates, in parallel, each element of the given array in place,
1420      * using the supplied function. For example if the array initially
1421      * holds {@code [2, 1, 0, 3]} and the operation performs addition,
1422      * then upon return the array holds {@code [2, 3, 3, 6]}.
1423      * Parallel prefix computation is usually more efficient than
1424      * sequential loops for large arrays.
1425      *
1426      * @param array the array, which is modified in-place by this method
1427      * @param op a side-effect-free, associative function to perform the
1428      * cumulation
1429      * @throws NullPointerException if the specified array or function is null
1430      * @since 1.8
1431      */
1432     public static void parallelPrefix(long[] array, LongBinaryOperator op) {
1433         Objects.requireNonNull(op);
1434         if (array.length > 0)
1435             new ArrayPrefixHelpers.LongCumulateTask
1436                     (null, op, array, 0, array.length).invoke();
1437     }
1438 
1439     /**
1440      * Performs {@link #parallelPrefix(long[], LongBinaryOperator)}
1441      * for the given subrange of the array.
1442      *
1443      * @param array the array
1444      * @param fromIndex the index of the first element, inclusive
1445      * @param toIndex the index of the last element, exclusive
1446      * @param op a side-effect-free, associative function to perform the
1447      * cumulation
1448      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
1449      * @throws ArrayIndexOutOfBoundsException
1450      *     if {@code fromIndex < 0} or {@code toIndex > array.length}
1451      * @throws NullPointerException if the specified array or function is null
1452      * @since 1.8
1453      */
1454     public static void parallelPrefix(long[] array, int fromIndex,
1455                                       int toIndex, LongBinaryOperator op) {
1456         Objects.requireNonNull(op);
1457         rangeCheck(array.length, fromIndex, toIndex);
1458         if (fromIndex < toIndex)
1459             new ArrayPrefixHelpers.LongCumulateTask
1460                     (null, op, array, fromIndex, toIndex).invoke();
1461     }
1462 
1463     /**
1464      * Cumulates, in parallel, each element of the given array in place,
1465      * using the supplied function. For example if the array initially
1466      * holds {@code [2.0, 1.0, 0.0, 3.0]} and the operation performs addition,
1467      * then upon return the array holds {@code [2.0, 3.0, 3.0, 6.0]}.
1468      * Parallel prefix computation is usually more efficient than
1469      * sequential loops for large arrays.
1470      *
1471      * <p> Because floating-point operations may not be strictly associative,
1472      * the returned result may not be identical to the value that would be
1473      * obtained if the operation was performed sequentially.
1474      *
1475      * @param array the array, which is modified in-place by this method
1476      * @param op a side-effect-free function to perform the cumulation
1477      * @throws NullPointerException if the specified array or function is null
1478      * @since 1.8
1479      */
1480     public static void parallelPrefix(double[] array, DoubleBinaryOperator op) {
1481         Objects.requireNonNull(op);
1482         if (array.length > 0)
1483             new ArrayPrefixHelpers.DoubleCumulateTask
1484                     (null, op, array, 0, array.length).invoke();
1485     }
1486 
1487     /**
1488      * Performs {@link #parallelPrefix(double[], DoubleBinaryOperator)}
1489      * for the given subrange of the array.
1490      *
1491      * @param array the array
1492      * @param fromIndex the index of the first element, inclusive
1493      * @param toIndex the index of the last element, exclusive
1494      * @param op a side-effect-free, associative function to perform the
1495      * cumulation
1496      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
1497      * @throws ArrayIndexOutOfBoundsException
1498      *     if {@code fromIndex < 0} or {@code toIndex > array.length}
1499      * @throws NullPointerException if the specified array or function is null
1500      * @since 1.8
1501      */
1502     public static void parallelPrefix(double[] array, int fromIndex,
1503                                       int toIndex, DoubleBinaryOperator op) {
1504         Objects.requireNonNull(op);
1505         rangeCheck(array.length, fromIndex, toIndex);
1506         if (fromIndex < toIndex)
1507             new ArrayPrefixHelpers.DoubleCumulateTask
1508                     (null, op, array, fromIndex, toIndex).invoke();
1509     }
1510 
1511     /**
1512      * Cumulates, in parallel, each element of the given array in place,
1513      * using the supplied function. For example if the array initially
1514      * holds {@code [2, 1, 0, 3]} and the operation performs addition,
1515      * then upon return the array holds {@code [2, 3, 3, 6]}.
1516      * Parallel prefix computation is usually more efficient than
1517      * sequential loops for large arrays.
1518      *
1519      * @param array the array, which is modified in-place by this method
1520      * @param op a side-effect-free, associative function to perform the
1521      * cumulation
1522      * @throws NullPointerException if the specified array or function is null
1523      * @since 1.8
1524      */
1525     public static void parallelPrefix(int[] array, IntBinaryOperator op) {
1526         Objects.requireNonNull(op);
1527         if (array.length > 0)
1528             new ArrayPrefixHelpers.IntCumulateTask
1529                     (null, op, array, 0, array.length).invoke();
1530     }
1531 
1532     /**
1533      * Performs {@link #parallelPrefix(int[], IntBinaryOperator)}
1534      * for the given subrange of the array.
1535      *
1536      * @param array the array
1537      * @param fromIndex the index of the first element, inclusive
1538      * @param toIndex the index of the last element, exclusive
1539      * @param op a side-effect-free, associative function to perform the
1540      * cumulation
1541      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
1542      * @throws ArrayIndexOutOfBoundsException
1543      *     if {@code fromIndex < 0} or {@code toIndex > array.length}
1544      * @throws NullPointerException if the specified array or function is null
1545      * @since 1.8
1546      */
1547     public static void parallelPrefix(int[] array, int fromIndex,
1548                                       int toIndex, IntBinaryOperator op) {
1549         Objects.requireNonNull(op);
1550         rangeCheck(array.length, fromIndex, toIndex);
1551         if (fromIndex < toIndex)
1552             new ArrayPrefixHelpers.IntCumulateTask
1553                     (null, op, array, fromIndex, toIndex).invoke();
1554     }
1555 
1556     // Searching
1557 
1558     /**
1559      * Searches the specified array of longs for the specified value using the
1560      * binary search algorithm.  The array must be sorted (as
1561      * by the {@link #sort(long[])} method) prior to making this call.  If it
1562      * is not sorted, the results are undefined.  If the array contains
1563      * multiple elements with the specified value, there is no guarantee which
1564      * one will be found.
1565      *
1566      * @param a the array to be searched
1567      * @param key the value to be searched for
1568      * @return index of the search key, if it is contained in the array;
1569      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1570      *         <i>insertion point</i> is defined as the point at which the
1571      *         key would be inserted into the array: the index of the first
1572      *         element greater than the key, or {@code a.length} if all
1573      *         elements in the array are less than the specified key.  Note
1574      *         that this guarantees that the return value will be &gt;= 0 if
1575      *         and only if the key is found.
1576      */
1577     public static int binarySearch(long[] a, long key) {
1578         return binarySearch0(a, 0, a.length, key);
1579     }
1580 
1581     /**
1582      * Searches a range of
1583      * the specified array of longs for the specified value using the
1584      * binary search algorithm.
1585      * The range must be sorted (as
1586      * by the {@link #sort(long[], int, int)} method)
1587      * prior to making this call.  If it
1588      * is not sorted, the results are undefined.  If the range contains
1589      * multiple elements with the specified value, there is no guarantee which
1590      * one will be found.
1591      *
1592      * @param a the array to be searched
1593      * @param fromIndex the index of the first element (inclusive) to be
1594      *          searched
1595      * @param toIndex the index of the last element (exclusive) to be searched
1596      * @param key the value to be searched for
1597      * @return index of the search key, if it is contained in the array
1598      *         within the specified range;
1599      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1600      *         <i>insertion point</i> is defined as the point at which the
1601      *         key would be inserted into the array: the index of the first
1602      *         element in the range greater than the key,
1603      *         or {@code toIndex} if all
1604      *         elements in the range are less than the specified key.  Note
1605      *         that this guarantees that the return value will be &gt;= 0 if
1606      *         and only if the key is found.
1607      * @throws IllegalArgumentException
1608      *         if {@code fromIndex > toIndex}
1609      * @throws ArrayIndexOutOfBoundsException
1610      *         if {@code fromIndex < 0 or toIndex > a.length}
1611      * @since 1.6
1612      */
1613     public static int binarySearch(long[] a, int fromIndex, int toIndex,
1614                                    long key) {
1615         rangeCheck(a.length, fromIndex, toIndex);
1616         return binarySearch0(a, fromIndex, toIndex, key);
1617     }
1618 
1619     // Like public version, but without range checks.
1620     private static int binarySearch0(long[] a, int fromIndex, int toIndex,
1621                                      long key) {
1622         int low = fromIndex;
1623         int high = toIndex - 1;
1624 
1625         while (low <= high) {
1626             int mid = (low + high) >>> 1;
1627             long midVal = a[mid];
1628 
1629             if (midVal < key)
1630                 low = mid + 1;
1631             else if (midVal > key)
1632                 high = mid - 1;
1633             else
1634                 return mid; // key found
1635         }
1636         return -(low + 1);  // key not found.
1637     }
1638 
1639     /**
1640      * Searches the specified array of ints for the specified value using the
1641      * binary search algorithm.  The array must be sorted (as
1642      * by the {@link #sort(int[])} method) prior to making this call.  If it
1643      * is not sorted, the results are undefined.  If the array contains
1644      * multiple elements with the specified value, there is no guarantee which
1645      * one will be found.
1646      *
1647      * @param a the array to be searched
1648      * @param key the value to be searched for
1649      * @return index of the search key, if it is contained in the array;
1650      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1651      *         <i>insertion point</i> is defined as the point at which the
1652      *         key would be inserted into the array: the index of the first
1653      *         element greater than the key, or {@code a.length} if all
1654      *         elements in the array are less than the specified key.  Note
1655      *         that this guarantees that the return value will be &gt;= 0 if
1656      *         and only if the key is found.
1657      */
1658     public static int binarySearch(int[] a, int key) {
1659         return binarySearch0(a, 0, a.length, key);
1660     }
1661 
1662     /**
1663      * Searches a range of
1664      * the specified array of ints for the specified value using the
1665      * binary search algorithm.
1666      * The range must be sorted (as
1667      * by the {@link #sort(int[], int, int)} method)
1668      * prior to making this call.  If it
1669      * is not sorted, the results are undefined.  If the range contains
1670      * multiple elements with the specified value, there is no guarantee which
1671      * one will be found.
1672      *
1673      * @param a the array to be searched
1674      * @param fromIndex the index of the first element (inclusive) to be
1675      *          searched
1676      * @param toIndex the index of the last element (exclusive) to be searched
1677      * @param key the value to be searched for
1678      * @return index of the search key, if it is contained in the array
1679      *         within the specified range;
1680      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1681      *         <i>insertion point</i> is defined as the point at which the
1682      *         key would be inserted into the array: the index of the first
1683      *         element in the range greater than the key,
1684      *         or {@code toIndex} if all
1685      *         elements in the range are less than the specified key.  Note
1686      *         that this guarantees that the return value will be &gt;= 0 if
1687      *         and only if the key is found.
1688      * @throws IllegalArgumentException
1689      *         if {@code fromIndex > toIndex}
1690      * @throws ArrayIndexOutOfBoundsException
1691      *         if {@code fromIndex < 0 or toIndex > a.length}
1692      * @since 1.6
1693      */
1694     public static int binarySearch(int[] a, int fromIndex, int toIndex,
1695                                    int key) {
1696         rangeCheck(a.length, fromIndex, toIndex);
1697         return binarySearch0(a, fromIndex, toIndex, key);
1698     }
1699 
1700     // Like public version, but without range checks.
1701     private static int binarySearch0(int[] a, int fromIndex, int toIndex,
1702                                      int key) {
1703         int low = fromIndex;
1704         int high = toIndex - 1;
1705 
1706         while (low <= high) {
1707             int mid = (low + high) >>> 1;
1708             int midVal = a[mid];
1709 
1710             if (midVal < key)
1711                 low = mid + 1;
1712             else if (midVal > key)
1713                 high = mid - 1;
1714             else
1715                 return mid; // key found
1716         }
1717         return -(low + 1);  // key not found.
1718     }
1719 
1720     /**
1721      * Searches the specified array of shorts for the specified value using
1722      * the binary search algorithm.  The array must be sorted
1723      * (as by the {@link #sort(short[])} method) prior to making this call.  If
1724      * it is not sorted, the results are undefined.  If the array contains
1725      * multiple elements with the specified value, there is no guarantee which
1726      * one will be found.
1727      *
1728      * @param a the array to be searched
1729      * @param key the value to be searched for
1730      * @return index of the search key, if it is contained in the array;
1731      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1732      *         <i>insertion point</i> is defined as the point at which the
1733      *         key would be inserted into the array: the index of the first
1734      *         element greater than the key, or {@code a.length} if all
1735      *         elements in the array are less than the specified key.  Note
1736      *         that this guarantees that the return value will be &gt;= 0 if
1737      *         and only if the key is found.
1738      */
1739     public static int binarySearch(short[] a, short key) {
1740         return binarySearch0(a, 0, a.length, key);
1741     }
1742 
1743     /**
1744      * Searches a range of
1745      * the specified array of shorts for the specified value using
1746      * the binary search algorithm.
1747      * The range must be sorted
1748      * (as by the {@link #sort(short[], int, int)} method)
1749      * prior to making this call.  If
1750      * it is not sorted, the results are undefined.  If the range contains
1751      * multiple elements with the specified value, there is no guarantee which
1752      * one will be found.
1753      *
1754      * @param a the array to be searched
1755      * @param fromIndex the index of the first element (inclusive) to be
1756      *          searched
1757      * @param toIndex the index of the last element (exclusive) to be searched
1758      * @param key the value to be searched for
1759      * @return index of the search key, if it is contained in the array
1760      *         within the specified range;
1761      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1762      *         <i>insertion point</i> is defined as the point at which the
1763      *         key would be inserted into the array: the index of the first
1764      *         element in the range greater than the key,
1765      *         or {@code toIndex} if all
1766      *         elements in the range are less than the specified key.  Note
1767      *         that this guarantees that the return value will be &gt;= 0 if
1768      *         and only if the key is found.
1769      * @throws IllegalArgumentException
1770      *         if {@code fromIndex > toIndex}
1771      * @throws ArrayIndexOutOfBoundsException
1772      *         if {@code fromIndex < 0 or toIndex > a.length}
1773      * @since 1.6
1774      */
1775     public static int binarySearch(short[] a, int fromIndex, int toIndex,
1776                                    short key) {
1777         rangeCheck(a.length, fromIndex, toIndex);
1778         return binarySearch0(a, fromIndex, toIndex, key);
1779     }
1780 
1781     // Like public version, but without range checks.
1782     private static int binarySearch0(short[] a, int fromIndex, int toIndex,
1783                                      short key) {
1784         int low = fromIndex;
1785         int high = toIndex - 1;
1786 
1787         while (low <= high) {
1788             int mid = (low + high) >>> 1;
1789             short midVal = a[mid];
1790 
1791             if (midVal < key)
1792                 low = mid + 1;
1793             else if (midVal > key)
1794                 high = mid - 1;
1795             else
1796                 return mid; // key found
1797         }
1798         return -(low + 1);  // key not found.
1799     }
1800 
1801     /**
1802      * Searches the specified array of chars for the specified value using the
1803      * binary search algorithm.  The array must be sorted (as
1804      * by the {@link #sort(char[])} method) prior to making this call.  If it
1805      * is not sorted, the results are undefined.  If the array contains
1806      * multiple elements with the specified value, there is no guarantee which
1807      * one will be found.
1808      *
1809      * @param a the array to be searched
1810      * @param key the value to be searched for
1811      * @return index of the search key, if it is contained in the array;
1812      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1813      *         <i>insertion point</i> is defined as the point at which the
1814      *         key would be inserted into the array: the index of the first
1815      *         element greater than the key, or {@code a.length} if all
1816      *         elements in the array are less than the specified key.  Note
1817      *         that this guarantees that the return value will be &gt;= 0 if
1818      *         and only if the key is found.
1819      */
1820     public static int binarySearch(char[] a, char key) {
1821         return binarySearch0(a, 0, a.length, key);
1822     }
1823 
1824     /**
1825      * Searches a range of
1826      * the specified array of chars for the specified value using the
1827      * binary search algorithm.
1828      * The range must be sorted (as
1829      * by the {@link #sort(char[], int, int)} method)
1830      * prior to making this call.  If it
1831      * is not sorted, the results are undefined.  If the range contains
1832      * multiple elements with the specified value, there is no guarantee which
1833      * one will be found.
1834      *
1835      * @param a the array to be searched
1836      * @param fromIndex the index of the first element (inclusive) to be
1837      *          searched
1838      * @param toIndex the index of the last element (exclusive) to be searched
1839      * @param key the value to be searched for
1840      * @return index of the search key, if it is contained in the array
1841      *         within the specified range;
1842      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1843      *         <i>insertion point</i> is defined as the point at which the
1844      *         key would be inserted into the array: the index of the first
1845      *         element in the range greater than the key,
1846      *         or {@code toIndex} if all
1847      *         elements in the range are less than the specified key.  Note
1848      *         that this guarantees that the return value will be &gt;= 0 if
1849      *         and only if the key is found.
1850      * @throws IllegalArgumentException
1851      *         if {@code fromIndex > toIndex}
1852      * @throws ArrayIndexOutOfBoundsException
1853      *         if {@code fromIndex < 0 or toIndex > a.length}
1854      * @since 1.6
1855      */
1856     public static int binarySearch(char[] a, int fromIndex, int toIndex,
1857                                    char key) {
1858         rangeCheck(a.length, fromIndex, toIndex);
1859         return binarySearch0(a, fromIndex, toIndex, key);
1860     }
1861 
1862     // Like public version, but without range checks.
1863     private static int binarySearch0(char[] a, int fromIndex, int toIndex,
1864                                      char key) {
1865         int low = fromIndex;
1866         int high = toIndex - 1;
1867 
1868         while (low <= high) {
1869             int mid = (low + high) >>> 1;
1870             char midVal = a[mid];
1871 
1872             if (midVal < key)
1873                 low = mid + 1;
1874             else if (midVal > key)
1875                 high = mid - 1;
1876             else
1877                 return mid; // key found
1878         }
1879         return -(low + 1);  // key not found.
1880     }
1881 
1882     /**
1883      * Searches the specified array of bytes for the specified value using the
1884      * binary search algorithm.  The array must be sorted (as
1885      * by the {@link #sort(byte[])} method) prior to making this call.  If it
1886      * is not sorted, the results are undefined.  If the array contains
1887      * multiple elements with the specified value, there is no guarantee which
1888      * one will be found.
1889      *
1890      * @param a the array to be searched
1891      * @param key the value to be searched for
1892      * @return index of the search key, if it is contained in the array;
1893      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1894      *         <i>insertion point</i> is defined as the point at which the
1895      *         key would be inserted into the array: the index of the first
1896      *         element greater than the key, or {@code a.length} if all
1897      *         elements in the array are less than the specified key.  Note
1898      *         that this guarantees that the return value will be &gt;= 0 if
1899      *         and only if the key is found.
1900      */
1901     public static int binarySearch(byte[] a, byte key) {
1902         return binarySearch0(a, 0, a.length, key);
1903     }
1904 
1905     /**
1906      * Searches a range of
1907      * the specified array of bytes for the specified value using the
1908      * binary search algorithm.
1909      * The range must be sorted (as
1910      * by the {@link #sort(byte[], int, int)} method)
1911      * prior to making this call.  If it
1912      * is not sorted, the results are undefined.  If the range contains
1913      * multiple elements with the specified value, there is no guarantee which
1914      * one will be found.
1915      *
1916      * @param a the array to be searched
1917      * @param fromIndex the index of the first element (inclusive) to be
1918      *          searched
1919      * @param toIndex the index of the last element (exclusive) to be searched
1920      * @param key the value to be searched for
1921      * @return index of the search key, if it is contained in the array
1922      *         within the specified range;
1923      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1924      *         <i>insertion point</i> is defined as the point at which the
1925      *         key would be inserted into the array: the index of the first
1926      *         element in the range greater than the key,
1927      *         or {@code toIndex} if all
1928      *         elements in the range are less than the specified key.  Note
1929      *         that this guarantees that the return value will be &gt;= 0 if
1930      *         and only if the key is found.
1931      * @throws IllegalArgumentException
1932      *         if {@code fromIndex > toIndex}
1933      * @throws ArrayIndexOutOfBoundsException
1934      *         if {@code fromIndex < 0 or toIndex > a.length}
1935      * @since 1.6
1936      */
1937     public static int binarySearch(byte[] a, int fromIndex, int toIndex,
1938                                    byte key) {
1939         rangeCheck(a.length, fromIndex, toIndex);
1940         return binarySearch0(a, fromIndex, toIndex, key);
1941     }
1942 
1943     // Like public version, but without range checks.
1944     private static int binarySearch0(byte[] a, int fromIndex, int toIndex,
1945                                      byte key) {
1946         int low = fromIndex;
1947         int high = toIndex - 1;
1948 
1949         while (low <= high) {
1950             int mid = (low + high) >>> 1;
1951             byte midVal = a[mid];
1952 
1953             if (midVal < key)
1954                 low = mid + 1;
1955             else if (midVal > key)
1956                 high = mid - 1;
1957             else
1958                 return mid; // key found
1959         }
1960         return -(low + 1);  // key not found.
1961     }
1962 
1963     /**
1964      * Searches the specified array of doubles for the specified value using
1965      * the binary search algorithm.  The array must be sorted
1966      * (as by the {@link #sort(double[])} method) prior to making this call.
1967      * If it is not sorted, the results are undefined.  If the array contains
1968      * multiple elements with the specified value, there is no guarantee which
1969      * one will be found.  This method considers all NaN values to be
1970      * equivalent and equal.
1971      *
1972      * @param a the array to be searched
1973      * @param key the value to be searched for
1974      * @return index of the search key, if it is contained in the array;
1975      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
1976      *         <i>insertion point</i> is defined as the point at which the
1977      *         key would be inserted into the array: the index of the first
1978      *         element greater than the key, or {@code a.length} if all
1979      *         elements in the array are less than the specified key.  Note
1980      *         that this guarantees that the return value will be &gt;= 0 if
1981      *         and only if the key is found.
1982      */
1983     public static int binarySearch(double[] a, double key) {
1984         return binarySearch0(a, 0, a.length, key);
1985     }
1986 
1987     /**
1988      * Searches a range of
1989      * the specified array of doubles for the specified value using
1990      * the binary search algorithm.
1991      * The range must be sorted
1992      * (as by the {@link #sort(double[], int, int)} method)
1993      * prior to making this call.
1994      * If it is not sorted, the results are undefined.  If the range contains
1995      * multiple elements with the specified value, there is no guarantee which
1996      * one will be found.  This method considers all NaN values to be
1997      * equivalent and equal.
1998      *
1999      * @param a the array to be searched
2000      * @param fromIndex the index of the first element (inclusive) to be
2001      *          searched
2002      * @param toIndex the index of the last element (exclusive) to be searched
2003      * @param key the value to be searched for
2004      * @return index of the search key, if it is contained in the array
2005      *         within the specified range;
2006      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
2007      *         <i>insertion point</i> is defined as the point at which the
2008      *         key would be inserted into the array: the index of the first
2009      *         element in the range greater than the key,
2010      *         or {@code toIndex} if all
2011      *         elements in the range are less than the specified key.  Note
2012      *         that this guarantees that the return value will be &gt;= 0 if
2013      *         and only if the key is found.
2014      * @throws IllegalArgumentException
2015      *         if {@code fromIndex > toIndex}
2016      * @throws ArrayIndexOutOfBoundsException
2017      *         if {@code fromIndex < 0 or toIndex > a.length}
2018      * @since 1.6
2019      */
2020     public static int binarySearch(double[] a, int fromIndex, int toIndex,
2021                                    double key) {
2022         rangeCheck(a.length, fromIndex, toIndex);
2023         return binarySearch0(a, fromIndex, toIndex, key);
2024     }
2025 
2026     // Like public version, but without range checks.
2027     private static int binarySearch0(double[] a, int fromIndex, int toIndex,
2028                                      double key) {
2029         int low = fromIndex;
2030         int high = toIndex - 1;
2031 
2032         while (low <= high) {
2033             int mid = (low + high) >>> 1;
2034             double midVal = a[mid];
2035 
2036             if (midVal < key)
2037                 low = mid + 1;  // Neither val is NaN, thisVal is smaller
2038             else if (midVal > key)
2039                 high = mid - 1; // Neither val is NaN, thisVal is larger
2040             else {
2041                 long midBits = Double.doubleToLongBits(midVal);
2042                 long keyBits = Double.doubleToLongBits(key);
2043                 if (midBits == keyBits)     // Values are equal
2044                     return mid;             // Key found
2045                 else if (midBits < keyBits) // (-0.0, 0.0) or (!NaN, NaN)
2046                     low = mid + 1;
2047                 else                        // (0.0, -0.0) or (NaN, !NaN)
2048                     high = mid - 1;
2049             }
2050         }
2051         return -(low + 1);  // key not found.
2052     }
2053 
2054     /**
2055      * Searches the specified array of floats for the specified value using
2056      * the binary search algorithm. The array must be sorted
2057      * (as by the {@link #sort(float[])} method) prior to making this call. If
2058      * it is not sorted, the results are undefined. If the array contains
2059      * multiple elements with the specified value, there is no guarantee which
2060      * one will be found. This method considers all NaN values to be
2061      * equivalent and equal.
2062      *
2063      * @param a the array to be searched
2064      * @param key the value to be searched for
2065      * @return index of the search key, if it is contained in the array;
2066      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2067      *         <i>insertion point</i> is defined as the point at which the
2068      *         key would be inserted into the array: the index of the first
2069      *         element greater than the key, or {@code a.length} if all
2070      *         elements in the array are less than the specified key. Note
2071      *         that this guarantees that the return value will be &gt;= 0 if
2072      *         and only if the key is found.
2073      */
2074     public static int binarySearch(float[] a, float key) {
2075         return binarySearch0(a, 0, a.length, key);
2076     }
2077 
2078     /**
2079      * Searches a range of
2080      * the specified array of floats for the specified value using
2081      * the binary search algorithm.
2082      * The range must be sorted
2083      * (as by the {@link #sort(float[], int, int)} method)
2084      * prior to making this call. If
2085      * it is not sorted, the results are undefined. If the range contains
2086      * multiple elements with the specified value, there is no guarantee which
2087      * one will be found. This method considers all NaN values to be
2088      * equivalent and equal.
2089      *
2090      * @param a the array to be searched
2091      * @param fromIndex the index of the first element (inclusive) to be
2092      *          searched
2093      * @param toIndex the index of the last element (exclusive) to be searched
2094      * @param key the value to be searched for
2095      * @return index of the search key, if it is contained in the array
2096      *         within the specified range;
2097      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>. The
2098      *         <i>insertion point</i> is defined as the point at which the
2099      *         key would be inserted into the array: the index of the first
2100      *         element in the range greater than the key,
2101      *         or {@code toIndex} if all
2102      *         elements in the range are less than the specified key. Note
2103      *         that this guarantees that the return value will be &gt;= 0 if
2104      *         and only if the key is found.
2105      * @throws IllegalArgumentException
2106      *         if {@code fromIndex > toIndex}
2107      * @throws ArrayIndexOutOfBoundsException
2108      *         if {@code fromIndex < 0 or toIndex > a.length}
2109      * @since 1.6
2110      */
2111     public static int binarySearch(float[] a, int fromIndex, int toIndex,
2112                                    float key) {
2113         rangeCheck(a.length, fromIndex, toIndex);
2114         return binarySearch0(a, fromIndex, toIndex, key);
2115     }
2116 
2117     // Like public version, but without range checks.
2118     private static int binarySearch0(float[] a, int fromIndex, int toIndex,
2119                                      float key) {
2120         int low = fromIndex;
2121         int high = toIndex - 1;
2122 
2123         while (low <= high) {
2124             int mid = (low + high) >>> 1;
2125             float midVal = a[mid];
2126 
2127             if (midVal < key)
2128                 low = mid + 1;  // Neither val is NaN, thisVal is smaller
2129             else if (midVal > key)
2130                 high = mid - 1; // Neither val is NaN, thisVal is larger
2131             else {
2132                 int midBits = Float.floatToIntBits(midVal);
2133                 int keyBits = Float.floatToIntBits(key);
2134                 if (midBits == keyBits)     // Values are equal
2135                     return mid;             // Key found
2136                 else if (midBits < keyBits) // (-0.0, 0.0) or (!NaN, NaN)
2137                     low = mid + 1;
2138                 else                        // (0.0, -0.0) or (NaN, !NaN)
2139                     high = mid - 1;
2140             }
2141         }
2142         return -(low + 1);  // key not found.
2143     }
2144 
2145     /**
2146      * Searches the specified array for the specified object using the binary
2147      * search algorithm. The array must be sorted into ascending order
2148      * according to the
2149      * {@linkplain Comparable natural ordering}
2150      * of its elements (as by the
2151      * {@link #sort(Object[])} method) prior to making this call.
2152      * If it is not sorted, the results are undefined.
2153      * (If the array contains elements that are not mutually comparable (for
2154      * example, strings and integers), it <i>cannot</i> be sorted according
2155      * to the natural ordering of its elements, hence results are undefined.)
2156      * If the array contains multiple
2157      * elements equal to the specified object, there is no guarantee which
2158      * one will be found.
2159      *
2160      * @param a the array to be searched
2161      * @param key the value to be searched for
2162      * @return index of the search key, if it is contained in the array;
2163      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
2164      *         <i>insertion point</i> is defined as the point at which the
2165      *         key would be inserted into the array: the index of the first
2166      *         element greater than the key, or {@code a.length} if all
2167      *         elements in the array are less than the specified key.  Note
2168      *         that this guarantees that the return value will be &gt;= 0 if
2169      *         and only if the key is found.
2170      * @throws ClassCastException if the search key is not comparable to the
2171      *         elements of the array.
2172      */
2173     public static int binarySearch(Object[] a, Object key) {
2174         return binarySearch0(a, 0, a.length, key);
2175     }
2176 
2177     /**
2178      * Searches a range of
2179      * the specified array for the specified object using the binary
2180      * search algorithm.
2181      * The range must be sorted into ascending order
2182      * according to the
2183      * {@linkplain Comparable natural ordering}
2184      * of its elements (as by the
2185      * {@link #sort(Object[], int, int)} method) prior to making this
2186      * call.  If it is not sorted, the results are undefined.
2187      * (If the range contains elements that are not mutually comparable (for
2188      * example, strings and integers), it <i>cannot</i> be sorted according
2189      * to the natural ordering of its elements, hence results are undefined.)
2190      * If the range contains multiple
2191      * elements equal to the specified object, there is no guarantee which
2192      * one will be found.
2193      *
2194      * @param a the array to be searched
2195      * @param fromIndex the index of the first element (inclusive) to be
2196      *          searched
2197      * @param toIndex the index of the last element (exclusive) to be searched
2198      * @param key the value to be searched for
2199      * @return index of the search key, if it is contained in the array
2200      *         within the specified range;
2201      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
2202      *         <i>insertion point</i> is defined as the point at which the
2203      *         key would be inserted into the array: the index of the first
2204      *         element in the range greater than the key,
2205      *         or {@code toIndex} if all
2206      *         elements in the range are less than the specified key.  Note
2207      *         that this guarantees that the return value will be &gt;= 0 if
2208      *         and only if the key is found.
2209      * @throws ClassCastException if the search key is not comparable to the
2210      *         elements of the array within the specified range.
2211      * @throws IllegalArgumentException
2212      *         if {@code fromIndex > toIndex}
2213      * @throws ArrayIndexOutOfBoundsException
2214      *         if {@code fromIndex < 0 or toIndex > a.length}
2215      * @since 1.6
2216      */
2217     public static int binarySearch(Object[] a, int fromIndex, int toIndex,
2218                                    Object key) {
2219         rangeCheck(a.length, fromIndex, toIndex);
2220         return binarySearch0(a, fromIndex, toIndex, key);
2221     }
2222 
2223     // Like public version, but without range checks.
2224     private static int binarySearch0(Object[] a, int fromIndex, int toIndex,
2225                                      Object key) {
2226         int low = fromIndex;
2227         int high = toIndex - 1;
2228 
2229         while (low <= high) {
2230             int mid = (low + high) >>> 1;
2231             @SuppressWarnings("rawtypes")
2232             Comparable midVal = (Comparable)a[mid];
2233             @SuppressWarnings("unchecked")
2234             int cmp = midVal.compareTo(key);
2235 
2236             if (cmp < 0)
2237                 low = mid + 1;
2238             else if (cmp > 0)
2239                 high = mid - 1;
2240             else
2241                 return mid; // key found
2242         }
2243         return -(low + 1);  // key not found.
2244     }
2245 
2246     /**
2247      * Searches the specified array for the specified object using the binary
2248      * search algorithm.  The array must be sorted into ascending order
2249      * according to the specified comparator (as by the
2250      * {@link #sort(Object[], Comparator) sort(T[], Comparator)}
2251      * method) prior to making this call.  If it is
2252      * not sorted, the results are undefined.
2253      * If the array contains multiple
2254      * elements equal to the specified object, there is no guarantee which one
2255      * will be found.
2256      *
2257      * @param <T> the class of the objects in the array
2258      * @param a the array to be searched
2259      * @param key the value to be searched for
2260      * @param c the comparator by which the array is ordered.  A
2261      *        {@code null} value indicates that the elements'
2262      *        {@linkplain Comparable natural ordering} should be used.
2263      * @return index of the search key, if it is contained in the array;
2264      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
2265      *         <i>insertion point</i> is defined as the point at which the
2266      *         key would be inserted into the array: the index of the first
2267      *         element greater than the key, or {@code a.length} if all
2268      *         elements in the array are less than the specified key.  Note
2269      *         that this guarantees that the return value will be &gt;= 0 if
2270      *         and only if the key is found.
2271      * @throws ClassCastException if the array contains elements that are not
2272      *         <i>mutually comparable</i> using the specified comparator,
2273      *         or the search key is not comparable to the
2274      *         elements of the array using this comparator.
2275      */
2276     public static <T> int binarySearch(T[] a, T key, Comparator<? super T> c) {
2277         return binarySearch0(a, 0, a.length, key, c);
2278     }
2279 
2280     /**
2281      * Searches a range of
2282      * the specified array for the specified object using the binary
2283      * search algorithm.
2284      * The range must be sorted into ascending order
2285      * according to the specified comparator (as by the
2286      * {@link #sort(Object[], int, int, Comparator)
2287      * sort(T[], int, int, Comparator)}
2288      * method) prior to making this call.
2289      * If it is not sorted, the results are undefined.
2290      * If the range contains multiple elements equal to the specified object,
2291      * there is no guarantee which one will be found.
2292      *
2293      * @param <T> the class of the objects in the array
2294      * @param a the array to be searched
2295      * @param fromIndex the index of the first element (inclusive) to be
2296      *          searched
2297      * @param toIndex the index of the last element (exclusive) to be searched
2298      * @param key the value to be searched for
2299      * @param c the comparator by which the array is ordered.  A
2300      *        {@code null} value indicates that the elements'
2301      *        {@linkplain Comparable natural ordering} should be used.
2302      * @return index of the search key, if it is contained in the array
2303      *         within the specified range;
2304      *         otherwise, <code>(-(<i>insertion point</i>) - 1)</code>.  The
2305      *         <i>insertion point</i> is defined as the point at which the
2306      *         key would be inserted into the array: the index of the first
2307      *         element in the range greater than the key,
2308      *         or {@code toIndex} if all
2309      *         elements in the range are less than the specified key.  Note
2310      *         that this guarantees that the return value will be &gt;= 0 if
2311      *         and only if the key is found.
2312      * @throws ClassCastException if the range contains elements that are not
2313      *         <i>mutually comparable</i> using the specified comparator,
2314      *         or the search key is not comparable to the
2315      *         elements in the range using this comparator.
2316      * @throws IllegalArgumentException
2317      *         if {@code fromIndex > toIndex}
2318      * @throws ArrayIndexOutOfBoundsException
2319      *         if {@code fromIndex < 0 or toIndex > a.length}
2320      * @since 1.6
2321      */
2322     public static <T> int binarySearch(T[] a, int fromIndex, int toIndex,
2323                                        T key, Comparator<? super T> c) {
2324         rangeCheck(a.length, fromIndex, toIndex);
2325         return binarySearch0(a, fromIndex, toIndex, key, c);
2326     }
2327 
2328     // Like public version, but without range checks.
2329     private static <T> int binarySearch0(T[] a, int fromIndex, int toIndex,
2330                                          T key, Comparator<? super T> c) {
2331         if (c == null) {
2332             return binarySearch0(a, fromIndex, toIndex, key);
2333         }
2334         int low = fromIndex;
2335         int high = toIndex - 1;
2336 
2337         while (low <= high) {
2338             int mid = (low + high) >>> 1;
2339             T midVal = a[mid];
2340             int cmp = c.compare(midVal, key);
2341             if (cmp < 0)
2342                 low = mid + 1;
2343             else if (cmp > 0)
2344                 high = mid - 1;
2345             else
2346                 return mid; // key found
2347         }
2348         return -(low + 1);  // key not found.
2349     }
2350 
2351     // Equality Testing
2352 
2353     /**
2354      * Returns {@code true} if the two specified arrays of longs are
2355      * <i>equal</i> to one another.  Two arrays are considered equal if both
2356      * arrays contain the same number of elements, and all corresponding pairs
2357      * of elements in the two arrays are equal.  In other words, two arrays
2358      * are equal if they contain the same elements in the same order.  Also,
2359      * two array references are considered equal if both are {@code null}.
2360      *
2361      * @param a one array to be tested for equality
2362      * @param a2 the other array to be tested for equality
2363      * @return {@code true} if the two arrays are equal
2364      */
2365     public static boolean equals(long[] a, long[] a2) {
2366         if (a==a2)
2367             return true;
2368         if (a==null || a2==null)
2369             return false;
2370 
2371         int length = a.length;
2372         if (a2.length != length)
2373             return false;
2374 
2375         return ArraysSupport.mismatch(a, a2, length) < 0;
2376     }
2377 
2378     /**
2379      * Returns true if the two specified arrays of longs, over the specified
2380      * ranges, are <i>equal</i> to one another.
2381      *
2382      * <p>Two arrays are considered equal if the number of elements covered by
2383      * each range is the same, and all corresponding pairs of elements over the
2384      * specified ranges in the two arrays are equal.  In other words, two arrays
2385      * are equal if they contain, over the specified ranges, the same elements
2386      * in the same order.
2387      *
2388      * @param a the first array to be tested for equality
2389      * @param aFromIndex the index (inclusive) of the first element in the
2390      *                   first array to be tested
2391      * @param aToIndex the index (exclusive) of the last element in the
2392      *                 first array to be tested
2393      * @param b the second array to be tested for equality
2394      * @param bFromIndex the index (inclusive) of the first element in the
2395      *                   second array to be tested
2396      * @param bToIndex the index (exclusive) of the last element in the
2397      *                 second array to be tested
2398      * @return {@code true} if the two arrays, over the specified ranges, are
2399      *         equal
2400      * @throws IllegalArgumentException
2401      *         if {@code aFromIndex > aToIndex} or
2402      *         if {@code bFromIndex > bToIndex}
2403      * @throws ArrayIndexOutOfBoundsException
2404      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2405      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2406      * @throws NullPointerException
2407      *         if either array is {@code null}
2408      * @since 9
2409      */
2410     public static boolean equals(long[] a, int aFromIndex, int aToIndex,
2411                                  long[] b, int bFromIndex, int bToIndex) {
2412         rangeCheck(a.length, aFromIndex, aToIndex);
2413         rangeCheck(b.length, bFromIndex, bToIndex);
2414 
2415         int aLength = aToIndex - aFromIndex;
2416         int bLength = bToIndex - bFromIndex;
2417         if (aLength != bLength)
2418             return false;
2419 
2420         return ArraysSupport.mismatch(a, aFromIndex,
2421                                       b, bFromIndex,
2422                                       aLength) < 0;
2423     }
2424 
2425     /**
2426      * Returns {@code true} if the two specified arrays of ints are
2427      * <i>equal</i> to one another.  Two arrays are considered equal if both
2428      * arrays contain the same number of elements, and all corresponding pairs
2429      * of elements in the two arrays are equal.  In other words, two arrays
2430      * are equal if they contain the same elements in the same order.  Also,
2431      * two array references are considered equal if both are {@code null}.
2432      *
2433      * @param a one array to be tested for equality
2434      * @param a2 the other array to be tested for equality
2435      * @return {@code true} if the two arrays are equal
2436      */
2437     public static boolean equals(int[] a, int[] a2) {
2438         if (a==a2)
2439             return true;
2440         if (a==null || a2==null)
2441             return false;
2442 
2443         int length = a.length;
2444         if (a2.length != length)
2445             return false;
2446 
2447         return ArraysSupport.mismatch(a, a2, length) < 0;
2448     }
2449 
2450     /**
2451      * Returns true if the two specified arrays of ints, over the specified
2452      * ranges, are <i>equal</i> to one another.
2453      *
2454      * <p>Two arrays are considered equal if the number of elements covered by
2455      * each range is the same, and all corresponding pairs of elements over the
2456      * specified ranges in the two arrays are equal.  In other words, two arrays
2457      * are equal if they contain, over the specified ranges, the same elements
2458      * in the same order.
2459      *
2460      * @param a the first array to be tested for equality
2461      * @param aFromIndex the index (inclusive) of the first element in the
2462      *                   first array to be tested
2463      * @param aToIndex the index (exclusive) of the last element in the
2464      *                 first array to be tested
2465      * @param b the second array to be tested for equality
2466      * @param bFromIndex the index (inclusive) of the first element in the
2467      *                   second array to be tested
2468      * @param bToIndex the index (exclusive) of the last element in the
2469      *                 second array to be tested
2470      * @return {@code true} if the two arrays, over the specified ranges, are
2471      *         equal
2472      * @throws IllegalArgumentException
2473      *         if {@code aFromIndex > aToIndex} or
2474      *         if {@code bFromIndex > bToIndex}
2475      * @throws ArrayIndexOutOfBoundsException
2476      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2477      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2478      * @throws NullPointerException
2479      *         if either array is {@code null}
2480      * @since 9
2481      */
2482     public static boolean equals(int[] a, int aFromIndex, int aToIndex,
2483                                  int[] b, int bFromIndex, int bToIndex) {
2484         rangeCheck(a.length, aFromIndex, aToIndex);
2485         rangeCheck(b.length, bFromIndex, bToIndex);
2486 
2487         int aLength = aToIndex - aFromIndex;
2488         int bLength = bToIndex - bFromIndex;
2489         if (aLength != bLength)
2490             return false;
2491 
2492         return ArraysSupport.mismatch(a, aFromIndex,
2493                                       b, bFromIndex,
2494                                       aLength) < 0;
2495     }
2496 
2497     /**
2498      * Returns {@code true} if the two specified arrays of shorts are
2499      * <i>equal</i> to one another.  Two arrays are considered equal if both
2500      * arrays contain the same number of elements, and all corresponding pairs
2501      * of elements in the two arrays are equal.  In other words, two arrays
2502      * are equal if they contain the same elements in the same order.  Also,
2503      * two array references are considered equal if both are {@code null}.
2504      *
2505      * @param a one array to be tested for equality
2506      * @param a2 the other array to be tested for equality
2507      * @return {@code true} if the two arrays are equal
2508      */
2509     public static boolean equals(short[] a, short[] a2) {
2510         if (a==a2)
2511             return true;
2512         if (a==null || a2==null)
2513             return false;
2514 
2515         int length = a.length;
2516         if (a2.length != length)
2517             return false;
2518 
2519         return ArraysSupport.mismatch(a, a2, length) < 0;
2520     }
2521 
2522     /**
2523      * Returns true if the two specified arrays of shorts, over the specified
2524      * ranges, are <i>equal</i> to one another.
2525      *
2526      * <p>Two arrays are considered equal if the number of elements covered by
2527      * each range is the same, and all corresponding pairs of elements over the
2528      * specified ranges in the two arrays are equal.  In other words, two arrays
2529      * are equal if they contain, over the specified ranges, the same elements
2530      * in the same order.
2531      *
2532      * @param a the first array to be tested for equality
2533      * @param aFromIndex the index (inclusive) of the first element in the
2534      *                   first array to be tested
2535      * @param aToIndex the index (exclusive) of the last element in the
2536      *                 first array to be tested
2537      * @param b the second array to be tested for equality
2538      * @param bFromIndex the index (inclusive) of the first element in the
2539      *                   second array to be tested
2540      * @param bToIndex the index (exclusive) of the last element in the
2541      *                 second array to be tested
2542      * @return {@code true} if the two arrays, over the specified ranges, are
2543      *         equal
2544      * @throws IllegalArgumentException
2545      *         if {@code aFromIndex > aToIndex} or
2546      *         if {@code bFromIndex > bToIndex}
2547      * @throws ArrayIndexOutOfBoundsException
2548      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2549      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2550      * @throws NullPointerException
2551      *         if either array is {@code null}
2552      * @since 9
2553      */
2554     public static boolean equals(short[] a, int aFromIndex, int aToIndex,
2555                                  short[] b, int bFromIndex, int bToIndex) {
2556         rangeCheck(a.length, aFromIndex, aToIndex);
2557         rangeCheck(b.length, bFromIndex, bToIndex);
2558 
2559         int aLength = aToIndex - aFromIndex;
2560         int bLength = bToIndex - bFromIndex;
2561         if (aLength != bLength)
2562             return false;
2563 
2564         return ArraysSupport.mismatch(a, aFromIndex,
2565                                       b, bFromIndex,
2566                                       aLength) < 0;
2567     }
2568 
2569     /**
2570      * Returns {@code true} if the two specified arrays of chars are
2571      * <i>equal</i> to one another.  Two arrays are considered equal if both
2572      * arrays contain the same number of elements, and all corresponding pairs
2573      * of elements in the two arrays are equal.  In other words, two arrays
2574      * are equal if they contain the same elements in the same order.  Also,
2575      * two array references are considered equal if both are {@code null}.
2576      *
2577      * @param a one array to be tested for equality
2578      * @param a2 the other array to be tested for equality
2579      * @return {@code true} if the two arrays are equal
2580      */
2581     @IntrinsicCandidate
2582     public static boolean equals(char[] a, char[] a2) {
2583         if (a==a2)
2584             return true;
2585         if (a==null || a2==null)
2586             return false;
2587 
2588         int length = a.length;
2589         if (a2.length != length)
2590             return false;
2591 
2592         return ArraysSupport.mismatch(a, a2, length) < 0;
2593     }
2594 
2595     /**
2596      * Returns true if the two specified arrays of chars, over the specified
2597      * ranges, are <i>equal</i> to one another.
2598      *
2599      * <p>Two arrays are considered equal if the number of elements covered by
2600      * each range is the same, and all corresponding pairs of elements over the
2601      * specified ranges in the two arrays are equal.  In other words, two arrays
2602      * are equal if they contain, over the specified ranges, the same elements
2603      * in the same order.
2604      *
2605      * @param a the first array to be tested for equality
2606      * @param aFromIndex the index (inclusive) of the first element in the
2607      *                   first array to be tested
2608      * @param aToIndex the index (exclusive) of the last element in the
2609      *                 first array to be tested
2610      * @param b the second array to be tested for equality
2611      * @param bFromIndex the index (inclusive) of the first element in the
2612      *                   second array to be tested
2613      * @param bToIndex the index (exclusive) of the last element in the
2614      *                 second array to be tested
2615      * @return {@code true} if the two arrays, over the specified ranges, are
2616      *         equal
2617      * @throws IllegalArgumentException
2618      *         if {@code aFromIndex > aToIndex} or
2619      *         if {@code bFromIndex > bToIndex}
2620      * @throws ArrayIndexOutOfBoundsException
2621      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2622      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2623      * @throws NullPointerException
2624      *         if either array is {@code null}
2625      * @since 9
2626      */
2627     public static boolean equals(char[] a, int aFromIndex, int aToIndex,
2628                                  char[] b, int bFromIndex, int bToIndex) {
2629         rangeCheck(a.length, aFromIndex, aToIndex);
2630         rangeCheck(b.length, bFromIndex, bToIndex);
2631 
2632         int aLength = aToIndex - aFromIndex;
2633         int bLength = bToIndex - bFromIndex;
2634         if (aLength != bLength)
2635             return false;
2636 
2637         return ArraysSupport.mismatch(a, aFromIndex,
2638                                       b, bFromIndex,
2639                                       aLength) < 0;
2640     }
2641 
2642     /**
2643      * Returns {@code true} if the two specified arrays of bytes are
2644      * <i>equal</i> to one another.  Two arrays are considered equal if both
2645      * arrays contain the same number of elements, and all corresponding pairs
2646      * of elements in the two arrays are equal.  In other words, two arrays
2647      * are equal if they contain the same elements in the same order.  Also,
2648      * two array references are considered equal if both are {@code null}.
2649      *
2650      * @param a one array to be tested for equality
2651      * @param a2 the other array to be tested for equality
2652      * @return {@code true} if the two arrays are equal
2653      */
2654     @IntrinsicCandidate
2655     public static boolean equals(byte[] a, byte[] a2) {
2656         if (a==a2)
2657             return true;
2658         if (a==null || a2==null)
2659             return false;
2660 
2661         int length = a.length;
2662         if (a2.length != length)
2663             return false;
2664 
2665         return ArraysSupport.mismatch(a, a2, length) < 0;
2666     }
2667 
2668     /**
2669      * Returns true if the two specified arrays of bytes, over the specified
2670      * ranges, are <i>equal</i> to one another.
2671      *
2672      * <p>Two arrays are considered equal if the number of elements covered by
2673      * each range is the same, and all corresponding pairs of elements over the
2674      * specified ranges in the two arrays are equal.  In other words, two arrays
2675      * are equal if they contain, over the specified ranges, the same elements
2676      * in the same order.
2677      *
2678      * @param a the first array to be tested for equality
2679      * @param aFromIndex the index (inclusive) of the first element in the
2680      *                   first array to be tested
2681      * @param aToIndex the index (exclusive) of the last element in the
2682      *                 first array to be tested
2683      * @param b the second array to be tested for equality
2684      * @param bFromIndex the index (inclusive) of the first element in the
2685      *                   second array to be tested
2686      * @param bToIndex the index (exclusive) of the last element in the
2687      *                 second array to be tested
2688      * @return {@code true} if the two arrays, over the specified ranges, are
2689      *         equal
2690      * @throws IllegalArgumentException
2691      *         if {@code aFromIndex > aToIndex} or
2692      *         if {@code bFromIndex > bToIndex}
2693      * @throws ArrayIndexOutOfBoundsException
2694      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2695      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2696      * @throws NullPointerException
2697      *         if either array is {@code null}
2698      * @since 9
2699      */
2700     public static boolean equals(byte[] a, int aFromIndex, int aToIndex,
2701                                  byte[] b, int bFromIndex, int bToIndex) {
2702         rangeCheck(a.length, aFromIndex, aToIndex);
2703         rangeCheck(b.length, bFromIndex, bToIndex);
2704 
2705         int aLength = aToIndex - aFromIndex;
2706         int bLength = bToIndex - bFromIndex;
2707         if (aLength != bLength)
2708             return false;
2709 
2710         return ArraysSupport.mismatch(a, aFromIndex,
2711                                       b, bFromIndex,
2712                                       aLength) < 0;
2713     }
2714 
2715     /**
2716      * Returns {@code true} if the two specified arrays of booleans are
2717      * <i>equal</i> to one another.  Two arrays are considered equal if both
2718      * arrays contain the same number of elements, and all corresponding pairs
2719      * of elements in the two arrays are equal.  In other words, two arrays
2720      * are equal if they contain the same elements in the same order.  Also,
2721      * two array references are considered equal if both are {@code null}.
2722      *
2723      * @param a one array to be tested for equality
2724      * @param a2 the other array to be tested for equality
2725      * @return {@code true} if the two arrays are equal
2726      */
2727     public static boolean equals(boolean[] a, boolean[] a2) {
2728         if (a==a2)
2729             return true;
2730         if (a==null || a2==null)
2731             return false;
2732 
2733         int length = a.length;
2734         if (a2.length != length)
2735             return false;
2736 
2737         return ArraysSupport.mismatch(a, a2, length) < 0;
2738     }
2739 
2740     /**
2741      * Returns true if the two specified arrays of booleans, over the specified
2742      * ranges, are <i>equal</i> to one another.
2743      *
2744      * <p>Two arrays are considered equal if the number of elements covered by
2745      * each range is the same, and all corresponding pairs of elements over the
2746      * specified ranges in the two arrays are equal.  In other words, two arrays
2747      * are equal if they contain, over the specified ranges, the same elements
2748      * in the same order.
2749      *
2750      * @param a the first array to be tested for equality
2751      * @param aFromIndex the index (inclusive) of the first element in the
2752      *                   first array to be tested
2753      * @param aToIndex the index (exclusive) of the last element in the
2754      *                 first array to be tested
2755      * @param b the second array to be tested for equality
2756      * @param bFromIndex the index (inclusive) of the first element in the
2757      *                   second array to be tested
2758      * @param bToIndex the index (exclusive) of the last element in the
2759      *                 second array to be tested
2760      * @return {@code true} if the two arrays, over the specified ranges, are
2761      *         equal
2762      * @throws IllegalArgumentException
2763      *         if {@code aFromIndex > aToIndex} or
2764      *         if {@code bFromIndex > bToIndex}
2765      * @throws ArrayIndexOutOfBoundsException
2766      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2767      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2768      * @throws NullPointerException
2769      *         if either array is {@code null}
2770      * @since 9
2771      */
2772     public static boolean equals(boolean[] a, int aFromIndex, int aToIndex,
2773                                  boolean[] b, int bFromIndex, int bToIndex) {
2774         rangeCheck(a.length, aFromIndex, aToIndex);
2775         rangeCheck(b.length, bFromIndex, bToIndex);
2776 
2777         int aLength = aToIndex - aFromIndex;
2778         int bLength = bToIndex - bFromIndex;
2779         if (aLength != bLength)
2780             return false;
2781 
2782         return ArraysSupport.mismatch(a, aFromIndex,
2783                                       b, bFromIndex,
2784                                       aLength) < 0;
2785     }
2786 
2787     /**
2788      * Returns {@code true} if the two specified arrays of doubles are
2789      * <i>equal</i> to one another.  Two arrays are considered equal if both
2790      * arrays contain the same number of elements, and all corresponding pairs
2791      * of elements in the two arrays are equal.  In other words, two arrays
2792      * are equal if they contain the same elements in the same order.  Also,
2793      * two array references are considered equal if both are {@code null}.
2794      *
2795      * Two doubles {@code d1} and {@code d2} are considered equal if:
2796      * <pre>    {@code Double.valueOf(d1).equals(Double.valueOf(d2))}</pre>
2797      * (Unlike the {@code ==} operator, this method considers
2798      * {@code NaN} equal to itself, and 0.0d unequal to -0.0d.)
2799      *
2800      * @param a one array to be tested for equality
2801      * @param a2 the other array to be tested for equality
2802      * @return {@code true} if the two arrays are equal
2803      * @see Double#equals(Object)
2804      */
2805     public static boolean equals(double[] a, double[] a2) {
2806         if (a==a2)
2807             return true;
2808         if (a==null || a2==null)
2809             return false;
2810 
2811         int length = a.length;
2812         if (a2.length != length)
2813             return false;
2814 
2815         return ArraysSupport.mismatch(a, a2, length) < 0;
2816     }
2817 
2818     /**
2819      * Returns true if the two specified arrays of doubles, over the specified
2820      * ranges, are <i>equal</i> to one another.
2821      *
2822      * <p>Two arrays are considered equal if the number of elements covered by
2823      * each range is the same, and all corresponding pairs of elements over the
2824      * specified ranges in the two arrays are equal.  In other words, two arrays
2825      * are equal if they contain, over the specified ranges, the same elements
2826      * in the same order.
2827      *
2828      * <p>Two doubles {@code d1} and {@code d2} are considered equal if:
2829      * <pre>    {@code Double.valueOf(d1).equals(Double.valueOf(d2))}</pre>
2830      * (Unlike the {@code ==} operator, this method considers
2831      * {@code NaN} equal to itself, and 0.0d unequal to -0.0d.)
2832      *
2833      * @param a the first array to be tested for equality
2834      * @param aFromIndex the index (inclusive) of the first element in the
2835      *                   first array to be tested
2836      * @param aToIndex the index (exclusive) of the last element in the
2837      *                 first array to be tested
2838      * @param b the second array to be tested for equality
2839      * @param bFromIndex the index (inclusive) of the first element in the
2840      *                   second array to be tested
2841      * @param bToIndex the index (exclusive) of the last element in the
2842      *                 second array to be tested
2843      * @return {@code true} if the two arrays, over the specified ranges, are
2844      *         equal
2845      * @throws IllegalArgumentException
2846      *         if {@code aFromIndex > aToIndex} or
2847      *         if {@code bFromIndex > bToIndex}
2848      * @throws ArrayIndexOutOfBoundsException
2849      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2850      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2851      * @throws NullPointerException
2852      *         if either array is {@code null}
2853      * @see Double#equals(Object)
2854      * @since 9
2855      */
2856     public static boolean equals(double[] a, int aFromIndex, int aToIndex,
2857                                  double[] b, int bFromIndex, int bToIndex) {
2858         rangeCheck(a.length, aFromIndex, aToIndex);
2859         rangeCheck(b.length, bFromIndex, bToIndex);
2860 
2861         int aLength = aToIndex - aFromIndex;
2862         int bLength = bToIndex - bFromIndex;
2863         if (aLength != bLength)
2864             return false;
2865 
2866         return ArraysSupport.mismatch(a, aFromIndex,
2867                                       b, bFromIndex, aLength) < 0;
2868     }
2869 
2870     /**
2871      * Returns {@code true} if the two specified arrays of floats are
2872      * <i>equal</i> to one another.  Two arrays are considered equal if both
2873      * arrays contain the same number of elements, and all corresponding pairs
2874      * of elements in the two arrays are equal.  In other words, two arrays
2875      * are equal if they contain the same elements in the same order.  Also,
2876      * two array references are considered equal if both are {@code null}.
2877      *
2878      * Two floats {@code f1} and {@code f2} are considered equal if:
2879      * <pre>    {@code Float.valueOf(f1).equals(Float.valueOf(f2))}</pre>
2880      * (Unlike the {@code ==} operator, this method considers
2881      * {@code NaN} equal to itself, and 0.0f unequal to -0.0f.)
2882      *
2883      * @param a one array to be tested for equality
2884      * @param a2 the other array to be tested for equality
2885      * @return {@code true} if the two arrays are equal
2886      * @see Float#equals(Object)
2887      */
2888     public static boolean equals(float[] a, float[] a2) {
2889         if (a==a2)
2890             return true;
2891         if (a==null || a2==null)
2892             return false;
2893 
2894         int length = a.length;
2895         if (a2.length != length)
2896             return false;
2897 
2898         return ArraysSupport.mismatch(a, a2, length) < 0;
2899     }
2900 
2901     /**
2902      * Returns true if the two specified arrays of floats, over the specified
2903      * ranges, are <i>equal</i> to one another.
2904      *
2905      * <p>Two arrays are considered equal if the number of elements covered by
2906      * each range is the same, and all corresponding pairs of elements over the
2907      * specified ranges in the two arrays are equal.  In other words, two arrays
2908      * are equal if they contain, over the specified ranges, the same elements
2909      * in the same order.
2910      *
2911      * <p>Two floats {@code f1} and {@code f2} are considered equal if:
2912      * <pre>    {@code Float.valueOf(f1).equals(Float.valueOf(f2))}</pre>
2913      * (Unlike the {@code ==} operator, this method considers
2914      * {@code NaN} equal to itself, and 0.0f unequal to -0.0f.)
2915      *
2916      * @param a the first array to be tested for equality
2917      * @param aFromIndex the index (inclusive) of the first element in the
2918      *                   first array to be tested
2919      * @param aToIndex the index (exclusive) of the last element in the
2920      *                 first array to be tested
2921      * @param b the second array to be tested for equality
2922      * @param bFromIndex the index (inclusive) of the first element in the
2923      *                   second array to be tested
2924      * @param bToIndex the index (exclusive) of the last element in the
2925      *                 second array to be tested
2926      * @return {@code true} if the two arrays, over the specified ranges, are
2927      *         equal
2928      * @throws IllegalArgumentException
2929      *         if {@code aFromIndex > aToIndex} or
2930      *         if {@code bFromIndex > bToIndex}
2931      * @throws ArrayIndexOutOfBoundsException
2932      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
2933      *         if {@code bFromIndex < 0 or bToIndex > b.length}
2934      * @throws NullPointerException
2935      *         if either array is {@code null}
2936      * @see Float#equals(Object)
2937      * @since 9
2938      */
2939     public static boolean equals(float[] a, int aFromIndex, int aToIndex,
2940                                  float[] b, int bFromIndex, int bToIndex) {
2941         rangeCheck(a.length, aFromIndex, aToIndex);
2942         rangeCheck(b.length, bFromIndex, bToIndex);
2943 
2944         int aLength = aToIndex - aFromIndex;
2945         int bLength = bToIndex - bFromIndex;
2946         if (aLength != bLength)
2947             return false;
2948 
2949         return ArraysSupport.mismatch(a, aFromIndex,
2950                                       b, bFromIndex, aLength) < 0;
2951     }
2952 
2953     /**
2954      * Returns {@code true} if the two specified arrays of Objects are
2955      * <i>equal</i> to one another.  The two arrays are considered equal if
2956      * both arrays contain the same number of elements, and all corresponding
2957      * pairs of elements in the two arrays are equal.  Two objects {@code e1}
2958      * and {@code e2} are considered <i>equal</i> if
2959      * {@code Objects.equals(e1, e2)}.
2960      * In other words, the two arrays are equal if
2961      * they contain the same elements in the same order.  Also, two array
2962      * references are considered equal if both are {@code null}.
2963      *
2964      * @param a one array to be tested for equality
2965      * @param a2 the other array to be tested for equality
2966      * @return {@code true} if the two arrays are equal
2967      */
2968     public static boolean equals(Object[] a, Object[] a2) {
2969         if (a==a2)
2970             return true;
2971         if (a==null || a2==null)
2972             return false;
2973 
2974         int length = a.length;
2975         if (a2.length != length)
2976             return false;
2977 
2978         for (int i=0; i<length; i++) {
2979             if (!Objects.equals(a[i], a2[i]))
2980                 return false;
2981         }
2982 
2983         return true;
2984     }
2985 
2986     /**
2987      * Returns true if the two specified arrays of Objects, over the specified
2988      * ranges, are <i>equal</i> to one another.
2989      *
2990      * <p>Two arrays are considered equal if the number of elements covered by
2991      * each range is the same, and all corresponding pairs of elements over the
2992      * specified ranges in the two arrays are equal.  In other words, two arrays
2993      * are equal if they contain, over the specified ranges, the same elements
2994      * in the same order.
2995      *
2996      * <p>Two objects {@code e1} and {@code e2} are considered <i>equal</i> if
2997      * {@code Objects.equals(e1, e2)}.
2998      *
2999      * @param a the first array to be tested for equality
3000      * @param aFromIndex the index (inclusive) of the first element in the
3001      *                   first array to be tested
3002      * @param aToIndex the index (exclusive) of the last element in the
3003      *                 first array to be tested
3004      * @param b the second array to be tested for equality
3005      * @param bFromIndex the index (inclusive) of the first element in the
3006      *                   second array to be tested
3007      * @param bToIndex the index (exclusive) of the last element in the
3008      *                 second array to be tested
3009      * @return {@code true} if the two arrays, over the specified ranges, are
3010      *         equal
3011      * @throws IllegalArgumentException
3012      *         if {@code aFromIndex > aToIndex} or
3013      *         if {@code bFromIndex > bToIndex}
3014      * @throws ArrayIndexOutOfBoundsException
3015      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
3016      *         if {@code bFromIndex < 0 or bToIndex > b.length}
3017      * @throws NullPointerException
3018      *         if either array is {@code null}
3019      * @since 9
3020      */
3021     public static boolean equals(Object[] a, int aFromIndex, int aToIndex,
3022                                  Object[] b, int bFromIndex, int bToIndex) {
3023         rangeCheck(a.length, aFromIndex, aToIndex);
3024         rangeCheck(b.length, bFromIndex, bToIndex);
3025 
3026         int aLength = aToIndex - aFromIndex;
3027         int bLength = bToIndex - bFromIndex;
3028         if (aLength != bLength)
3029             return false;
3030 
3031         for (int i = 0; i < aLength; i++) {
3032             if (!Objects.equals(a[aFromIndex++], b[bFromIndex++]))
3033                 return false;
3034         }
3035 
3036         return true;
3037     }
3038 
3039     /**
3040      * Returns {@code true} if the two specified arrays of Objects are
3041      * <i>equal</i> to one another.
3042      *
3043      * <p>Two arrays are considered equal if both arrays contain the same number
3044      * of elements, and all corresponding pairs of elements in the two arrays
3045      * are equal.  In other words, the two arrays are equal if they contain the
3046      * same elements in the same order.  Also, two array references are
3047      * considered equal if both are {@code null}.
3048      *
3049      * <p>Two objects {@code e1} and {@code e2} are considered <i>equal</i> if,
3050      * given the specified comparator, {@code cmp.compare(e1, e2) == 0}.
3051      *
3052      * @param a one array to be tested for equality
3053      * @param a2 the other array to be tested for equality
3054      * @param cmp the comparator to compare array elements
3055      * @param <T> the type of array elements
3056      * @return {@code true} if the two arrays are equal
3057      * @throws NullPointerException if the comparator is {@code null}
3058      * @since 9
3059      */
3060     public static <T> boolean equals(T[] a, T[] a2, Comparator<? super T> cmp) {
3061         Objects.requireNonNull(cmp);
3062         if (a==a2)
3063             return true;
3064         if (a==null || a2==null)
3065             return false;
3066 
3067         int length = a.length;
3068         if (a2.length != length)
3069             return false;
3070 
3071         for (int i=0; i<length; i++) {
3072             if (cmp.compare(a[i], a2[i]) != 0)
3073                 return false;
3074         }
3075 
3076         return true;
3077     }
3078 
3079     /**
3080      * Returns true if the two specified arrays of Objects, over the specified
3081      * ranges, are <i>equal</i> to one another.
3082      *
3083      * <p>Two arrays are considered equal if the number of elements covered by
3084      * each range is the same, and all corresponding pairs of elements over the
3085      * specified ranges in the two arrays are equal.  In other words, two arrays
3086      * are equal if they contain, over the specified ranges, the same elements
3087      * in the same order.
3088      *
3089      * <p>Two objects {@code e1} and {@code e2} are considered <i>equal</i> if,
3090      * given the specified comparator, {@code cmp.compare(e1, e2) == 0}.
3091      *
3092      * @param a the first array to be tested for equality
3093      * @param aFromIndex the index (inclusive) of the first element in the
3094      *                   first array to be tested
3095      * @param aToIndex the index (exclusive) of the last element in the
3096      *                 first array to be tested
3097      * @param b the second array to be tested for equality
3098      * @param bFromIndex the index (inclusive) of the first element in the
3099      *                   second array to be tested
3100      * @param bToIndex the index (exclusive) of the last element in the
3101      *                 second array to be tested
3102      * @param cmp the comparator to compare array elements
3103      * @param <T> the type of array elements
3104      * @return {@code true} if the two arrays, over the specified ranges, are
3105      *         equal
3106      * @throws IllegalArgumentException
3107      *         if {@code aFromIndex > aToIndex} or
3108      *         if {@code bFromIndex > bToIndex}
3109      * @throws ArrayIndexOutOfBoundsException
3110      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
3111      *         if {@code bFromIndex < 0 or bToIndex > b.length}
3112      * @throws NullPointerException
3113      *         if either array or the comparator is {@code null}
3114      * @since 9
3115      */
3116     public static <T> boolean equals(T[] a, int aFromIndex, int aToIndex,
3117                                      T[] b, int bFromIndex, int bToIndex,
3118                                      Comparator<? super T> cmp) {
3119         Objects.requireNonNull(cmp);
3120         rangeCheck(a.length, aFromIndex, aToIndex);
3121         rangeCheck(b.length, bFromIndex, bToIndex);
3122 
3123         int aLength = aToIndex - aFromIndex;
3124         int bLength = bToIndex - bFromIndex;
3125         if (aLength != bLength)
3126             return false;
3127 
3128         for (int i = 0; i < aLength; i++) {
3129             if (cmp.compare(a[aFromIndex++], b[bFromIndex++]) != 0)
3130                 return false;
3131         }
3132 
3133         return true;
3134     }
3135 
3136     // Filling
3137 
3138     /**
3139      * Assigns the specified long value to each element of the specified array
3140      * of longs.
3141      *
3142      * @param a the array to be filled
3143      * @param val the value to be stored in all elements of the array
3144      */
3145     public static void fill(long[] a, long val) {
3146         for (int i = 0, len = a.length; i < len; i++)
3147             a[i] = val;
3148     }
3149 
3150     /**
3151      * Assigns the specified long value to each element of the specified
3152      * range of the specified array of longs.  The range to be filled
3153      * extends from index {@code fromIndex}, inclusive, to index
3154      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3155      * range to be filled is empty.)
3156      *
3157      * @param a the array to be filled
3158      * @param fromIndex the index of the first element (inclusive) to be
3159      *        filled with the specified value
3160      * @param toIndex the index of the last element (exclusive) to be
3161      *        filled with the specified value
3162      * @param val the value to be stored in all elements of the array
3163      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3164      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3165      *         {@code toIndex > a.length}
3166      */
3167     public static void fill(long[] a, int fromIndex, int toIndex, long val) {
3168         rangeCheck(a.length, fromIndex, toIndex);
3169         for (int i = fromIndex; i < toIndex; i++)
3170             a[i] = val;
3171     }
3172 
3173     /**
3174      * Assigns the specified int value to each element of the specified array
3175      * of ints.
3176      *
3177      * @param a the array to be filled
3178      * @param val the value to be stored in all elements of the array
3179      */
3180     public static void fill(int[] a, int val) {
3181         for (int i = 0, len = a.length; i < len; i++)
3182             a[i] = val;
3183     }
3184 
3185     /**
3186      * Assigns the specified int value to each element of the specified
3187      * range of the specified array of ints.  The range to be filled
3188      * extends from index {@code fromIndex}, inclusive, to index
3189      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3190      * range to be filled is empty.)
3191      *
3192      * @param a the array to be filled
3193      * @param fromIndex the index of the first element (inclusive) to be
3194      *        filled with the specified value
3195      * @param toIndex the index of the last element (exclusive) to be
3196      *        filled with the specified value
3197      * @param val the value to be stored in all elements of the array
3198      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3199      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3200      *         {@code toIndex > a.length}
3201      */
3202     public static void fill(int[] a, int fromIndex, int toIndex, int val) {
3203         rangeCheck(a.length, fromIndex, toIndex);
3204         for (int i = fromIndex; i < toIndex; i++)
3205             a[i] = val;
3206     }
3207 
3208     /**
3209      * Assigns the specified short value to each element of the specified array
3210      * of shorts.
3211      *
3212      * @param a the array to be filled
3213      * @param val the value to be stored in all elements of the array
3214      */
3215     public static void fill(short[] a, short val) {
3216         for (int i = 0, len = a.length; i < len; i++)
3217             a[i] = val;
3218     }
3219 
3220     /**
3221      * Assigns the specified short value to each element of the specified
3222      * range of the specified array of shorts.  The range to be filled
3223      * extends from index {@code fromIndex}, inclusive, to index
3224      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3225      * range to be filled is empty.)
3226      *
3227      * @param a the array to be filled
3228      * @param fromIndex the index of the first element (inclusive) to be
3229      *        filled with the specified value
3230      * @param toIndex the index of the last element (exclusive) to be
3231      *        filled with the specified value
3232      * @param val the value to be stored in all elements of the array
3233      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3234      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3235      *         {@code toIndex > a.length}
3236      */
3237     public static void fill(short[] a, int fromIndex, int toIndex, short val) {
3238         rangeCheck(a.length, fromIndex, toIndex);
3239         for (int i = fromIndex; i < toIndex; i++)
3240             a[i] = val;
3241     }
3242 
3243     /**
3244      * Assigns the specified char value to each element of the specified array
3245      * of chars.
3246      *
3247      * @param a the array to be filled
3248      * @param val the value to be stored in all elements of the array
3249      */
3250     public static void fill(char[] a, char val) {
3251         for (int i = 0, len = a.length; i < len; i++)
3252             a[i] = val;
3253     }
3254 
3255     /**
3256      * Assigns the specified char value to each element of the specified
3257      * range of the specified array of chars.  The range to be filled
3258      * extends from index {@code fromIndex}, inclusive, to index
3259      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3260      * range to be filled is empty.)
3261      *
3262      * @param a the array to be filled
3263      * @param fromIndex the index of the first element (inclusive) to be
3264      *        filled with the specified value
3265      * @param toIndex the index of the last element (exclusive) to be
3266      *        filled with the specified value
3267      * @param val the value to be stored in all elements of the array
3268      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3269      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3270      *         {@code toIndex > a.length}
3271      */
3272     public static void fill(char[] a, int fromIndex, int toIndex, char val) {
3273         rangeCheck(a.length, fromIndex, toIndex);
3274         for (int i = fromIndex; i < toIndex; i++)
3275             a[i] = val;
3276     }
3277 
3278     /**
3279      * Assigns the specified byte value to each element of the specified array
3280      * of bytes.
3281      *
3282      * @param a the array to be filled
3283      * @param val the value to be stored in all elements of the array
3284      */
3285     public static void fill(byte[] a, byte val) {
3286         for (int i = 0, len = a.length; i < len; i++)
3287             a[i] = val;
3288     }
3289 
3290     /**
3291      * Assigns the specified byte value to each element of the specified
3292      * range of the specified array of bytes.  The range to be filled
3293      * extends from index {@code fromIndex}, inclusive, to index
3294      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3295      * range to be filled is empty.)
3296      *
3297      * @param a the array to be filled
3298      * @param fromIndex the index of the first element (inclusive) to be
3299      *        filled with the specified value
3300      * @param toIndex the index of the last element (exclusive) to be
3301      *        filled with the specified value
3302      * @param val the value to be stored in all elements of the array
3303      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3304      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3305      *         {@code toIndex > a.length}
3306      */
3307     public static void fill(byte[] a, int fromIndex, int toIndex, byte val) {
3308         rangeCheck(a.length, fromIndex, toIndex);
3309         for (int i = fromIndex; i < toIndex; i++)
3310             a[i] = val;
3311     }
3312 
3313     /**
3314      * Assigns the specified boolean value to each element of the specified
3315      * array of booleans.
3316      *
3317      * @param a the array to be filled
3318      * @param val the value to be stored in all elements of the array
3319      */
3320     public static void fill(boolean[] a, boolean val) {
3321         for (int i = 0, len = a.length; i < len; i++)
3322             a[i] = val;
3323     }
3324 
3325     /**
3326      * Assigns the specified boolean value to each element of the specified
3327      * range of the specified array of booleans.  The range to be filled
3328      * extends from index {@code fromIndex}, inclusive, to index
3329      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3330      * range to be filled is empty.)
3331      *
3332      * @param a the array to be filled
3333      * @param fromIndex the index of the first element (inclusive) to be
3334      *        filled with the specified value
3335      * @param toIndex the index of the last element (exclusive) to be
3336      *        filled with the specified value
3337      * @param val the value to be stored in all elements of the array
3338      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3339      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3340      *         {@code toIndex > a.length}
3341      */
3342     public static void fill(boolean[] a, int fromIndex, int toIndex,
3343                             boolean val) {
3344         rangeCheck(a.length, fromIndex, toIndex);
3345         for (int i = fromIndex; i < toIndex; i++)
3346             a[i] = val;
3347     }
3348 
3349     /**
3350      * Assigns the specified double value to each element of the specified
3351      * array of doubles.
3352      *
3353      * @param a the array to be filled
3354      * @param val the value to be stored in all elements of the array
3355      */
3356     public static void fill(double[] a, double val) {
3357         for (int i = 0, len = a.length; i < len; i++)
3358             a[i] = val;
3359     }
3360 
3361     /**
3362      * Assigns the specified double value to each element of the specified
3363      * range of the specified array of doubles.  The range to be filled
3364      * extends from index {@code fromIndex}, inclusive, to index
3365      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3366      * range to be filled is empty.)
3367      *
3368      * @param a the array to be filled
3369      * @param fromIndex the index of the first element (inclusive) to be
3370      *        filled with the specified value
3371      * @param toIndex the index of the last element (exclusive) to be
3372      *        filled with the specified value
3373      * @param val the value to be stored in all elements of the array
3374      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3375      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3376      *         {@code toIndex > a.length}
3377      */
3378     public static void fill(double[] a, int fromIndex, int toIndex,double val){
3379         rangeCheck(a.length, fromIndex, toIndex);
3380         for (int i = fromIndex; i < toIndex; i++)
3381             a[i] = val;
3382     }
3383 
3384     /**
3385      * Assigns the specified float value to each element of the specified array
3386      * of floats.
3387      *
3388      * @param a the array to be filled
3389      * @param val the value to be stored in all elements of the array
3390      */
3391     public static void fill(float[] a, float val) {
3392         for (int i = 0, len = a.length; i < len; i++)
3393             a[i] = val;
3394     }
3395 
3396     /**
3397      * Assigns the specified float value to each element of the specified
3398      * range of the specified array of floats.  The range to be filled
3399      * extends from index {@code fromIndex}, inclusive, to index
3400      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3401      * range to be filled is empty.)
3402      *
3403      * @param a the array to be filled
3404      * @param fromIndex the index of the first element (inclusive) to be
3405      *        filled with the specified value
3406      * @param toIndex the index of the last element (exclusive) to be
3407      *        filled with the specified value
3408      * @param val the value to be stored in all elements of the array
3409      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3410      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3411      *         {@code toIndex > a.length}
3412      */
3413     public static void fill(float[] a, int fromIndex, int toIndex, float val) {
3414         rangeCheck(a.length, fromIndex, toIndex);
3415         for (int i = fromIndex; i < toIndex; i++)
3416             a[i] = val;
3417     }
3418 
3419     /**
3420      * Assigns the specified Object reference to each element of the specified
3421      * array of Objects.
3422      *
3423      * @param a the array to be filled
3424      * @param val the value to be stored in all elements of the array
3425      * @throws ArrayStoreException if the specified value is not of a
3426      *         runtime type that can be stored in the specified array
3427      */
3428     public static void fill(Object[] a, Object val) {
3429         for (int i = 0, len = a.length; i < len; i++)
3430             a[i] = val;
3431     }
3432 
3433     /**
3434      * Assigns the specified Object reference to each element of the specified
3435      * range of the specified array of Objects.  The range to be filled
3436      * extends from index {@code fromIndex}, inclusive, to index
3437      * {@code toIndex}, exclusive.  (If {@code fromIndex==toIndex}, the
3438      * range to be filled is empty.)
3439      *
3440      * @param a the array to be filled
3441      * @param fromIndex the index of the first element (inclusive) to be
3442      *        filled with the specified value
3443      * @param toIndex the index of the last element (exclusive) to be
3444      *        filled with the specified value
3445      * @param val the value to be stored in all elements of the array
3446      * @throws IllegalArgumentException if {@code fromIndex > toIndex}
3447      * @throws ArrayIndexOutOfBoundsException if {@code fromIndex < 0} or
3448      *         {@code toIndex > a.length}
3449      * @throws ArrayStoreException if the specified value is not of a
3450      *         runtime type that can be stored in the specified array
3451      */
3452     public static void fill(Object[] a, int fromIndex, int toIndex, Object val) {
3453         rangeCheck(a.length, fromIndex, toIndex);
3454         for (int i = fromIndex; i < toIndex; i++)
3455             a[i] = val;
3456     }
3457 
3458     // Cloning
3459 
3460     /**
3461      * Copies the specified array, truncating or padding with nulls (if necessary)
3462      * so the copy has the specified length.  For all indices that are
3463      * valid in both the original array and the copy, the two arrays will
3464      * contain identical values.  For any indices that are valid in the
3465      * copy but not the original, the copy will contain {@code null}.
3466      * Such indices will exist if and only if the specified length
3467      * is greater than that of the original array.
3468      * The resulting array is of exactly the same class as the original array.
3469      *
3470      * @param <T> the class of the objects in the array
3471      * @param original the array to be copied
3472      * @param newLength the length of the copy to be returned
3473      * @return a copy of the original array, truncated or padded with nulls
3474      *     to obtain the specified length
3475      * @throws NegativeArraySizeException if {@code newLength} is negative
3476      * @throws NullPointerException if {@code original} is null
3477      * @since 1.6
3478      */
3479     @SuppressWarnings("unchecked")
3480     public static <T> T[] copyOf(T[] original, int newLength) {
3481         return (T[]) copyOf(original, newLength, original.getClass());
3482     }
3483 
3484     /**
3485      * Copies the specified array, truncating or padding with nulls (if necessary)
3486      * so the copy has the specified length.  For all indices that are
3487      * valid in both the original array and the copy, the two arrays will
3488      * contain identical values.  For any indices that are valid in the
3489      * copy but not the original, the copy will contain {@code null}.
3490      * Such indices will exist if and only if the specified length
3491      * is greater than that of the original array.
3492      * The resulting array is of the class {@code newType}.
3493      *
3494      * @param <T> the class of the objects in the returned array
3495      * @param <U> the class of the objects in the original array
3496      * @param original the array to be copied
3497      * @param newLength the length of the copy to be returned
3498      * @param newType the class of the copy to be returned
3499      * @return a copy of the original array, truncated or padded with nulls
3500      *     to obtain the specified length
3501      * @throws NegativeArraySizeException if {@code newLength} is negative
3502      * @throws NullPointerException if {@code original} is null
3503      * @throws ArrayStoreException if an element copied from
3504      *     {@code original} is not of a runtime type that can be stored in
3505      *     an array of class {@code newType}
3506      * @since 1.6
3507      */
3508     @IntrinsicCandidate
3509     public static <T,U> T[] copyOf(U[] original, int newLength, Class<? extends T[]> newType) {

3510         @SuppressWarnings("unchecked")
3511         T[] copy = ((Object)newType == (Object)Object[].class)
3512             ? (T[]) new Object[newLength]
3513             : (T[]) Array.newInstance(newType.getComponentType(), newLength);


3514         System.arraycopy(original, 0, copy, 0,
3515                          Math.min(original.length, newLength));
3516         return copy;
3517     }
3518 
3519     /**
3520      * Copies the specified array, truncating or padding with zeros (if necessary)
3521      * so the copy has the specified length.  For all indices that are
3522      * valid in both the original array and the copy, the two arrays will
3523      * contain identical values.  For any indices that are valid in the
3524      * copy but not the original, the copy will contain {@code (byte)0}.
3525      * Such indices will exist if and only if the specified length
3526      * is greater than that of the original array.
3527      *
3528      * @param original the array to be copied
3529      * @param newLength the length of the copy to be returned
3530      * @return a copy of the original array, truncated or padded with zeros
3531      *     to obtain the specified length
3532      * @throws NegativeArraySizeException if {@code newLength} is negative
3533      * @throws NullPointerException if {@code original} is null
3534      * @since 1.6
3535      */
3536     public static byte[] copyOf(byte[] original, int newLength) {
3537         if (newLength == original.length) {
3538             return original.clone();
3539         }
3540         byte[] copy = new byte[newLength];
3541         System.arraycopy(original, 0, copy, 0,
3542                          Math.min(original.length, newLength));
3543         return copy;
3544     }
3545 
3546     /**
3547      * Copies the specified array, truncating or padding with zeros (if necessary)
3548      * so the copy has the specified length.  For all indices that are
3549      * valid in both the original array and the copy, the two arrays will
3550      * contain identical values.  For any indices that are valid in the
3551      * copy but not the original, the copy will contain {@code (short)0}.
3552      * Such indices will exist if and only if the specified length
3553      * is greater than that of the original array.
3554      *
3555      * @param original the array to be copied
3556      * @param newLength the length of the copy to be returned
3557      * @return a copy of the original array, truncated or padded with zeros
3558      *     to obtain the specified length
3559      * @throws NegativeArraySizeException if {@code newLength} is negative
3560      * @throws NullPointerException if {@code original} is null
3561      * @since 1.6
3562      */
3563     public static short[] copyOf(short[] original, int newLength) {
3564         if (newLength == original.length) {
3565             return original.clone();
3566         }
3567         short[] copy = new short[newLength];
3568         System.arraycopy(original, 0, copy, 0,
3569                          Math.min(original.length, newLength));
3570         return copy;
3571     }
3572 
3573     /**
3574      * Copies the specified array, truncating or padding with zeros (if necessary)
3575      * so the copy has the specified length.  For all indices that are
3576      * valid in both the original array and the copy, the two arrays will
3577      * contain identical values.  For any indices that are valid in the
3578      * copy but not the original, the copy will contain {@code 0}.
3579      * Such indices will exist if and only if the specified length
3580      * is greater than that of the original array.
3581      *
3582      * @param original the array to be copied
3583      * @param newLength the length of the copy to be returned
3584      * @return a copy of the original array, truncated or padded with zeros
3585      *     to obtain the specified length
3586      * @throws NegativeArraySizeException if {@code newLength} is negative
3587      * @throws NullPointerException if {@code original} is null
3588      * @since 1.6
3589      */
3590     public static int[] copyOf(int[] original, int newLength) {
3591         if (newLength == original.length) {
3592             return original.clone();
3593         }
3594         int[] copy = new int[newLength];
3595         System.arraycopy(original, 0, copy, 0,
3596                          Math.min(original.length, newLength));
3597         return copy;
3598     }
3599 
3600 
3601     /**
3602      * Copies the specified array, truncating or padding with zeros (if necessary)
3603      * so the copy has the specified length.  For all indices that are
3604      * valid in both the original array and the copy, the two arrays will
3605      * contain identical values.  For any indices that are valid in the
3606      * copy but not the original, the copy will contain {@code 0L}.
3607      * Such indices will exist if and only if the specified length
3608      * is greater than that of the original array.
3609      *
3610      * @param original the array to be copied
3611      * @param newLength the length of the copy to be returned
3612      * @return a copy of the original array, truncated or padded with zeros
3613      *     to obtain the specified length
3614      * @throws NegativeArraySizeException if {@code newLength} is negative
3615      * @throws NullPointerException if {@code original} is null
3616      * @since 1.6
3617      */
3618     public static long[] copyOf(long[] original, int newLength) {
3619         if (newLength == original.length) {
3620             return original.clone();
3621         }
3622         long[] copy = new long[newLength];
3623         System.arraycopy(original, 0, copy, 0,
3624                          Math.min(original.length, newLength));
3625         return copy;
3626     }
3627 
3628     /**
3629      * Copies the specified array, truncating or padding with null characters (if necessary)
3630      * so the copy has the specified length.  For all indices that are valid
3631      * in both the original array and the copy, the two arrays will contain
3632      * identical values.  For any indices that are valid in the copy but not
3633      * the original, the copy will contain {@code '\u005cu0000'}.  Such indices
3634      * will exist if and only if the specified length is greater than that of
3635      * the original array.
3636      *
3637      * @param original the array to be copied
3638      * @param newLength the length of the copy to be returned
3639      * @return a copy of the original array, truncated or padded with null characters
3640      *     to obtain the specified length
3641      * @throws NegativeArraySizeException if {@code newLength} is negative
3642      * @throws NullPointerException if {@code original} is null
3643      * @since 1.6
3644      */
3645     public static char[] copyOf(char[] original, int newLength) {
3646         if (newLength == original.length) {
3647             return original.clone();
3648         }
3649         char[] copy = new char[newLength];
3650         System.arraycopy(original, 0, copy, 0,
3651                          Math.min(original.length, newLength));
3652         return copy;
3653     }
3654 
3655     /**
3656      * Copies the specified array, truncating or padding with zeros (if necessary)
3657      * so the copy has the specified length.  For all indices that are
3658      * valid in both the original array and the copy, the two arrays will
3659      * contain identical values.  For any indices that are valid in the
3660      * copy but not the original, the copy will contain {@code 0f}.
3661      * Such indices will exist if and only if the specified length
3662      * is greater than that of the original array.
3663      *
3664      * @param original the array to be copied
3665      * @param newLength the length of the copy to be returned
3666      * @return a copy of the original array, truncated or padded with zeros
3667      *     to obtain the specified length
3668      * @throws NegativeArraySizeException if {@code newLength} is negative
3669      * @throws NullPointerException if {@code original} is null
3670      * @since 1.6
3671      */
3672     public static float[] copyOf(float[] original, int newLength) {
3673         if (newLength == original.length) {
3674             return original.clone();
3675         }
3676         float[] copy = new float[newLength];
3677         System.arraycopy(original, 0, copy, 0,
3678                          Math.min(original.length, newLength));
3679         return copy;
3680     }
3681 
3682     /**
3683      * Copies the specified array, truncating or padding with zeros (if necessary)
3684      * so the copy has the specified length.  For all indices that are
3685      * valid in both the original array and the copy, the two arrays will
3686      * contain identical values.  For any indices that are valid in the
3687      * copy but not the original, the copy will contain {@code 0d}.
3688      * Such indices will exist if and only if the specified length
3689      * is greater than that of the original array.
3690      *
3691      * @param original the array to be copied
3692      * @param newLength the length of the copy to be returned
3693      * @return a copy of the original array, truncated or padded with zeros
3694      *     to obtain the specified length
3695      * @throws NegativeArraySizeException if {@code newLength} is negative
3696      * @throws NullPointerException if {@code original} is null
3697      * @since 1.6
3698      */
3699     public static double[] copyOf(double[] original, int newLength) {
3700         if (newLength == original.length) {
3701             return original.clone();
3702         }
3703         double[] copy = new double[newLength];
3704         System.arraycopy(original, 0, copy, 0,
3705                          Math.min(original.length, newLength));
3706         return copy;
3707     }
3708 
3709     /**
3710      * Copies the specified array, truncating or padding with {@code false} (if necessary)
3711      * so the copy has the specified length.  For all indices that are
3712      * valid in both the original array and the copy, the two arrays will
3713      * contain identical values.  For any indices that are valid in the
3714      * copy but not the original, the copy will contain {@code false}.
3715      * Such indices will exist if and only if the specified length
3716      * is greater than that of the original array.
3717      *
3718      * @param original the array to be copied
3719      * @param newLength the length of the copy to be returned
3720      * @return a copy of the original array, truncated or padded with false elements
3721      *     to obtain the specified length
3722      * @throws NegativeArraySizeException if {@code newLength} is negative
3723      * @throws NullPointerException if {@code original} is null
3724      * @since 1.6
3725      */
3726     public static boolean[] copyOf(boolean[] original, int newLength) {
3727         if (newLength == original.length) {
3728             return original.clone();
3729         }
3730         boolean[] copy = new boolean[newLength];
3731         System.arraycopy(original, 0, copy, 0,
3732                          Math.min(original.length, newLength));
3733         return copy;
3734     }
3735 
3736     /**
3737      * Copies the specified range of the specified array into a new array.
3738      * The initial index of the range ({@code from}) must lie between zero
3739      * and {@code original.length}, inclusive.  The value at
3740      * {@code original[from]} is placed into the initial element of the copy
3741      * (unless {@code from == original.length} or {@code from == to}).
3742      * Values from subsequent elements in the original array are placed into
3743      * subsequent elements in the copy.  The final index of the range
3744      * ({@code to}), which must be greater than or equal to {@code from},
3745      * may be greater than {@code original.length}, in which case
3746      * {@code null} is placed in all elements of the copy whose index is
3747      * greater than or equal to {@code original.length - from}.  The length
3748      * of the returned array will be {@code to - from}.
3749      * <p>
3750      * The resulting array is of exactly the same class as the original array.
3751      *
3752      * @param <T> the class of the objects in the array
3753      * @param original the array from which a range is to be copied
3754      * @param from the initial index of the range to be copied, inclusive
3755      * @param to the final index of the range to be copied, exclusive.
3756      *     (This index may lie outside the array.)
3757      * @return a new array containing the specified range from the original array,
3758      *     truncated or padded with nulls to obtain the required length
3759      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3760      *     or {@code from > original.length}
3761      * @throws IllegalArgumentException if {@code from > to}
3762      * @throws NullPointerException if {@code original} is null
3763      * @since 1.6
3764      */
3765     @SuppressWarnings("unchecked")
3766     public static <T> T[] copyOfRange(T[] original, int from, int to) {
3767         return copyOfRange(original, from, to, (Class<? extends T[]>) original.getClass());
3768     }
3769 
3770     /**
3771      * Copies the specified range of the specified array into a new array.
3772      * The initial index of the range ({@code from}) must lie between zero
3773      * and {@code original.length}, inclusive.  The value at
3774      * {@code original[from]} is placed into the initial element of the copy
3775      * (unless {@code from == original.length} or {@code from == to}).
3776      * Values from subsequent elements in the original array are placed into
3777      * subsequent elements in the copy.  The final index of the range
3778      * ({@code to}), which must be greater than or equal to {@code from},
3779      * may be greater than {@code original.length}, in which case
3780      * {@code null} is placed in all elements of the copy whose index is
3781      * greater than or equal to {@code original.length - from}.  The length
3782      * of the returned array will be {@code to - from}.
3783      * The resulting array is of the class {@code newType}.
3784      *
3785      * @param <T> the class of the objects in the returned array
3786      * @param <U> the class of the objects in the original array
3787      * @param original the array from which a range is to be copied
3788      * @param from the initial index of the range to be copied, inclusive
3789      * @param to the final index of the range to be copied, exclusive.
3790      *     (This index may lie outside the array.)
3791      * @param newType the class of the copy to be returned
3792      * @return a new array containing the specified range from the original array,
3793      *     truncated or padded with nulls to obtain the required length
3794      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3795      *     or {@code from > original.length}
3796      * @throws IllegalArgumentException if {@code from > to}
3797      * @throws NullPointerException if {@code original} is null
3798      * @throws ArrayStoreException if an element copied from
3799      *     {@code original} is not of a runtime type that can be stored in
3800      *     an array of class {@code newType}.
3801      * @since 1.6
3802      */
3803     @IntrinsicCandidate
3804     public static <T,U> T[] copyOfRange(U[] original, int from, int to, Class<? extends T[]> newType) {
3805         int newLength = to - from;
3806         if (newLength < 0) {
3807             throw new IllegalArgumentException(from + " > " + to);
3808         }

3809         @SuppressWarnings("unchecked")
3810         T[] copy = ((Object)newType == (Object)Object[].class)
3811             ? (T[]) new Object[newLength]
3812             : (T[]) Array.newInstance(newType.getComponentType(), newLength);


3813         System.arraycopy(original, from, copy, 0,
3814                          Math.min(original.length - from, newLength));
3815         return copy;
3816     }
3817 
3818     /**
3819      * Copies the specified range of the specified array into a new array.
3820      * The initial index of the range ({@code from}) must lie between zero
3821      * and {@code original.length}, inclusive.  The value at
3822      * {@code original[from]} is placed into the initial element of the copy
3823      * (unless {@code from == original.length} or {@code from == to}).
3824      * Values from subsequent elements in the original array are placed into
3825      * subsequent elements in the copy.  The final index of the range
3826      * ({@code to}), which must be greater than or equal to {@code from},
3827      * may be greater than {@code original.length}, in which case
3828      * {@code (byte)0} is placed in all elements of the copy whose index is
3829      * greater than or equal to {@code original.length - from}.  The length
3830      * of the returned array will be {@code to - from}.
3831      *
3832      * @param original the array from which a range is to be copied
3833      * @param from the initial index of the range to be copied, inclusive
3834      * @param to the final index of the range to be copied, exclusive.
3835      *     (This index may lie outside the array.)
3836      * @return a new array containing the specified range from the original array,
3837      *     truncated or padded with zeros to obtain the required length
3838      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3839      *     or {@code from > original.length}
3840      * @throws IllegalArgumentException if {@code from > to}
3841      * @throws NullPointerException if {@code original} is null
3842      * @since 1.6
3843      */
3844     public static byte[] copyOfRange(byte[] original, int from, int to) {
3845         if (from == 0 && to == original.length) {
3846             return original.clone();
3847         }
3848         int newLength = to - from;
3849         if (newLength < 0) {
3850             throw new IllegalArgumentException(from + " > " + to);
3851         }
3852         byte[] copy = new byte[newLength];
3853         System.arraycopy(original, from, copy, 0,
3854                 Math.min(original.length - from, newLength));
3855         return copy;
3856     }
3857 
3858     /**
3859      * Copies the specified range of the specified array into a new array.
3860      * The initial index of the range ({@code from}) must lie between zero
3861      * and {@code original.length}, inclusive.  The value at
3862      * {@code original[from]} is placed into the initial element of the copy
3863      * (unless {@code from == original.length} or {@code from == to}).
3864      * Values from subsequent elements in the original array are placed into
3865      * subsequent elements in the copy.  The final index of the range
3866      * ({@code to}), which must be greater than or equal to {@code from},
3867      * may be greater than {@code original.length}, in which case
3868      * {@code (short)0} is placed in all elements of the copy whose index is
3869      * greater than or equal to {@code original.length - from}.  The length
3870      * of the returned array will be {@code to - from}.
3871      *
3872      * @param original the array from which a range is to be copied
3873      * @param from the initial index of the range to be copied, inclusive
3874      * @param to the final index of the range to be copied, exclusive.
3875      *     (This index may lie outside the array.)
3876      * @return a new array containing the specified range from the original array,
3877      *     truncated or padded with zeros to obtain the required length
3878      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3879      *     or {@code from > original.length}
3880      * @throws IllegalArgumentException if {@code from > to}
3881      * @throws NullPointerException if {@code original} is null
3882      * @since 1.6
3883      */
3884     public static short[] copyOfRange(short[] original, int from, int to) {
3885         if (from == 0 && to == original.length) {
3886             return original.clone();
3887         }
3888         int newLength = to - from;
3889         if (newLength < 0) {
3890             throw new IllegalArgumentException(from + " > " + to);
3891         }
3892         short[] copy = new short[newLength];
3893         System.arraycopy(original, from, copy, 0,
3894                          Math.min(original.length - from, newLength));
3895         return copy;
3896     }
3897 
3898     /**
3899      * Copies the specified range of the specified array into a new array.
3900      * The initial index of the range ({@code from}) must lie between zero
3901      * and {@code original.length}, inclusive.  The value at
3902      * {@code original[from]} is placed into the initial element of the copy
3903      * (unless {@code from == original.length} or {@code from == to}).
3904      * Values from subsequent elements in the original array are placed into
3905      * subsequent elements in the copy.  The final index of the range
3906      * ({@code to}), which must be greater than or equal to {@code from},
3907      * may be greater than {@code original.length}, in which case
3908      * {@code 0} is placed in all elements of the copy whose index is
3909      * greater than or equal to {@code original.length - from}.  The length
3910      * of the returned array will be {@code to - from}.
3911      *
3912      * @param original the array from which a range is to be copied
3913      * @param from the initial index of the range to be copied, inclusive
3914      * @param to the final index of the range to be copied, exclusive.
3915      *     (This index may lie outside the array.)
3916      * @return a new array containing the specified range from the original array,
3917      *     truncated or padded with zeros to obtain the required length
3918      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3919      *     or {@code from > original.length}
3920      * @throws IllegalArgumentException if {@code from > to}
3921      * @throws NullPointerException if {@code original} is null
3922      * @since 1.6
3923      */
3924     public static int[] copyOfRange(int[] original, int from, int to) {
3925         if (from == 0 && to == original.length) {
3926             return original.clone();
3927         }
3928         int newLength = to - from;
3929         if (newLength < 0) {
3930             throw new IllegalArgumentException(from + " > " + to);
3931         }
3932         int[] copy = new int[newLength];
3933         System.arraycopy(original, from, copy, 0,
3934                          Math.min(original.length - from, newLength));
3935         return copy;
3936     }
3937 
3938     /**
3939      * Copies the specified range of the specified array into a new array.
3940      * The initial index of the range ({@code from}) must lie between zero
3941      * and {@code original.length}, inclusive.  The value at
3942      * {@code original[from]} is placed into the initial element of the copy
3943      * (unless {@code from == original.length} or {@code from == to}).
3944      * Values from subsequent elements in the original array are placed into
3945      * subsequent elements in the copy.  The final index of the range
3946      * ({@code to}), which must be greater than or equal to {@code from},
3947      * may be greater than {@code original.length}, in which case
3948      * {@code 0L} is placed in all elements of the copy whose index is
3949      * greater than or equal to {@code original.length - from}.  The length
3950      * of the returned array will be {@code to - from}.
3951      *
3952      * @param original the array from which a range is to be copied
3953      * @param from the initial index of the range to be copied, inclusive
3954      * @param to the final index of the range to be copied, exclusive.
3955      *     (This index may lie outside the array.)
3956      * @return a new array containing the specified range from the original array,
3957      *     truncated or padded with zeros to obtain the required length
3958      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3959      *     or {@code from > original.length}
3960      * @throws IllegalArgumentException if {@code from > to}
3961      * @throws NullPointerException if {@code original} is null
3962      * @since 1.6
3963      */
3964     public static long[] copyOfRange(long[] original, int from, int to) {
3965         if (from == 0 && to == original.length) {
3966             return original.clone();
3967         }
3968         int newLength = to - from;
3969         if (newLength < 0) {
3970             throw new IllegalArgumentException(from + " > " + to);
3971         }
3972         long[] copy = new long[newLength];
3973         System.arraycopy(original, from, copy, 0,
3974                          Math.min(original.length - from, newLength));
3975         return copy;
3976     }
3977 
3978     /**
3979      * Copies the specified range of the specified array into a new array.
3980      * The initial index of the range ({@code from}) must lie between zero
3981      * and {@code original.length}, inclusive.  The value at
3982      * {@code original[from]} is placed into the initial element of the copy
3983      * (unless {@code from == original.length} or {@code from == to}).
3984      * Values from subsequent elements in the original array are placed into
3985      * subsequent elements in the copy.  The final index of the range
3986      * ({@code to}), which must be greater than or equal to {@code from},
3987      * may be greater than {@code original.length}, in which case
3988      * {@code '\u005cu0000'} is placed in all elements of the copy whose index is
3989      * greater than or equal to {@code original.length - from}.  The length
3990      * of the returned array will be {@code to - from}.
3991      *
3992      * @param original the array from which a range is to be copied
3993      * @param from the initial index of the range to be copied, inclusive
3994      * @param to the final index of the range to be copied, exclusive.
3995      *     (This index may lie outside the array.)
3996      * @return a new array containing the specified range from the original array,
3997      *     truncated or padded with null characters to obtain the required length
3998      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
3999      *     or {@code from > original.length}
4000      * @throws IllegalArgumentException if {@code from > to}
4001      * @throws NullPointerException if {@code original} is null
4002      * @since 1.6
4003      */
4004     public static char[] copyOfRange(char[] original, int from, int to) {
4005         if (from == 0 && to == original.length) {
4006             return original.clone();
4007         }
4008         int newLength = to - from;
4009         if (newLength < 0) {
4010             throw new IllegalArgumentException(from + " > " + to);
4011         }
4012         char[] copy = new char[newLength];
4013         System.arraycopy(original, from, copy, 0,
4014                          Math.min(original.length - from, newLength));
4015         return copy;
4016     }
4017 
4018     /**
4019      * Copies the specified range of the specified array into a new array.
4020      * The initial index of the range ({@code from}) must lie between zero
4021      * and {@code original.length}, inclusive.  The value at
4022      * {@code original[from]} is placed into the initial element of the copy
4023      * (unless {@code from == original.length} or {@code from == to}).
4024      * Values from subsequent elements in the original array are placed into
4025      * subsequent elements in the copy.  The final index of the range
4026      * ({@code to}), which must be greater than or equal to {@code from},
4027      * may be greater than {@code original.length}, in which case
4028      * {@code 0f} is placed in all elements of the copy whose index is
4029      * greater than or equal to {@code original.length - from}.  The length
4030      * of the returned array will be {@code to - from}.
4031      *
4032      * @param original the array from which a range is to be copied
4033      * @param from the initial index of the range to be copied, inclusive
4034      * @param to the final index of the range to be copied, exclusive.
4035      *     (This index may lie outside the array.)
4036      * @return a new array containing the specified range from the original array,
4037      *     truncated or padded with zeros to obtain the required length
4038      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
4039      *     or {@code from > original.length}
4040      * @throws IllegalArgumentException if {@code from > to}
4041      * @throws NullPointerException if {@code original} is null
4042      * @since 1.6
4043      */
4044     public static float[] copyOfRange(float[] original, int from, int to) {
4045         if (from == 0 && to == original.length) {
4046             return original.clone();
4047         }
4048         int newLength = to - from;
4049         if (newLength < 0) {
4050             throw new IllegalArgumentException(from + " > " + to);
4051         }
4052         float[] copy = new float[newLength];
4053         System.arraycopy(original, from, copy, 0,
4054                          Math.min(original.length - from, newLength));
4055         return copy;
4056     }
4057 
4058     /**
4059      * Copies the specified range of the specified array into a new array.
4060      * The initial index of the range ({@code from}) must lie between zero
4061      * and {@code original.length}, inclusive.  The value at
4062      * {@code original[from]} is placed into the initial element of the copy
4063      * (unless {@code from == original.length} or {@code from == to}).
4064      * Values from subsequent elements in the original array are placed into
4065      * subsequent elements in the copy.  The final index of the range
4066      * ({@code to}), which must be greater than or equal to {@code from},
4067      * may be greater than {@code original.length}, in which case
4068      * {@code 0d} is placed in all elements of the copy whose index is
4069      * greater than or equal to {@code original.length - from}.  The length
4070      * of the returned array will be {@code to - from}.
4071      *
4072      * @param original the array from which a range is to be copied
4073      * @param from the initial index of the range to be copied, inclusive
4074      * @param to the final index of the range to be copied, exclusive.
4075      *     (This index may lie outside the array.)
4076      * @return a new array containing the specified range from the original array,
4077      *     truncated or padded with zeros to obtain the required length
4078      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
4079      *     or {@code from > original.length}
4080      * @throws IllegalArgumentException if {@code from > to}
4081      * @throws NullPointerException if {@code original} is null
4082      * @since 1.6
4083      */
4084     public static double[] copyOfRange(double[] original, int from, int to) {
4085         if (from == 0 && to == original.length) {
4086             return original.clone();
4087         }
4088         int newLength = to - from;
4089         if (newLength < 0) {
4090             throw new IllegalArgumentException(from + " > " + to);
4091         }
4092         double[] copy = new double[newLength];
4093         System.arraycopy(original, from, copy, 0,
4094                          Math.min(original.length - from, newLength));
4095         return copy;
4096     }
4097 
4098     /**
4099      * Copies the specified range of the specified array into a new array.
4100      * The initial index of the range ({@code from}) must lie between zero
4101      * and {@code original.length}, inclusive.  The value at
4102      * {@code original[from]} is placed into the initial element of the copy
4103      * (unless {@code from == original.length} or {@code from == to}).
4104      * Values from subsequent elements in the original array are placed into
4105      * subsequent elements in the copy.  The final index of the range
4106      * ({@code to}), which must be greater than or equal to {@code from},
4107      * may be greater than {@code original.length}, in which case
4108      * {@code false} is placed in all elements of the copy whose index is
4109      * greater than or equal to {@code original.length - from}.  The length
4110      * of the returned array will be {@code to - from}.
4111      *
4112      * @param original the array from which a range is to be copied
4113      * @param from the initial index of the range to be copied, inclusive
4114      * @param to the final index of the range to be copied, exclusive.
4115      *     (This index may lie outside the array.)
4116      * @return a new array containing the specified range from the original array,
4117      *     truncated or padded with false elements to obtain the required length
4118      * @throws ArrayIndexOutOfBoundsException if {@code from < 0}
4119      *     or {@code from > original.length}
4120      * @throws IllegalArgumentException if {@code from > to}
4121      * @throws NullPointerException if {@code original} is null
4122      * @since 1.6
4123      */
4124     public static boolean[] copyOfRange(boolean[] original, int from, int to) {
4125         if (from == 0 && to == original.length) {
4126             return original.clone();
4127         }
4128         int newLength = to - from;
4129         if (newLength < 0) {
4130             throw new IllegalArgumentException(from + " > " + to);
4131         }
4132         boolean[] copy = new boolean[newLength];
4133         System.arraycopy(original, from, copy, 0,
4134                          Math.min(original.length - from, newLength));
4135         return copy;
4136     }
4137 
4138     // Misc
4139 
4140     /**
4141      * Returns a fixed-size list backed by the specified array. Changes made to
4142      * the array will be visible in the returned list, and changes made to the
4143      * list will be visible in the array. The returned list is
4144      * {@link Serializable} and implements {@link RandomAccess}.
4145      *
4146      * <p>The returned list implements the optional {@code Collection} methods, except
4147      * those that would change the size of the returned list. Those methods leave
4148      * the list unchanged and throw {@link UnsupportedOperationException}.
4149      *
4150      * <p>If the specified array's actual component type differs from the type
4151      * parameter T, this can result in operations on the returned list throwing an
4152      * {@code ArrayStoreException}.
4153      *
4154      * @apiNote
4155      * This method acts as bridge between array-based and collection-based
4156      * APIs, in combination with {@link Collection#toArray}.
4157      *
4158      * <p>This method provides a way to wrap an existing array:
4159      * <pre>{@code
4160      *     Integer[] numbers = ...
4161      *     ...
4162      *     List<Integer> values = Arrays.asList(numbers);
4163      * }</pre>
4164      *
4165      * <p>This method also provides a convenient way to create a fixed-size
4166      * list initialized to contain several elements:
4167      * <pre>{@code
4168      *     List<String> stooges = Arrays.asList("Larry", "Moe", "Curly");
4169      * }</pre>
4170      *
4171      * <p><em>The list returned by this method is modifiable.</em>
4172      * To create an unmodifiable list, use
4173      * {@link Collections#unmodifiableList Collections.unmodifiableList}
4174      * or <a href="List.html#unmodifiable">Unmodifiable Lists</a>.
4175      *
4176      * @param <T> the class of the objects in the array
4177      * @param a the array by which the list will be backed
4178      * @return a list view of the specified array
4179      * @throws NullPointerException if the specified array is {@code null}
4180      */
4181     @SafeVarargs
4182     @SuppressWarnings("varargs")
4183     public static <T> List<T> asList(T... a) {
4184         return new ArrayList<>(a);
4185     }
4186 
4187     /**
4188      * @serial include
4189      */
4190     private static class ArrayList<E> extends AbstractList<E>
4191         implements RandomAccess, java.io.Serializable
4192     {
4193         @java.io.Serial
4194         private static final long serialVersionUID = -2764017481108945198L;
4195         @SuppressWarnings("serial") // Conditionally serializable
4196         private final E[] a;
4197 
4198         ArrayList(E[] array) {
4199             a = Objects.requireNonNull(array);
4200         }
4201 
4202         @Override
4203         public int size() {
4204             return a.length;
4205         }
4206 
4207         @Override
4208         public Object[] toArray() {
4209             return Arrays.copyOf(a, a.length, Object[].class);
4210         }
4211 
4212         @Override
4213         @SuppressWarnings("unchecked")
4214         public <T> T[] toArray(T[] a) {
4215             int size = size();
4216             if (a.length < size)
4217                 return Arrays.copyOf(this.a, size,
4218                                      (Class<? extends T[]>) a.getClass());
4219             System.arraycopy(this.a, 0, a, 0, size);
4220             if (a.length > size)
4221                 a[size] = null;
4222             return a;
4223         }
4224 
4225         @Override
4226         public E get(int index) {
4227             return a[index];
4228         }
4229 
4230         @Override
4231         public E set(int index, E element) {
4232             E oldValue = a[index];
4233             a[index] = element;
4234             return oldValue;
4235         }
4236 
4237         @Override
4238         public int indexOf(Object o) {
4239             E[] a = this.a;
4240             if (o == null) {
4241                 for (int i = 0; i < a.length; i++)
4242                     if (a[i] == null)
4243                         return i;
4244             } else {
4245                 for (int i = 0; i < a.length; i++)
4246                     if (o.equals(a[i]))
4247                         return i;
4248             }
4249             return -1;
4250         }
4251 
4252         @Override
4253         public boolean contains(Object o) {
4254             return indexOf(o) >= 0;
4255         }
4256 
4257         @Override
4258         public Spliterator<E> spliterator() {
4259             return Spliterators.spliterator(a, Spliterator.ORDERED);
4260         }
4261 
4262         @Override
4263         public void forEach(Consumer<? super E> action) {
4264             Objects.requireNonNull(action);
4265             for (E e : a) {
4266                 action.accept(e);
4267             }
4268         }
4269 
4270         @Override
4271         public void replaceAll(UnaryOperator<E> operator) {
4272             Objects.requireNonNull(operator);
4273             E[] a = this.a;
4274             for (int i = 0; i < a.length; i++) {
4275                 a[i] = operator.apply(a[i]);
4276             }
4277         }
4278 
4279         @Override
4280         public void sort(Comparator<? super E> c) {
4281             Arrays.sort(a, c);
4282         }
4283 
4284         @Override
4285         public Iterator<E> iterator() {
4286             return new ArrayItr<>(a);
4287         }
4288     }
4289 
4290     private static class ArrayItr<E> implements Iterator<E> {
4291         private int cursor;
4292         private final E[] a;
4293 
4294         ArrayItr(E[] a) {
4295             this.a = a;
4296         }
4297 
4298         @Override
4299         public boolean hasNext() {
4300             return cursor < a.length;
4301         }
4302 
4303         @Override
4304         public E next() {
4305             int i = cursor;
4306             if (i >= a.length) {
4307                 throw new NoSuchElementException();
4308             }
4309             cursor = i + 1;
4310             return a[i];
4311         }
4312     }
4313 
4314     /**
4315      * Returns a hash code based on the contents of the specified array.
4316      * For any two {@code long} arrays {@code a} and {@code b}
4317      * such that {@code Arrays.equals(a, b)}, it is also the case that
4318      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4319      *
4320      * <p>The value returned by this method is the same value that would be
4321      * obtained by invoking the {@link List#hashCode() hashCode}
4322      * method on a {@link List} containing a sequence of {@link Long}
4323      * instances representing the elements of {@code a} in the same order.
4324      * If {@code a} is {@code null}, this method returns 0.
4325      *
4326      * @param a the array whose hash value to compute
4327      * @return a content-based hash code for {@code a}
4328      * @since 1.5
4329      */
4330     public static int hashCode(long[] a) {
4331         if (a == null) {
4332             return 0;
4333         }
4334         int result = 1;
4335         for (long element : a) {
4336             result = 31 * result + Long.hashCode(element);
4337         }
4338         return result;
4339     }
4340 
4341     /**
4342      * Returns a hash code based on the contents of the specified array.
4343      * For any two non-null {@code int} arrays {@code a} and {@code b}
4344      * such that {@code Arrays.equals(a, b)}, it is also the case that
4345      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4346      *
4347      * <p>The value returned by this method is the same value that would be
4348      * obtained by invoking the {@link List#hashCode() hashCode}
4349      * method on a {@link List} containing a sequence of {@link Integer}
4350      * instances representing the elements of {@code a} in the same order.
4351      * If {@code a} is {@code null}, this method returns 0.
4352      *
4353      * @param a the array whose hash value to compute
4354      * @return a content-based hash code for {@code a}
4355      * @since 1.5
4356      */
4357     public static int hashCode(int[] a) {
4358         if (a == null) {
4359             return 0;
4360         }
4361         return ArraysSupport.hashCode(a, 0, a.length, 1);
4362     }
4363 
4364     /**
4365      * Returns a hash code based on the contents of the specified array.
4366      * For any two {@code short} arrays {@code a} and {@code b}
4367      * such that {@code Arrays.equals(a, b)}, it is also the case that
4368      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4369      *
4370      * <p>The value returned by this method is the same value that would be
4371      * obtained by invoking the {@link List#hashCode() hashCode}
4372      * method on a {@link List} containing a sequence of {@link Short}
4373      * instances representing the elements of {@code a} in the same order.
4374      * If {@code a} is {@code null}, this method returns 0.
4375      *
4376      * @param a the array whose hash value to compute
4377      * @return a content-based hash code for {@code a}
4378      * @since 1.5
4379      */
4380     public static int hashCode(short[] a) {
4381         if (a == null) {
4382             return 0;
4383         }
4384         return ArraysSupport.hashCode(a, 0, a.length, 1);
4385     }
4386 
4387     /**
4388      * Returns a hash code based on the contents of the specified array.
4389      * For any two {@code char} arrays {@code a} and {@code b}
4390      * such that {@code Arrays.equals(a, b)}, it is also the case that
4391      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4392      *
4393      * <p>The value returned by this method is the same value that would be
4394      * obtained by invoking the {@link List#hashCode() hashCode}
4395      * method on a {@link List} containing a sequence of {@link Character}
4396      * instances representing the elements of {@code a} in the same order.
4397      * If {@code a} is {@code null}, this method returns 0.
4398      *
4399      * @param a the array whose hash value to compute
4400      * @return a content-based hash code for {@code a}
4401      * @since 1.5
4402      */
4403     public static int hashCode(char[] a) {
4404         if (a == null) {
4405             return 0;
4406         }
4407         return ArraysSupport.hashCode(a, 0, a.length, 1);
4408     }
4409 
4410     /**
4411      * Returns a hash code based on the contents of the specified array.
4412      * For any two {@code byte} arrays {@code a} and {@code b}
4413      * such that {@code Arrays.equals(a, b)}, it is also the case that
4414      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4415      *
4416      * <p>The value returned by this method is the same value that would be
4417      * obtained by invoking the {@link List#hashCode() hashCode}
4418      * method on a {@link List} containing a sequence of {@link Byte}
4419      * instances representing the elements of {@code a} in the same order.
4420      * If {@code a} is {@code null}, this method returns 0.
4421      *
4422      * @param a the array whose hash value to compute
4423      * @return a content-based hash code for {@code a}
4424      * @since 1.5
4425      */
4426     public static int hashCode(byte[] a) {
4427         if (a == null) {
4428             return 0;
4429         }
4430         return ArraysSupport.hashCode(a, 0, a.length, 1);
4431     }
4432 
4433     /**
4434      * Returns a hash code based on the contents of the specified array.
4435      * For any two {@code boolean} arrays {@code a} and {@code b}
4436      * such that {@code Arrays.equals(a, b)}, it is also the case that
4437      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4438      *
4439      * <p>The value returned by this method is the same value that would be
4440      * obtained by invoking the {@link List#hashCode() hashCode}
4441      * method on a {@link List} containing a sequence of {@link Boolean}
4442      * instances representing the elements of {@code a} in the same order.
4443      * If {@code a} is {@code null}, this method returns 0.
4444      *
4445      * @param a the array whose hash value to compute
4446      * @return a content-based hash code for {@code a}
4447      * @since 1.5
4448      */
4449     public static int hashCode(boolean[] a) {
4450         if (a == null)
4451             return 0;
4452 
4453         int result = 1;
4454         for (boolean element : a)
4455             result = 31 * result + Boolean.hashCode(element);
4456 
4457         return result;
4458     }
4459 
4460     /**
4461      * Returns a hash code based on the contents of the specified array.
4462      * For any two {@code float} arrays {@code a} and {@code b}
4463      * such that {@code Arrays.equals(a, b)}, it is also the case that
4464      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4465      *
4466      * <p>The value returned by this method is the same value that would be
4467      * obtained by invoking the {@link List#hashCode() hashCode}
4468      * method on a {@link List} containing a sequence of {@link Float}
4469      * instances representing the elements of {@code a} in the same order.
4470      * If {@code a} is {@code null}, this method returns 0.
4471      *
4472      * @param a the array whose hash value to compute
4473      * @return a content-based hash code for {@code a}
4474      * @since 1.5
4475      */
4476     public static int hashCode(float[] a) {
4477         if (a == null)
4478             return 0;
4479 
4480         int result = 1;
4481         for (float element : a)
4482             result = 31 * result + Float.hashCode(element);
4483 
4484         return result;
4485     }
4486 
4487     /**
4488      * Returns a hash code based on the contents of the specified array.
4489      * For any two {@code double} arrays {@code a} and {@code b}
4490      * such that {@code Arrays.equals(a, b)}, it is also the case that
4491      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4492      *
4493      * <p>The value returned by this method is the same value that would be
4494      * obtained by invoking the {@link List#hashCode() hashCode}
4495      * method on a {@link List} containing a sequence of {@link Double}
4496      * instances representing the elements of {@code a} in the same order.
4497      * If {@code a} is {@code null}, this method returns 0.
4498      *
4499      * @param a the array whose hash value to compute
4500      * @return a content-based hash code for {@code a}
4501      * @since 1.5
4502      */
4503     public static int hashCode(double[] a) {
4504         if (a == null)
4505             return 0;
4506 
4507         int result = 1;
4508         for (double element : a) {
4509             result = 31 * result + Double.hashCode(element);
4510         }
4511         return result;
4512     }
4513 
4514     /**
4515      * Returns a hash code based on the contents of the specified array.  If
4516      * the array contains other arrays as elements, the hash code is based on
4517      * their identities rather than their contents.  It is therefore
4518      * acceptable to invoke this method on an array that contains itself as an
4519      * element,  either directly or indirectly through one or more levels of
4520      * arrays.
4521      *
4522      * <p>For any two arrays {@code a} and {@code b} such that
4523      * {@code Arrays.equals(a, b)}, it is also the case that
4524      * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}.
4525      *
4526      * <p>The value returned by this method is equal to the value that would
4527      * be returned by {@code Arrays.asList(a).hashCode()}, unless {@code a}
4528      * is {@code null}, in which case {@code 0} is returned.
4529      *
4530      * @param a the array whose content-based hash code to compute
4531      * @return a content-based hash code for {@code a}
4532      * @see #deepHashCode(Object[])
4533      * @since 1.5
4534      */
4535     public static int hashCode(Object[] a) {
4536         if (a == null) {
4537             return 0;
4538         }
4539         return ArraysSupport.hashCode(a, 0, a.length, 1);
4540     }
4541 
4542     /**
4543      * Returns a hash code based on the "deep contents" of the specified
4544      * array.  If the array contains other arrays as elements, the
4545      * hash code is based on their contents and so on, ad infinitum.
4546      * It is therefore unacceptable to invoke this method on an array that
4547      * contains itself as an element, either directly or indirectly through
4548      * one or more levels of arrays.  The behavior of such an invocation is
4549      * undefined.
4550      *
4551      * <p>For any two arrays {@code a} and {@code b} such that
4552      * {@code Arrays.deepEquals(a, b)}, it is also the case that
4553      * {@code Arrays.deepHashCode(a) == Arrays.deepHashCode(b)}.
4554      *
4555      * <p>The computation of the value returned by this method is similar to
4556      * that of the value returned by {@link List#hashCode()} on a list
4557      * containing the same elements as {@code a} in the same order, with one
4558      * difference: If an element {@code e} of {@code a} is itself an array,
4559      * its hash code is computed not by calling {@code e.hashCode()}, but as
4560      * by calling the appropriate overloading of {@code Arrays.hashCode(e)}
4561      * if {@code e} is an array of a primitive type, or as by calling
4562      * {@code Arrays.deepHashCode(e)} recursively if {@code e} is an array
4563      * of a reference type.  If {@code a} is {@code null}, this method
4564      * returns 0.
4565      *
4566      * @param a the array whose deep-content-based hash code to compute
4567      * @return a deep-content-based hash code for {@code a}
4568      * @see #hashCode(Object[])
4569      * @since 1.5
4570      */
4571     public static int deepHashCode(Object[] a) {
4572         if (a == null)
4573             return 0;
4574 
4575         int result = 1;
4576 
4577         for (Object element : a) {
4578             final int elementHash;
4579             final Class<?> cl;
4580             if (element == null)
4581                 elementHash = 0;
4582             else if ((cl = element.getClass().getComponentType()) == null)
4583                 elementHash = element.hashCode();
4584             else if (element instanceof Object[])
4585                 elementHash = deepHashCode((Object[]) element);
4586             else
4587                 elementHash = primitiveArrayHashCode(element, cl);
4588 
4589             result = 31 * result + elementHash;
4590         }
4591 
4592         return result;
4593     }
4594 
4595     private static int primitiveArrayHashCode(Object a, Class<?> cl) {
4596         return
4597             (cl == byte.class)    ? hashCode((byte[]) a)    :
4598             (cl == int.class)     ? hashCode((int[]) a)     :
4599             (cl == long.class)    ? hashCode((long[]) a)    :
4600             (cl == char.class)    ? hashCode((char[]) a)    :
4601             (cl == short.class)   ? hashCode((short[]) a)   :
4602             (cl == boolean.class) ? hashCode((boolean[]) a) :
4603             (cl == double.class)  ? hashCode((double[]) a)  :
4604             // If new primitive types are ever added, this method must be
4605             // expanded or we will fail here with ClassCastException.
4606             hashCode((float[]) a);
4607     }
4608 
4609     /**
4610      * Returns {@code true} if the two specified arrays are <i>deeply
4611      * equal</i> to one another.  Unlike the {@link #equals(Object[],Object[])}
4612      * method, this method is appropriate for use with nested arrays of
4613      * arbitrary depth.
4614      *
4615      * <p>Two array references are considered deeply equal if both
4616      * are {@code null}, or if they refer to arrays that contain the same
4617      * number of elements and all corresponding pairs of elements in the two
4618      * arrays are deeply equal.
4619      *
4620      * <p>Two possibly {@code null} elements {@code e1} and {@code e2} are
4621      * deeply equal if any of the following conditions hold:
4622      * <ul>
4623      *    <li> {@code e1} and {@code e2} are both arrays of object reference
4624      *         types, and {@code Arrays.deepEquals(e1, e2) would return true}
4625      *    <li> {@code e1} and {@code e2} are arrays of the same primitive
4626      *         type, and the appropriate overloading of
4627      *         {@code Arrays.equals(e1, e2)} would return true.
4628      *    <li> {@code e1 == e2}
4629      *    <li> {@code e1.equals(e2)} would return true.
4630      * </ul>
4631      * Note that this definition permits {@code null} elements at any depth.
4632      *
4633      * <p>If either of the specified arrays contain themselves as elements
4634      * either directly or indirectly through one or more levels of arrays,
4635      * the behavior of this method is undefined.
4636      *
4637      * @param a1 one array to be tested for equality
4638      * @param a2 the other array to be tested for equality
4639      * @return {@code true} if the two arrays are equal
4640      * @see #equals(Object[],Object[])
4641      * @see Objects#deepEquals(Object, Object)
4642      * @since 1.5
4643      */
4644     public static boolean deepEquals(Object[] a1, Object[] a2) {
4645         if (a1 == a2)
4646             return true;
4647         if (a1 == null || a2==null)
4648             return false;
4649         int length = a1.length;
4650         if (a2.length != length)
4651             return false;
4652 
4653         for (int i = 0; i < length; i++) {
4654             Object e1 = a1[i];
4655             Object e2 = a2[i];
4656 
4657             if (e1 == e2)
4658                 continue;
4659             if (e1 == null)
4660                 return false;
4661 
4662             // Figure out whether the two elements are equal
4663             boolean eq = deepEquals0(e1, e2);
4664 
4665             if (!eq)
4666                 return false;
4667         }
4668         return true;
4669     }
4670 
4671     static boolean deepEquals0(Object e1, Object e2) {
4672         assert e1 != null;
4673         boolean eq;
4674         if (e1 instanceof Object[] && e2 instanceof Object[])
4675             eq = deepEquals ((Object[]) e1, (Object[]) e2);
4676         else if (e1 instanceof byte[] && e2 instanceof byte[])
4677             eq = equals((byte[]) e1, (byte[]) e2);
4678         else if (e1 instanceof short[] && e2 instanceof short[])
4679             eq = equals((short[]) e1, (short[]) e2);
4680         else if (e1 instanceof int[] && e2 instanceof int[])
4681             eq = equals((int[]) e1, (int[]) e2);
4682         else if (e1 instanceof long[] && e2 instanceof long[])
4683             eq = equals((long[]) e1, (long[]) e2);
4684         else if (e1 instanceof char[] && e2 instanceof char[])
4685             eq = equals((char[]) e1, (char[]) e2);
4686         else if (e1 instanceof float[] && e2 instanceof float[])
4687             eq = equals((float[]) e1, (float[]) e2);
4688         else if (e1 instanceof double[] && e2 instanceof double[])
4689             eq = equals((double[]) e1, (double[]) e2);
4690         else if (e1 instanceof boolean[] && e2 instanceof boolean[])
4691             eq = equals((boolean[]) e1, (boolean[]) e2);
4692         else
4693             eq = e1.equals(e2);
4694         return eq;
4695     }
4696 
4697     /**
4698      * Returns a string representation of the contents of the specified array.
4699      * The string representation consists of a list of the array's elements,
4700      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4701      * separated by the characters {@code ", "} (a comma followed by a
4702      * space).  Elements are converted to strings as by
4703      * {@code String.valueOf(long)}.  Returns {@code "null"} if {@code a}
4704      * is {@code null}.
4705      *
4706      * @param a the array whose string representation to return
4707      * @return a string representation of {@code a}
4708      * @since 1.5
4709      */
4710     public static String toString(long[] a) {
4711         if (a == null)
4712             return "null";
4713         int iMax = a.length - 1;
4714         if (iMax == -1)
4715             return "[]";
4716 
4717         StringBuilder b = new StringBuilder();
4718         b.append('[');
4719         for (int i = 0; ; i++) {
4720             b.append(a[i]);
4721             if (i == iMax)
4722                 return b.append(']').toString();
4723             b.append(", ");
4724         }
4725     }
4726 
4727     /**
4728      * Returns a string representation of the contents of the specified array.
4729      * The string representation consists of a list of the array's elements,
4730      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4731      * separated by the characters {@code ", "} (a comma followed by a
4732      * space).  Elements are converted to strings as by
4733      * {@code String.valueOf(int)}.  Returns {@code "null"} if {@code a} is
4734      * {@code null}.
4735      *
4736      * @param a the array whose string representation to return
4737      * @return a string representation of {@code a}
4738      * @since 1.5
4739      */
4740     public static String toString(int[] a) {
4741         if (a == null)
4742             return "null";
4743         int iMax = a.length - 1;
4744         if (iMax == -1)
4745             return "[]";
4746 
4747         StringBuilder b = new StringBuilder();
4748         b.append('[');
4749         for (int i = 0; ; i++) {
4750             b.append(a[i]);
4751             if (i == iMax)
4752                 return b.append(']').toString();
4753             b.append(", ");
4754         }
4755     }
4756 
4757     /**
4758      * Returns a string representation of the contents of the specified array.
4759      * The string representation consists of a list of the array's elements,
4760      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4761      * separated by the characters {@code ", "} (a comma followed by a
4762      * space).  Elements are converted to strings as by
4763      * {@code String.valueOf(short)}.  Returns {@code "null"} if {@code a}
4764      * is {@code null}.
4765      *
4766      * @param a the array whose string representation to return
4767      * @return a string representation of {@code a}
4768      * @since 1.5
4769      */
4770     public static String toString(short[] a) {
4771         if (a == null)
4772             return "null";
4773         int iMax = a.length - 1;
4774         if (iMax == -1)
4775             return "[]";
4776 
4777         StringBuilder b = new StringBuilder();
4778         b.append('[');
4779         for (int i = 0; ; i++) {
4780             b.append(a[i]);
4781             if (i == iMax)
4782                 return b.append(']').toString();
4783             b.append(", ");
4784         }
4785     }
4786 
4787     /**
4788      * Returns a string representation of the contents of the specified array.
4789      * The string representation consists of a list of the array's elements,
4790      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4791      * separated by the characters {@code ", "} (a comma followed by a
4792      * space).  Elements are converted to strings as by
4793      * {@code String.valueOf(char)}.  Returns {@code "null"} if {@code a}
4794      * is {@code null}.
4795      *
4796      * @param a the array whose string representation to return
4797      * @return a string representation of {@code a}
4798      * @since 1.5
4799      */
4800     public static String toString(char[] a) {
4801         if (a == null)
4802             return "null";
4803         int iMax = a.length - 1;
4804         if (iMax == -1)
4805             return "[]";
4806 
4807         StringBuilder b = new StringBuilder();
4808         b.append('[');
4809         for (int i = 0; ; i++) {
4810             b.append(a[i]);
4811             if (i == iMax)
4812                 return b.append(']').toString();
4813             b.append(", ");
4814         }
4815     }
4816 
4817     /**
4818      * Returns a string representation of the contents of the specified array.
4819      * The string representation consists of a list of the array's elements,
4820      * enclosed in square brackets ({@code "[]"}).  Adjacent elements
4821      * are separated by the characters {@code ", "} (a comma followed
4822      * by a space).  Elements are converted to strings as by
4823      * {@code String.valueOf(byte)}.  Returns {@code "null"} if
4824      * {@code a} is {@code null}.
4825      *
4826      * @param a the array whose string representation to return
4827      * @return a string representation of {@code a}
4828      * @since 1.5
4829      */
4830     public static String toString(byte[] a) {
4831         if (a == null)
4832             return "null";
4833         int iMax = a.length - 1;
4834         if (iMax == -1)
4835             return "[]";
4836 
4837         StringBuilder b = new StringBuilder();
4838         b.append('[');
4839         for (int i = 0; ; i++) {
4840             b.append(a[i]);
4841             if (i == iMax)
4842                 return b.append(']').toString();
4843             b.append(", ");
4844         }
4845     }
4846 
4847     /**
4848      * Returns a string representation of the contents of the specified array.
4849      * The string representation consists of a list of the array's elements,
4850      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4851      * separated by the characters {@code ", "} (a comma followed by a
4852      * space).  Elements are converted to strings as by
4853      * {@code String.valueOf(boolean)}.  Returns {@code "null"} if
4854      * {@code a} is {@code null}.
4855      *
4856      * @param a the array whose string representation to return
4857      * @return a string representation of {@code a}
4858      * @since 1.5
4859      */
4860     public static String toString(boolean[] a) {
4861         if (a == null)
4862             return "null";
4863         int iMax = a.length - 1;
4864         if (iMax == -1)
4865             return "[]";
4866 
4867         StringBuilder b = new StringBuilder();
4868         b.append('[');
4869         for (int i = 0; ; i++) {
4870             b.append(a[i]);
4871             if (i == iMax)
4872                 return b.append(']').toString();
4873             b.append(", ");
4874         }
4875     }
4876 
4877     /**
4878      * Returns a string representation of the contents of the specified array.
4879      * The string representation consists of a list of the array's elements,
4880      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4881      * separated by the characters {@code ", "} (a comma followed by a
4882      * space).  Elements are converted to strings as by
4883      * {@code String.valueOf(float)}.  Returns {@code "null"} if {@code a}
4884      * is {@code null}.
4885      *
4886      * @param a the array whose string representation to return
4887      * @return a string representation of {@code a}
4888      * @since 1.5
4889      */
4890     public static String toString(float[] a) {
4891         if (a == null)
4892             return "null";
4893 
4894         int iMax = a.length - 1;
4895         if (iMax == -1)
4896             return "[]";
4897 
4898         StringBuilder b = new StringBuilder();
4899         b.append('[');
4900         for (int i = 0; ; i++) {
4901             b.append(a[i]);
4902             if (i == iMax)
4903                 return b.append(']').toString();
4904             b.append(", ");
4905         }
4906     }
4907 
4908     /**
4909      * Returns a string representation of the contents of the specified array.
4910      * The string representation consists of a list of the array's elements,
4911      * enclosed in square brackets ({@code "[]"}).  Adjacent elements are
4912      * separated by the characters {@code ", "} (a comma followed by a
4913      * space).  Elements are converted to strings as by
4914      * {@code String.valueOf(double)}.  Returns {@code "null"} if {@code a}
4915      * is {@code null}.
4916      *
4917      * @param a the array whose string representation to return
4918      * @return a string representation of {@code a}
4919      * @since 1.5
4920      */
4921     public static String toString(double[] a) {
4922         if (a == null)
4923             return "null";
4924         int iMax = a.length - 1;
4925         if (iMax == -1)
4926             return "[]";
4927 
4928         StringBuilder b = new StringBuilder();
4929         b.append('[');
4930         for (int i = 0; ; i++) {
4931             b.append(a[i]);
4932             if (i == iMax)
4933                 return b.append(']').toString();
4934             b.append(", ");
4935         }
4936     }
4937 
4938     /**
4939      * Returns a string representation of the contents of the specified array.
4940      * If the array contains other arrays as elements, they are converted to
4941      * strings by the {@link Object#toString} method inherited from
4942      * {@code Object}, which describes their <i>identities</i> rather than
4943      * their contents.
4944      *
4945      * <p>The value returned by this method is equal to the value that would
4946      * be returned by {@code Arrays.asList(a).toString()}, unless {@code a}
4947      * is {@code null}, in which case {@code "null"} is returned.
4948      *
4949      * @param a the array whose string representation to return
4950      * @return a string representation of {@code a}
4951      * @see #deepToString(Object[])
4952      * @since 1.5
4953      */
4954     public static String toString(Object[] a) {
4955         if (a == null)
4956             return "null";
4957 
4958         int iMax = a.length - 1;
4959         if (iMax == -1)
4960             return "[]";
4961 
4962         StringBuilder b = new StringBuilder();
4963         b.append('[');
4964         for (int i = 0; ; i++) {
4965             b.append(String.valueOf(a[i]));
4966             if (i == iMax)
4967                 return b.append(']').toString();
4968             b.append(", ");
4969         }
4970     }
4971 
4972     /**
4973      * Returns a string representation of the "deep contents" of the specified
4974      * array.  If the array contains other arrays as elements, the string
4975      * representation contains their contents and so on.  This method is
4976      * designed for converting multidimensional arrays to strings.
4977      *
4978      * <p>The string representation consists of a list of the array's
4979      * elements, enclosed in square brackets ({@code "[]"}).  Adjacent
4980      * elements are separated by the characters {@code ", "} (a comma
4981      * followed by a space).  Elements are converted to strings as by
4982      * {@code String.valueOf(Object)}, unless they are themselves
4983      * arrays.
4984      *
4985      * <p>If an element {@code e} is an array of a primitive type, it is
4986      * converted to a string as by invoking the appropriate overloading of
4987      * {@code Arrays.toString(e)}.  If an element {@code e} is an array of a
4988      * reference type, it is converted to a string as by invoking
4989      * this method recursively.
4990      *
4991      * <p>To avoid infinite recursion, if the specified array contains itself
4992      * as an element, or contains an indirect reference to itself through one
4993      * or more levels of arrays, the self-reference is converted to the string
4994      * {@code "[...]"}.  For example, an array containing only a reference
4995      * to itself would be rendered as {@code "[[...]]"}.
4996      *
4997      * <p>This method returns {@code "null"} if the specified array
4998      * is {@code null}.
4999      *
5000      * @param a the array whose string representation to return
5001      * @return a string representation of {@code a}
5002      * @see #toString(Object[])
5003      * @since 1.5
5004      */
5005     public static String deepToString(Object[] a) {
5006         if (a == null)
5007             return "null";
5008 
5009         int bufLen = 20 * a.length;
5010         if (a.length != 0 && bufLen <= 0)
5011             bufLen = Integer.MAX_VALUE;
5012         StringBuilder buf = new StringBuilder(bufLen);
5013         deepToString(a, buf, new HashSet<>());
5014         return buf.toString();
5015     }
5016 
5017     private static void deepToString(Object[] a, StringBuilder buf,
5018                                      Set<Object[]> dejaVu) {
5019         if (a == null) {
5020             buf.append("null");
5021             return;
5022         }
5023         int iMax = a.length - 1;
5024         if (iMax == -1) {
5025             buf.append("[]");
5026             return;
5027         }
5028 
5029         dejaVu.add(a);
5030         buf.append('[');
5031         for (int i = 0; ; i++) {
5032 
5033             Object element = a[i];
5034             if (element == null) {
5035                 buf.append("null");
5036             } else {
5037                 Class<?> eClass = element.getClass();
5038 
5039                 if (eClass.isArray()) {
5040                     if (eClass == byte[].class)
5041                         buf.append(toString((byte[]) element));
5042                     else if (eClass == short[].class)
5043                         buf.append(toString((short[]) element));
5044                     else if (eClass == int[].class)
5045                         buf.append(toString((int[]) element));
5046                     else if (eClass == long[].class)
5047                         buf.append(toString((long[]) element));
5048                     else if (eClass == char[].class)
5049                         buf.append(toString((char[]) element));
5050                     else if (eClass == float[].class)
5051                         buf.append(toString((float[]) element));
5052                     else if (eClass == double[].class)
5053                         buf.append(toString((double[]) element));
5054                     else if (eClass == boolean[].class)
5055                         buf.append(toString((boolean[]) element));
5056                     else { // element is an array of object references
5057                         if (dejaVu.contains(element))
5058                             buf.append("[...]");
5059                         else
5060                             deepToString((Object[])element, buf, dejaVu);
5061                     }
5062                 } else {  // element is non-null and not an array
5063                     buf.append(element.toString());
5064                 }
5065             }
5066             if (i == iMax)
5067                 break;
5068             buf.append(", ");
5069         }
5070         buf.append(']');
5071         dejaVu.remove(a);
5072     }
5073 
5074 
5075     /**
5076      * Set all elements of the specified array, using the provided
5077      * generator function to compute each element.
5078      *
5079      * <p>If the generator function throws an exception, it is relayed to
5080      * the caller and the array is left in an indeterminate state.
5081      *
5082      * @apiNote
5083      * Setting a subrange of an array, using a generator function to compute
5084      * each element, can be written as follows:
5085      * <pre>{@code
5086      * IntStream.range(startInclusive, endExclusive)
5087      *          .forEach(i -> array[i] = generator.apply(i));
5088      * }</pre>
5089      *
5090      * @param <T> type of elements of the array
5091      * @param array array to be initialized
5092      * @param generator a function accepting an index and producing the desired
5093      *        value for that position
5094      * @throws NullPointerException if the generator is null
5095      * @since 1.8
5096      */
5097     public static <T> void setAll(T[] array, IntFunction<? extends T> generator) {
5098         Objects.requireNonNull(generator);
5099         for (int i = 0; i < array.length; i++)
5100             array[i] = generator.apply(i);
5101     }
5102 
5103     /**
5104      * Set all elements of the specified array, in parallel, using the
5105      * provided generator function to compute each element.
5106      *
5107      * <p>If the generator function throws an exception, an unchecked exception
5108      * is thrown from {@code parallelSetAll} and the array is left in an
5109      * indeterminate state.
5110      *
5111      * @apiNote
5112      * Setting a subrange of an array, in parallel, using a generator function
5113      * to compute each element, can be written as follows:
5114      * <pre>{@code
5115      * IntStream.range(startInclusive, endExclusive)
5116      *          .parallel()
5117      *          .forEach(i -> array[i] = generator.apply(i));
5118      * }</pre>
5119      *
5120      * @param <T> type of elements of the array
5121      * @param array array to be initialized
5122      * @param generator a function accepting an index and producing the desired
5123      *        value for that position
5124      * @throws NullPointerException if the generator is null
5125      * @since 1.8
5126      */
5127     public static <T> void parallelSetAll(T[] array, IntFunction<? extends T> generator) {
5128         Objects.requireNonNull(generator);
5129         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.apply(i); });
5130     }
5131 
5132     /**
5133      * Set all elements of the specified array, using the provided
5134      * generator function to compute each element.
5135      *
5136      * <p>If the generator function throws an exception, it is relayed to
5137      * the caller and the array is left in an indeterminate state.
5138      *
5139      * @apiNote
5140      * Setting a subrange of an array, using a generator function to compute
5141      * each element, can be written as follows:
5142      * <pre>{@code
5143      * IntStream.range(startInclusive, endExclusive)
5144      *          .forEach(i -> array[i] = generator.applyAsInt(i));
5145      * }</pre>
5146      *
5147      * @param array array to be initialized
5148      * @param generator a function accepting an index and producing the desired
5149      *        value for that position
5150      * @throws NullPointerException if the generator is null
5151      * @since 1.8
5152      */
5153     public static void setAll(int[] array, IntUnaryOperator generator) {
5154         Objects.requireNonNull(generator);
5155         for (int i = 0; i < array.length; i++)
5156             array[i] = generator.applyAsInt(i);
5157     }
5158 
5159     /**
5160      * Set all elements of the specified array, in parallel, using the
5161      * provided generator function to compute each element.
5162      *
5163      * <p>If the generator function throws an exception, an unchecked exception
5164      * is thrown from {@code parallelSetAll} and the array is left in an
5165      * indeterminate state.
5166      *
5167      * @apiNote
5168      * Setting a subrange of an array, in parallel, using a generator function
5169      * to compute each element, can be written as follows:
5170      * <pre>{@code
5171      * IntStream.range(startInclusive, endExclusive)
5172      *          .parallel()
5173      *          .forEach(i -> array[i] = generator.applyAsInt(i));
5174      * }</pre>
5175      *
5176      * @param array array to be initialized
5177      * @param generator a function accepting an index and producing the desired
5178      * value for that position
5179      * @throws NullPointerException if the generator is null
5180      * @since 1.8
5181      */
5182     public static void parallelSetAll(int[] array, IntUnaryOperator generator) {
5183         Objects.requireNonNull(generator);
5184         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsInt(i); });
5185     }
5186 
5187     /**
5188      * Set all elements of the specified array, using the provided
5189      * generator function to compute each element.
5190      *
5191      * <p>If the generator function throws an exception, it is relayed to
5192      * the caller and the array is left in an indeterminate state.
5193      *
5194      * @apiNote
5195      * Setting a subrange of an array, using a generator function to compute
5196      * each element, can be written as follows:
5197      * <pre>{@code
5198      * IntStream.range(startInclusive, endExclusive)
5199      *          .forEach(i -> array[i] = generator.applyAsLong(i));
5200      * }</pre>
5201      *
5202      * @param array array to be initialized
5203      * @param generator a function accepting an index and producing the desired
5204      *        value for that position
5205      * @throws NullPointerException if the generator is null
5206      * @since 1.8
5207      */
5208     public static void setAll(long[] array, IntToLongFunction generator) {
5209         Objects.requireNonNull(generator);
5210         for (int i = 0; i < array.length; i++)
5211             array[i] = generator.applyAsLong(i);
5212     }
5213 
5214     /**
5215      * Set all elements of the specified array, in parallel, using the
5216      * provided generator function to compute each element.
5217      *
5218      * <p>If the generator function throws an exception, an unchecked exception
5219      * is thrown from {@code parallelSetAll} and the array is left in an
5220      * indeterminate state.
5221      *
5222      * @apiNote
5223      * Setting a subrange of an array, in parallel, using a generator function
5224      * to compute each element, can be written as follows:
5225      * <pre>{@code
5226      * IntStream.range(startInclusive, endExclusive)
5227      *          .parallel()
5228      *          .forEach(i -> array[i] = generator.applyAsLong(i));
5229      * }</pre>
5230      *
5231      * @param array array to be initialized
5232      * @param generator a function accepting an index and producing the desired
5233      *        value for that position
5234      * @throws NullPointerException if the generator is null
5235      * @since 1.8
5236      */
5237     public static void parallelSetAll(long[] array, IntToLongFunction generator) {
5238         Objects.requireNonNull(generator);
5239         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsLong(i); });
5240     }
5241 
5242     /**
5243      * Set all elements of the specified array, using the provided
5244      * generator function to compute each element.
5245      *
5246      * <p>If the generator function throws an exception, it is relayed to
5247      * the caller and the array is left in an indeterminate state.
5248      *
5249      * @apiNote
5250      * Setting a subrange of an array, using a generator function to compute
5251      * each element, can be written as follows:
5252      * <pre>{@code
5253      * IntStream.range(startInclusive, endExclusive)
5254      *          .forEach(i -> array[i] = generator.applyAsDouble(i));
5255      * }</pre>
5256      *
5257      * @param array array to be initialized
5258      * @param generator a function accepting an index and producing the desired
5259      *        value for that position
5260      * @throws NullPointerException if the generator is null
5261      * @since 1.8
5262      */
5263     public static void setAll(double[] array, IntToDoubleFunction generator) {
5264         Objects.requireNonNull(generator);
5265         for (int i = 0; i < array.length; i++)
5266             array[i] = generator.applyAsDouble(i);
5267     }
5268 
5269     /**
5270      * Set all elements of the specified array, in parallel, using the
5271      * provided generator function to compute each element.
5272      *
5273      * <p>If the generator function throws an exception, an unchecked exception
5274      * is thrown from {@code parallelSetAll} and the array is left in an
5275      * indeterminate state.
5276      *
5277      * @apiNote
5278      * Setting a subrange of an array, in parallel, using a generator function
5279      * to compute each element, can be written as follows:
5280      * <pre>{@code
5281      * IntStream.range(startInclusive, endExclusive)
5282      *          .parallel()
5283      *          .forEach(i -> array[i] = generator.applyAsDouble(i));
5284      * }</pre>
5285      *
5286      * @param array array to be initialized
5287      * @param generator a function accepting an index and producing the desired
5288      *        value for that position
5289      * @throws NullPointerException if the generator is null
5290      * @since 1.8
5291      */
5292     public static void parallelSetAll(double[] array, IntToDoubleFunction generator) {
5293         Objects.requireNonNull(generator);
5294         IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsDouble(i); });
5295     }
5296 
5297     /**
5298      * Returns a {@link Spliterator} covering all of the specified array.
5299      *
5300      * <p>The spliterator reports {@link Spliterator#SIZED},
5301      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5302      * {@link Spliterator#IMMUTABLE}.
5303      *
5304      * @param <T> type of elements
5305      * @param array the array, assumed to be unmodified during use
5306      * @return a spliterator for the array elements
5307      * @since 1.8
5308      */
5309     public static <T> Spliterator<T> spliterator(T[] array) {
5310         return Spliterators.spliterator(array,
5311                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5312     }
5313 
5314     /**
5315      * Returns a {@link Spliterator} covering the specified range of the
5316      * specified array.
5317      *
5318      * <p>The spliterator reports {@link Spliterator#SIZED},
5319      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5320      * {@link Spliterator#IMMUTABLE}.
5321      *
5322      * @param <T> type of elements
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 <T> Spliterator<T> spliterator(T[] 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.OfInt} 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 a spliterator for the array elements
5347      * @since 1.8
5348      */
5349     public static Spliterator.OfInt spliterator(int[] array) {
5350         return Spliterators.spliterator(array,
5351                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5352     }
5353 
5354     /**
5355      * Returns a {@link Spliterator.OfInt} 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.OfInt spliterator(int[] 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.OfLong} covering all of the specified array.
5379      *
5380      * <p>The spliterator reports {@link Spliterator#SIZED},
5381      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5382      * {@link Spliterator#IMMUTABLE}.
5383      *
5384      * @param array the array, assumed to be unmodified during use
5385      * @return the spliterator for the array elements
5386      * @since 1.8
5387      */
5388     public static Spliterator.OfLong spliterator(long[] array) {
5389         return Spliterators.spliterator(array,
5390                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5391     }
5392 
5393     /**
5394      * Returns a {@link Spliterator.OfLong} covering the specified range of the
5395      * specified array.
5396      *
5397      * <p>The spliterator reports {@link Spliterator#SIZED},
5398      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5399      * {@link Spliterator#IMMUTABLE}.
5400      *
5401      * @param array the array, assumed to be unmodified during use
5402      * @param startInclusive the first index to cover, inclusive
5403      * @param endExclusive index immediately past the last index to cover
5404      * @return a spliterator for the array elements
5405      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5406      *         negative, {@code endExclusive} is less than
5407      *         {@code startInclusive}, or {@code endExclusive} is greater than
5408      *         the array size
5409      * @since 1.8
5410      */
5411     public static Spliterator.OfLong spliterator(long[] array, int startInclusive, int endExclusive) {
5412         return Spliterators.spliterator(array, startInclusive, endExclusive,
5413                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5414     }
5415 
5416     /**
5417      * Returns a {@link Spliterator.OfDouble} covering all of the specified
5418      * array.
5419      *
5420      * <p>The spliterator reports {@link Spliterator#SIZED},
5421      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5422      * {@link Spliterator#IMMUTABLE}.
5423      *
5424      * @param array the array, assumed to be unmodified during use
5425      * @return a spliterator for the array elements
5426      * @since 1.8
5427      */
5428     public static Spliterator.OfDouble spliterator(double[] array) {
5429         return Spliterators.spliterator(array,
5430                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5431     }
5432 
5433     /**
5434      * Returns a {@link Spliterator.OfDouble} covering the specified range of
5435      * the specified array.
5436      *
5437      * <p>The spliterator reports {@link Spliterator#SIZED},
5438      * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and
5439      * {@link Spliterator#IMMUTABLE}.
5440      *
5441      * @param array the array, assumed to be unmodified during use
5442      * @param startInclusive the first index to cover, inclusive
5443      * @param endExclusive index immediately past the last index to cover
5444      * @return a spliterator for the array elements
5445      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5446      *         negative, {@code endExclusive} is less than
5447      *         {@code startInclusive}, or {@code endExclusive} is greater than
5448      *         the array size
5449      * @since 1.8
5450      */
5451     public static Spliterator.OfDouble spliterator(double[] array, int startInclusive, int endExclusive) {
5452         return Spliterators.spliterator(array, startInclusive, endExclusive,
5453                                         Spliterator.ORDERED | Spliterator.IMMUTABLE);
5454     }
5455 
5456     /**
5457      * Returns a sequential {@link Stream} with the specified array as its
5458      * source.
5459      *
5460      * @param <T> The type of the array elements
5461      * @param array The array, assumed to be unmodified during use
5462      * @return a {@code Stream} for the array
5463      * @since 1.8
5464      */
5465     public static <T> Stream<T> stream(T[] array) {
5466         return stream(array, 0, array.length);
5467     }
5468 
5469     /**
5470      * Returns a sequential {@link Stream} with the specified range of the
5471      * specified array as its source.
5472      *
5473      * @param <T> the type of the array elements
5474      * @param array the array, assumed to be unmodified during use
5475      * @param startInclusive the first index to cover, inclusive
5476      * @param endExclusive index immediately past the last index to cover
5477      * @return a {@code Stream} for the array range
5478      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5479      *         negative, {@code endExclusive} is less than
5480      *         {@code startInclusive}, or {@code endExclusive} is greater than
5481      *         the array size
5482      * @since 1.8
5483      */
5484     public static <T> Stream<T> stream(T[] array, int startInclusive, int endExclusive) {
5485         return StreamSupport.stream(spliterator(array, startInclusive, endExclusive), false);
5486     }
5487 
5488     /**
5489      * Returns a sequential {@link IntStream} with the specified array as its
5490      * source.
5491      *
5492      * @param array the array, assumed to be unmodified during use
5493      * @return an {@code IntStream} for the array
5494      * @since 1.8
5495      */
5496     public static IntStream stream(int[] array) {
5497         return stream(array, 0, array.length);
5498     }
5499 
5500     /**
5501      * Returns a sequential {@link IntStream} with the specified range of the
5502      * specified array as its source.
5503      *
5504      * @param array the array, assumed to be unmodified during use
5505      * @param startInclusive the first index to cover, inclusive
5506      * @param endExclusive index immediately past the last index to cover
5507      * @return an {@code IntStream} for the array range
5508      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5509      *         negative, {@code endExclusive} is less than
5510      *         {@code startInclusive}, or {@code endExclusive} is greater than
5511      *         the array size
5512      * @since 1.8
5513      */
5514     public static IntStream stream(int[] array, int startInclusive, int endExclusive) {
5515         return StreamSupport.intStream(spliterator(array, startInclusive, endExclusive), false);
5516     }
5517 
5518     /**
5519      * Returns a sequential {@link LongStream} with the specified array as its
5520      * source.
5521      *
5522      * @param array the array, assumed to be unmodified during use
5523      * @return a {@code LongStream} for the array
5524      * @since 1.8
5525      */
5526     public static LongStream stream(long[] array) {
5527         return stream(array, 0, array.length);
5528     }
5529 
5530     /**
5531      * Returns a sequential {@link LongStream} with the specified range of the
5532      * specified array as its source.
5533      *
5534      * @param array the array, assumed to be unmodified during use
5535      * @param startInclusive the first index to cover, inclusive
5536      * @param endExclusive index immediately past the last index to cover
5537      * @return a {@code LongStream} for the array range
5538      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5539      *         negative, {@code endExclusive} is less than
5540      *         {@code startInclusive}, or {@code endExclusive} is greater than
5541      *         the array size
5542      * @since 1.8
5543      */
5544     public static LongStream stream(long[] array, int startInclusive, int endExclusive) {
5545         return StreamSupport.longStream(spliterator(array, startInclusive, endExclusive), false);
5546     }
5547 
5548     /**
5549      * Returns a sequential {@link DoubleStream} with the specified array as its
5550      * source.
5551      *
5552      * @param array the array, assumed to be unmodified during use
5553      * @return a {@code DoubleStream} for the array
5554      * @since 1.8
5555      */
5556     public static DoubleStream stream(double[] array) {
5557         return stream(array, 0, array.length);
5558     }
5559 
5560     /**
5561      * Returns a sequential {@link DoubleStream} with the specified range of the
5562      * specified array as its source.
5563      *
5564      * @param array the array, assumed to be unmodified during use
5565      * @param startInclusive the first index to cover, inclusive
5566      * @param endExclusive index immediately past the last index to cover
5567      * @return a {@code DoubleStream} for the array range
5568      * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is
5569      *         negative, {@code endExclusive} is less than
5570      *         {@code startInclusive}, or {@code endExclusive} is greater than
5571      *         the array size
5572      * @since 1.8
5573      */
5574     public static DoubleStream stream(double[] array, int startInclusive, int endExclusive) {
5575         return StreamSupport.doubleStream(spliterator(array, startInclusive, endExclusive), false);
5576     }
5577 
5578 
5579     // Comparison methods
5580 
5581     // Compare boolean
5582 
5583     /**
5584      * Compares two {@code boolean} arrays lexicographically.
5585      *
5586      * <p>If the two arrays share a common prefix then the lexicographic
5587      * comparison is the result of comparing two elements, as if by
5588      * {@link Boolean#compare(boolean, boolean)}, at an index within the
5589      * respective arrays that is the prefix length.
5590      * Otherwise, one array is a proper prefix of the other and, lexicographic
5591      * comparison is the result of comparing the two array lengths.
5592      * (See {@link #mismatch(boolean[], boolean[])} for the definition of a
5593      * common and proper prefix.)
5594      *
5595      * <p>A {@code null} array reference is considered lexicographically less
5596      * than a non-{@code null} array reference.  Two {@code null} array
5597      * references are considered equal.
5598      *
5599      * <p>The comparison is consistent with {@link #equals(boolean[], boolean[]) equals},
5600      * more specifically the following holds for arrays {@code a} and {@code b}:
5601      * <pre>{@code
5602      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
5603      * }</pre>
5604      *
5605      * @apiNote
5606      * <p>This method behaves as if (for non-{@code null} array references):
5607      * <pre>{@code
5608      *     int i = Arrays.mismatch(a, b);
5609      *     if (i >= 0 && i < Math.min(a.length, b.length))
5610      *         return Boolean.compare(a[i], b[i]);
5611      *     return a.length - b.length;
5612      * }</pre>
5613      *
5614      * @param a the first array to compare
5615      * @param b the second array to compare
5616      * @return the value {@code 0} if the first and second array are equal and
5617      *         contain the same elements in the same order;
5618      *         a value less than {@code 0} if the first array is
5619      *         lexicographically less than the second array; and
5620      *         a value greater than {@code 0} if the first array is
5621      *         lexicographically greater than the second array
5622      * @since 9
5623      */
5624     public static int compare(boolean[] a, boolean[] b) {
5625         if (a == b)
5626             return 0;
5627         if (a == null || b == null)
5628             return a == null ? -1 : 1;
5629 
5630         int i = ArraysSupport.mismatch(a, b,
5631                                        Math.min(a.length, b.length));
5632         if (i >= 0) {
5633             return Boolean.compare(a[i], b[i]);
5634         }
5635 
5636         return a.length - b.length;
5637     }
5638 
5639     /**
5640      * Compares two {@code boolean} arrays lexicographically over the specified
5641      * ranges.
5642      *
5643      * <p>If the two arrays, over the specified ranges, share a common prefix
5644      * then the lexicographic comparison is the result of comparing two
5645      * elements, as if by {@link Boolean#compare(boolean, boolean)}, at a
5646      * relative index within the respective arrays that is the length of the
5647      * prefix.
5648      * Otherwise, one array is a proper prefix of the other and, lexicographic
5649      * comparison is the result of comparing the two range lengths.
5650      * (See {@link #mismatch(boolean[], int, int, boolean[], int, int)} for the
5651      * definition of a common and proper prefix.)
5652      *
5653      * <p>The comparison is consistent with
5654      * {@link #equals(boolean[], int, int, boolean[], int, int) equals}, more
5655      * specifically the following holds for arrays {@code a} and {@code b} with
5656      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
5657      * [{@code bFromIndex}, {@code bToIndex}) respectively:
5658      * <pre>{@code
5659      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
5660      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
5661      * }</pre>
5662      *
5663      * @apiNote
5664      * <p>This method behaves as if:
5665      * <pre>{@code
5666      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
5667      *                             b, bFromIndex, bToIndex);
5668      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
5669      *         return Boolean.compare(a[aFromIndex + i], b[bFromIndex + i]);
5670      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
5671      * }</pre>
5672      *
5673      * @param a the first array to compare
5674      * @param aFromIndex the index (inclusive) of the first element in the
5675      *                   first array to be compared
5676      * @param aToIndex the index (exclusive) of the last element in the
5677      *                 first array to be compared
5678      * @param b the second array to compare
5679      * @param bFromIndex the index (inclusive) of the first element in the
5680      *                   second array to be compared
5681      * @param bToIndex the index (exclusive) of the last element in the
5682      *                 second array to be compared
5683      * @return the value {@code 0} if, over the specified ranges, the first and
5684      *         second array are equal and contain the same elements in the same
5685      *         order;
5686      *         a value less than {@code 0} if, over the specified ranges, the
5687      *         first array is lexicographically less than the second array; and
5688      *         a value greater than {@code 0} if, over the specified ranges, the
5689      *         first array is lexicographically greater than the second array
5690      * @throws IllegalArgumentException
5691      *         if {@code aFromIndex > aToIndex} or
5692      *         if {@code bFromIndex > bToIndex}
5693      * @throws ArrayIndexOutOfBoundsException
5694      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
5695      *         if {@code bFromIndex < 0 or bToIndex > b.length}
5696      * @throws NullPointerException
5697      *         if either array is {@code null}
5698      * @since 9
5699      */
5700     public static int compare(boolean[] a, int aFromIndex, int aToIndex,
5701                               boolean[] b, int bFromIndex, int bToIndex) {
5702         rangeCheck(a.length, aFromIndex, aToIndex);
5703         rangeCheck(b.length, bFromIndex, bToIndex);
5704 
5705         int aLength = aToIndex - aFromIndex;
5706         int bLength = bToIndex - bFromIndex;
5707         int i = ArraysSupport.mismatch(a, aFromIndex,
5708                                        b, bFromIndex,
5709                                        Math.min(aLength, bLength));
5710         if (i >= 0) {
5711             return Boolean.compare(a[aFromIndex + i], b[bFromIndex + i]);
5712         }
5713 
5714         return aLength - bLength;
5715     }
5716 
5717     // Compare byte
5718 
5719     /**
5720      * Compares two {@code byte} arrays lexicographically.
5721      *
5722      * <p>If the two arrays share a common prefix then the lexicographic
5723      * comparison is the result of comparing two elements, as if by
5724      * {@link Byte#compare(byte, byte)}, at an index within the respective
5725      * arrays that is the prefix length.
5726      * Otherwise, one array is a proper prefix of the other and, lexicographic
5727      * comparison is the result of comparing the two array lengths.
5728      * (See {@link #mismatch(byte[], byte[])} for the definition of a common and
5729      * proper prefix.)
5730      *
5731      * <p>A {@code null} array reference is considered lexicographically less
5732      * than a non-{@code null} array reference.  Two {@code null} array
5733      * references are considered equal.
5734      *
5735      * <p>The comparison is consistent with {@link #equals(byte[], byte[]) equals},
5736      * more specifically the following holds for arrays {@code a} and {@code b}:
5737      * <pre>{@code
5738      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
5739      * }</pre>
5740      *
5741      * @apiNote
5742      * <p>This method behaves as if (for non-{@code null} array references):
5743      * <pre>{@code
5744      *     int i = Arrays.mismatch(a, b);
5745      *     if (i >= 0 && i < Math.min(a.length, b.length))
5746      *         return Byte.compare(a[i], b[i]);
5747      *     return a.length - b.length;
5748      * }</pre>
5749      *
5750      * @param a the first array to compare
5751      * @param b the second array to compare
5752      * @return the value {@code 0} if the first and second array are equal and
5753      *         contain the same elements in the same order;
5754      *         a value less than {@code 0} if the first array is
5755      *         lexicographically less than the second array; and
5756      *         a value greater than {@code 0} if the first array is
5757      *         lexicographically greater than the second array
5758      * @since 9
5759      */
5760     public static int compare(byte[] a, byte[] b) {
5761         if (a == b)
5762             return 0;
5763         if (a == null || b == null)
5764             return a == null ? -1 : 1;
5765 
5766         int i = ArraysSupport.mismatch(a, b,
5767                                        Math.min(a.length, b.length));
5768         if (i >= 0) {
5769             return Byte.compare(a[i], b[i]);
5770         }
5771 
5772         return a.length - b.length;
5773     }
5774 
5775     /**
5776      * Compares two {@code byte} arrays lexicographically over the specified
5777      * ranges.
5778      *
5779      * <p>If the two arrays, over the specified ranges, share a common prefix
5780      * then the lexicographic comparison is the result of comparing two
5781      * elements, as if by {@link Byte#compare(byte, byte)}, at a relative index
5782      * within the respective arrays that is the length of the prefix.
5783      * Otherwise, one array is a proper prefix of the other and, lexicographic
5784      * comparison is the result of comparing the two range lengths.
5785      * (See {@link #mismatch(byte[], int, int, byte[], int, int)} for the
5786      * definition of a common and proper prefix.)
5787      *
5788      * <p>The comparison is consistent with
5789      * {@link #equals(byte[], int, int, byte[], int, int) equals}, more
5790      * specifically the following holds for arrays {@code a} and {@code b} with
5791      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
5792      * [{@code bFromIndex}, {@code bToIndex}) respectively:
5793      * <pre>{@code
5794      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
5795      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
5796      * }</pre>
5797      *
5798      * @apiNote
5799      * <p>This method behaves as if:
5800      * <pre>{@code
5801      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
5802      *                             b, bFromIndex, bToIndex);
5803      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
5804      *         return Byte.compare(a[aFromIndex + i], b[bFromIndex + i]);
5805      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
5806      * }</pre>
5807      *
5808      * @param a the first array to compare
5809      * @param aFromIndex the index (inclusive) of the first element in the
5810      *                   first array to be compared
5811      * @param aToIndex the index (exclusive) of the last element in the
5812      *                 first array to be compared
5813      * @param b the second array to compare
5814      * @param bFromIndex the index (inclusive) of the first element in the
5815      *                   second array to be compared
5816      * @param bToIndex the index (exclusive) of the last element in the
5817      *                 second array to be compared
5818      * @return the value {@code 0} if, over the specified ranges, the first and
5819      *         second array are equal and contain the same elements in the same
5820      *         order;
5821      *         a value less than {@code 0} if, over the specified ranges, the
5822      *         first array is lexicographically less than the second array; and
5823      *         a value greater than {@code 0} if, over the specified ranges, the
5824      *         first array is lexicographically greater than the second array
5825      * @throws IllegalArgumentException
5826      *         if {@code aFromIndex > aToIndex} or
5827      *         if {@code bFromIndex > bToIndex}
5828      * @throws ArrayIndexOutOfBoundsException
5829      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
5830      *         if {@code bFromIndex < 0 or bToIndex > b.length}
5831      * @throws NullPointerException
5832      *         if either array is {@code null}
5833      * @since 9
5834      */
5835     public static int compare(byte[] a, int aFromIndex, int aToIndex,
5836                               byte[] b, int bFromIndex, int bToIndex) {
5837         rangeCheck(a.length, aFromIndex, aToIndex);
5838         rangeCheck(b.length, bFromIndex, bToIndex);
5839 
5840         int aLength = aToIndex - aFromIndex;
5841         int bLength = bToIndex - bFromIndex;
5842         int i = ArraysSupport.mismatch(a, aFromIndex,
5843                                        b, bFromIndex,
5844                                        Math.min(aLength, bLength));
5845         if (i >= 0) {
5846             return Byte.compare(a[aFromIndex + i], b[bFromIndex + i]);
5847         }
5848 
5849         return aLength - bLength;
5850     }
5851 
5852     /**
5853      * Compares two {@code byte} arrays lexicographically, numerically treating
5854      * elements as unsigned.
5855      *
5856      * <p>If the two arrays share a common prefix then the lexicographic
5857      * comparison is the result of comparing two elements, as if by
5858      * {@link Byte#compareUnsigned(byte, byte)}, at an index within the
5859      * respective arrays that is the prefix length.
5860      * Otherwise, one array is a proper prefix of the other and, lexicographic
5861      * comparison is the result of comparing the two array lengths.
5862      * (See {@link #mismatch(byte[], byte[])} for the definition of a common
5863      * and proper prefix.)
5864      *
5865      * <p>A {@code null} array reference is considered lexicographically less
5866      * than a non-{@code null} array reference.  Two {@code null} array
5867      * references are considered equal.
5868      *
5869      * @apiNote
5870      * <p>This method behaves as if (for non-{@code null} array references):
5871      * <pre>{@code
5872      *     int i = Arrays.mismatch(a, b);
5873      *     if (i >= 0 && i < Math.min(a.length, b.length))
5874      *         return Byte.compareUnsigned(a[i], b[i]);
5875      *     return a.length - b.length;
5876      * }</pre>
5877      *
5878      * @param a the first array to compare
5879      * @param b the second array to compare
5880      * @return the value {@code 0} if the first and second array are
5881      *         equal and contain the same elements in the same order;
5882      *         a value less than {@code 0} if the first array is
5883      *         lexicographically less than the second array; and
5884      *         a value greater than {@code 0} if the first array is
5885      *         lexicographically greater than the second array
5886      * @since 9
5887      */
5888     public static int compareUnsigned(byte[] a, byte[] b) {
5889         if (a == b)
5890             return 0;
5891         if (a == null || b == null)
5892             return a == null ? -1 : 1;
5893 
5894         int i = ArraysSupport.mismatch(a, b,
5895                                        Math.min(a.length, b.length));
5896         if (i >= 0) {
5897             return Byte.compareUnsigned(a[i], b[i]);
5898         }
5899 
5900         return a.length - b.length;
5901     }
5902 
5903 
5904     /**
5905      * Compares two {@code byte} arrays lexicographically over the specified
5906      * ranges, numerically treating elements as unsigned.
5907      *
5908      * <p>If the two arrays, over the specified ranges, share a common prefix
5909      * then the lexicographic comparison is the result of comparing two
5910      * elements, as if by {@link Byte#compareUnsigned(byte, byte)}, at a
5911      * relative index within the respective arrays that is the length of the
5912      * prefix.
5913      * Otherwise, one array is a proper prefix of the other and, lexicographic
5914      * comparison is the result of comparing the two range lengths.
5915      * (See {@link #mismatch(byte[], int, int, byte[], int, int)} for the
5916      * definition of a common and proper prefix.)
5917      *
5918      * @apiNote
5919      * <p>This method behaves as if:
5920      * <pre>{@code
5921      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
5922      *                             b, bFromIndex, bToIndex);
5923      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
5924      *         return Byte.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
5925      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
5926      * }</pre>
5927      *
5928      * @param a the first array to compare
5929      * @param aFromIndex the index (inclusive) of the first element in the
5930      *                   first array to be compared
5931      * @param aToIndex the index (exclusive) of the last element in the
5932      *                 first array to be compared
5933      * @param b the second array to compare
5934      * @param bFromIndex the index (inclusive) of the first element in the
5935      *                   second array to be compared
5936      * @param bToIndex the index (exclusive) of the last element in the
5937      *                 second array to be compared
5938      * @return the value {@code 0} if, over the specified ranges, the first and
5939      *         second array are equal and contain the same elements in the same
5940      *         order;
5941      *         a value less than {@code 0} if, over the specified ranges, the
5942      *         first array is lexicographically less than the second array; and
5943      *         a value greater than {@code 0} if, over the specified ranges, the
5944      *         first array is lexicographically greater than the second array
5945      * @throws IllegalArgumentException
5946      *         if {@code aFromIndex > aToIndex} or
5947      *         if {@code bFromIndex > bToIndex}
5948      * @throws ArrayIndexOutOfBoundsException
5949      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
5950      *         if {@code bFromIndex < 0 or bToIndex > b.length}
5951      * @throws NullPointerException
5952      *         if either array is null
5953      * @since 9
5954      */
5955     public static int compareUnsigned(byte[] a, int aFromIndex, int aToIndex,
5956                                       byte[] b, int bFromIndex, int bToIndex) {
5957         rangeCheck(a.length, aFromIndex, aToIndex);
5958         rangeCheck(b.length, bFromIndex, bToIndex);
5959 
5960         int aLength = aToIndex - aFromIndex;
5961         int bLength = bToIndex - bFromIndex;
5962         int i = ArraysSupport.mismatch(a, aFromIndex,
5963                                        b, bFromIndex,
5964                                        Math.min(aLength, bLength));
5965         if (i >= 0) {
5966             return Byte.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
5967         }
5968 
5969         return aLength - bLength;
5970     }
5971 
5972     // Compare short
5973 
5974     /**
5975      * Compares two {@code short} arrays lexicographically.
5976      *
5977      * <p>If the two arrays share a common prefix then the lexicographic
5978      * comparison is the result of comparing two elements, as if by
5979      * {@link Short#compare(short, short)}, at an index within the respective
5980      * arrays that is the prefix length.
5981      * Otherwise, one array is a proper prefix of the other and, lexicographic
5982      * comparison is the result of comparing the two array lengths.
5983      * (See {@link #mismatch(short[], short[])} for the definition of a common
5984      * and proper prefix.)
5985      *
5986      * <p>A {@code null} array reference is considered lexicographically less
5987      * than a non-{@code null} array reference.  Two {@code null} array
5988      * references are considered equal.
5989      *
5990      * <p>The comparison is consistent with {@link #equals(short[], short[]) equals},
5991      * more specifically the following holds for arrays {@code a} and {@code b}:
5992      * <pre>{@code
5993      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
5994      * }</pre>
5995      *
5996      * @apiNote
5997      * <p>This method behaves as if (for non-{@code null} array references):
5998      * <pre>{@code
5999      *     int i = Arrays.mismatch(a, b);
6000      *     if (i >= 0 && i < Math.min(a.length, b.length))
6001      *         return Short.compare(a[i], b[i]);
6002      *     return a.length - b.length;
6003      * }</pre>
6004      *
6005      * @param a the first array to compare
6006      * @param b the second array to compare
6007      * @return the value {@code 0} if the first and second array are equal and
6008      *         contain the same elements in the same order;
6009      *         a value less than {@code 0} if the first array is
6010      *         lexicographically less than the second array; and
6011      *         a value greater than {@code 0} if the first array is
6012      *         lexicographically greater than the second array
6013      * @since 9
6014      */
6015     public static int compare(short[] a, short[] b) {
6016         if (a == b)
6017             return 0;
6018         if (a == null || b == null)
6019             return a == null ? -1 : 1;
6020 
6021         int i = ArraysSupport.mismatch(a, b,
6022                                        Math.min(a.length, b.length));
6023         if (i >= 0) {
6024             return Short.compare(a[i], b[i]);
6025         }
6026 
6027         return a.length - b.length;
6028     }
6029 
6030     /**
6031      * Compares two {@code short} arrays lexicographically over the specified
6032      * ranges.
6033      *
6034      * <p>If the two arrays, over the specified ranges, share a common prefix
6035      * then the lexicographic comparison is the result of comparing two
6036      * elements, as if by {@link Short#compare(short, short)}, at a relative
6037      * index within the respective arrays that is the length of the prefix.
6038      * Otherwise, one array is a proper prefix of the other and, lexicographic
6039      * comparison is the result of comparing the two range lengths.
6040      * (See {@link #mismatch(short[], int, int, short[], int, int)} for the
6041      * definition of a common and proper prefix.)
6042      *
6043      * <p>The comparison is consistent with
6044      * {@link #equals(short[], int, int, short[], int, int) equals}, more
6045      * specifically the following holds for arrays {@code a} and {@code b} with
6046      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
6047      * [{@code bFromIndex}, {@code bToIndex}) respectively:
6048      * <pre>{@code
6049      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6050      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6051      * }</pre>
6052      *
6053      * @apiNote
6054      * <p>This method behaves as if:
6055      * <pre>{@code
6056      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6057      *                             b, bFromIndex, bToIndex);
6058      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6059      *         return Short.compare(a[aFromIndex + i], b[bFromIndex + i]);
6060      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6061      * }</pre>
6062      *
6063      * @param a the first array to compare
6064      * @param aFromIndex the index (inclusive) of the first element in the
6065      *                   first array to be compared
6066      * @param aToIndex the index (exclusive) of the last element in the
6067      *                 first array to be compared
6068      * @param b the second array to compare
6069      * @param bFromIndex the index (inclusive) of the first element in the
6070      *                   second array to be compared
6071      * @param bToIndex the index (exclusive) of the last element in the
6072      *                 second array to be compared
6073      * @return the value {@code 0} if, over the specified ranges, the first and
6074      *         second array are equal and contain the same elements in the same
6075      *         order;
6076      *         a value less than {@code 0} if, over the specified ranges, the
6077      *         first array is lexicographically less than the second array; and
6078      *         a value greater than {@code 0} if, over the specified ranges, the
6079      *         first array is lexicographically greater than the second array
6080      * @throws IllegalArgumentException
6081      *         if {@code aFromIndex > aToIndex} or
6082      *         if {@code bFromIndex > bToIndex}
6083      * @throws ArrayIndexOutOfBoundsException
6084      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6085      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6086      * @throws NullPointerException
6087      *         if either array is {@code null}
6088      * @since 9
6089      */
6090     public static int compare(short[] a, int aFromIndex, int aToIndex,
6091                               short[] b, int bFromIndex, int bToIndex) {
6092         rangeCheck(a.length, aFromIndex, aToIndex);
6093         rangeCheck(b.length, bFromIndex, bToIndex);
6094 
6095         int aLength = aToIndex - aFromIndex;
6096         int bLength = bToIndex - bFromIndex;
6097         int i = ArraysSupport.mismatch(a, aFromIndex,
6098                                        b, bFromIndex,
6099                                        Math.min(aLength, bLength));
6100         if (i >= 0) {
6101             return Short.compare(a[aFromIndex + i], b[bFromIndex + i]);
6102         }
6103 
6104         return aLength - bLength;
6105     }
6106 
6107     /**
6108      * Compares two {@code short} arrays lexicographically, numerically treating
6109      * elements as unsigned.
6110      *
6111      * <p>If the two arrays share a common prefix then the lexicographic
6112      * comparison is the result of comparing two elements, as if by
6113      * {@link Short#compareUnsigned(short, short)}, at an index within the
6114      * respective arrays that is the prefix length.
6115      * Otherwise, one array is a proper prefix of the other and, lexicographic
6116      * comparison is the result of comparing the two array lengths.
6117      * (See {@link #mismatch(short[], short[])} for the definition of a common
6118      * and proper prefix.)
6119      *
6120      * <p>A {@code null} array reference is considered lexicographically less
6121      * than a non-{@code null} array reference.  Two {@code null} array
6122      * references are considered equal.
6123      *
6124      * @apiNote
6125      * <p>This method behaves as if (for non-{@code null} array references):
6126      * <pre>{@code
6127      *     int i = Arrays.mismatch(a, b);
6128      *     if (i >= 0 && i < Math.min(a.length, b.length))
6129      *         return Short.compareUnsigned(a[i], b[i]);
6130      *     return a.length - b.length;
6131      * }</pre>
6132      *
6133      * @param a the first array to compare
6134      * @param b the second array to compare
6135      * @return the value {@code 0} if the first and second array are
6136      *         equal and contain the same elements in the same order;
6137      *         a value less than {@code 0} if the first array is
6138      *         lexicographically less than the second array; and
6139      *         a value greater than {@code 0} if the first array is
6140      *         lexicographically greater than the second array
6141      * @since 9
6142      */
6143     public static int compareUnsigned(short[] a, short[] b) {
6144         if (a == b)
6145             return 0;
6146         if (a == null || b == null)
6147             return a == null ? -1 : 1;
6148 
6149         int i = ArraysSupport.mismatch(a, b,
6150                                        Math.min(a.length, b.length));
6151         if (i >= 0) {
6152             return Short.compareUnsigned(a[i], b[i]);
6153         }
6154 
6155         return a.length - b.length;
6156     }
6157 
6158     /**
6159      * Compares two {@code short} arrays lexicographically over the specified
6160      * ranges, numerically treating elements as unsigned.
6161      *
6162      * <p>If the two arrays, over the specified ranges, share a common prefix
6163      * then the lexicographic comparison is the result of comparing two
6164      * elements, as if by {@link Short#compareUnsigned(short, short)}, at a
6165      * relative index within the respective arrays that is the length of the
6166      * prefix.
6167      * Otherwise, one array is a proper prefix of the other and, lexicographic
6168      * comparison is the result of comparing the two range lengths.
6169      * (See {@link #mismatch(short[], int, int, short[], int, int)} for the
6170      * definition of a common and proper prefix.)
6171      *
6172      * @apiNote
6173      * <p>This method behaves as if:
6174      * <pre>{@code
6175      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6176      *                             b, bFromIndex, bToIndex);
6177      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6178      *         return Short.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6179      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6180      * }</pre>
6181      *
6182      * @param a the first array to compare
6183      * @param aFromIndex the index (inclusive) of the first element in the
6184      *                   first array to be compared
6185      * @param aToIndex the index (exclusive) of the last element in the
6186      *                 first array to be compared
6187      * @param b the second array to compare
6188      * @param bFromIndex the index (inclusive) of the first element in the
6189      *                   second array to be compared
6190      * @param bToIndex the index (exclusive) of the last element in the
6191      *                 second array to be compared
6192      * @return the value {@code 0} if, over the specified ranges, the first and
6193      *         second array are equal and contain the same elements in the same
6194      *         order;
6195      *         a value less than {@code 0} if, over the specified ranges, the
6196      *         first array is lexicographically less than the second array; and
6197      *         a value greater than {@code 0} if, over the specified ranges, the
6198      *         first array is lexicographically greater than the second array
6199      * @throws IllegalArgumentException
6200      *         if {@code aFromIndex > aToIndex} or
6201      *         if {@code bFromIndex > bToIndex}
6202      * @throws ArrayIndexOutOfBoundsException
6203      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6204      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6205      * @throws NullPointerException
6206      *         if either array is null
6207      * @since 9
6208      */
6209     public static int compareUnsigned(short[] a, int aFromIndex, int aToIndex,
6210                                       short[] b, int bFromIndex, int bToIndex) {
6211         rangeCheck(a.length, aFromIndex, aToIndex);
6212         rangeCheck(b.length, bFromIndex, bToIndex);
6213 
6214         int aLength = aToIndex - aFromIndex;
6215         int bLength = bToIndex - bFromIndex;
6216         int i = ArraysSupport.mismatch(a, aFromIndex,
6217                                        b, bFromIndex,
6218                                        Math.min(aLength, bLength));
6219         if (i >= 0) {
6220             return Short.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6221         }
6222 
6223         return aLength - bLength;
6224     }
6225 
6226     // Compare char
6227 
6228     /**
6229      * Compares two {@code char} arrays lexicographically.
6230      *
6231      * <p>If the two arrays share a common prefix then the lexicographic
6232      * comparison is the result of comparing two elements, as if by
6233      * {@link Character#compare(char, char)}, at an index within the respective
6234      * arrays that is the prefix length.
6235      * Otherwise, one array is a proper prefix of the other and, lexicographic
6236      * comparison is the result of comparing the two array lengths.
6237      * (See {@link #mismatch(char[], char[])} for the definition of a common and
6238      * proper prefix.)
6239      *
6240      * <p>A {@code null} array reference is considered lexicographically less
6241      * than a non-{@code null} array reference.  Two {@code null} array
6242      * references are considered equal.
6243      *
6244      * <p>The comparison is consistent with {@link #equals(char[], char[]) equals},
6245      * more specifically the following holds for arrays {@code a} and {@code b}:
6246      * <pre>{@code
6247      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6248      * }</pre>
6249      *
6250      * @apiNote
6251      * <p>This method behaves as if (for non-{@code null} array references):
6252      * <pre>{@code
6253      *     int i = Arrays.mismatch(a, b);
6254      *     if (i >= 0 && i < Math.min(a.length, b.length))
6255      *         return Character.compare(a[i], b[i]);
6256      *     return a.length - b.length;
6257      * }</pre>
6258      *
6259      * @param a the first array to compare
6260      * @param b the second array to compare
6261      * @return the value {@code 0} if the first and second array are equal and
6262      *         contain the same elements in the same order;
6263      *         a value less than {@code 0} if the first array is
6264      *         lexicographically less than the second array; and
6265      *         a value greater than {@code 0} if the first array is
6266      *         lexicographically greater than the second array
6267      * @since 9
6268      */
6269     public static int compare(char[] a, char[] b) {
6270         if (a == b)
6271             return 0;
6272         if (a == null || b == null)
6273             return a == null ? -1 : 1;
6274 
6275         int i = ArraysSupport.mismatch(a, b,
6276                                        Math.min(a.length, b.length));
6277         if (i >= 0) {
6278             return Character.compare(a[i], b[i]);
6279         }
6280 
6281         return a.length - b.length;
6282     }
6283 
6284     /**
6285      * Compares two {@code char} arrays lexicographically over the specified
6286      * ranges.
6287      *
6288      * <p>If the two arrays, over the specified ranges, share a common prefix
6289      * then the lexicographic comparison is the result of comparing two
6290      * elements, as if by {@link Character#compare(char, char)}, at a relative
6291      * index within the respective arrays that is the length of the prefix.
6292      * Otherwise, one array is a proper prefix of the other and, lexicographic
6293      * comparison is the result of comparing the two range lengths.
6294      * (See {@link #mismatch(char[], int, int, char[], int, int)} for the
6295      * definition of a common and proper prefix.)
6296      *
6297      * <p>The comparison is consistent with
6298      * {@link #equals(char[], int, int, char[], int, int) equals}, more
6299      * specifically the following holds for arrays {@code a} and {@code b} with
6300      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
6301      * [{@code bFromIndex}, {@code bToIndex}) respectively:
6302      * <pre>{@code
6303      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6304      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6305      * }</pre>
6306      *
6307      * @apiNote
6308      * <p>This method behaves as if:
6309      * <pre>{@code
6310      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6311      *                             b, bFromIndex, bToIndex);
6312      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6313      *         return Character.compare(a[aFromIndex + i], b[bFromIndex + i]);
6314      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6315      * }</pre>
6316      *
6317      * @param a the first array to compare
6318      * @param aFromIndex the index (inclusive) of the first element in the
6319      *                   first array to be compared
6320      * @param aToIndex the index (exclusive) of the last element in the
6321      *                 first array to be compared
6322      * @param b the second array to compare
6323      * @param bFromIndex the index (inclusive) of the first element in the
6324      *                   second array to be compared
6325      * @param bToIndex the index (exclusive) of the last element in the
6326      *                 second array to be compared
6327      * @return the value {@code 0} if, over the specified ranges, the first and
6328      *         second array are equal and contain the same elements in the same
6329      *         order;
6330      *         a value less than {@code 0} if, over the specified ranges, the
6331      *         first array is lexicographically less than the second array; and
6332      *         a value greater than {@code 0} if, over the specified ranges, the
6333      *         first array is lexicographically greater than the second array
6334      * @throws IllegalArgumentException
6335      *         if {@code aFromIndex > aToIndex} or
6336      *         if {@code bFromIndex > bToIndex}
6337      * @throws ArrayIndexOutOfBoundsException
6338      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6339      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6340      * @throws NullPointerException
6341      *         if either array is {@code null}
6342      * @since 9
6343      */
6344     public static int compare(char[] a, int aFromIndex, int aToIndex,
6345                               char[] b, int bFromIndex, int bToIndex) {
6346         rangeCheck(a.length, aFromIndex, aToIndex);
6347         rangeCheck(b.length, bFromIndex, bToIndex);
6348 
6349         int aLength = aToIndex - aFromIndex;
6350         int bLength = bToIndex - bFromIndex;
6351         int i = ArraysSupport.mismatch(a, aFromIndex,
6352                                        b, bFromIndex,
6353                                        Math.min(aLength, bLength));
6354         if (i >= 0) {
6355             return Character.compare(a[aFromIndex + i], b[bFromIndex + i]);
6356         }
6357 
6358         return aLength - bLength;
6359     }
6360 
6361     // Compare int
6362 
6363     /**
6364      * Compares two {@code int} arrays lexicographically.
6365      *
6366      * <p>If the two arrays share a common prefix then the lexicographic
6367      * comparison is the result of comparing two elements, as if by
6368      * {@link Integer#compare(int, int)}, at an index within the respective
6369      * arrays that is the prefix length.
6370      * Otherwise, one array is a proper prefix of the other and, lexicographic
6371      * comparison is the result of comparing the two array lengths.
6372      * (See {@link #mismatch(int[], int[])} for the definition of a common and
6373      * proper prefix.)
6374      *
6375      * <p>A {@code null} array reference is considered lexicographically less
6376      * than a non-{@code null} array reference.  Two {@code null} array
6377      * references are considered equal.
6378      *
6379      * <p>The comparison is consistent with {@link #equals(int[], int[]) equals},
6380      * more specifically the following holds for arrays {@code a} and {@code b}:
6381      * <pre>{@code
6382      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6383      * }</pre>
6384      *
6385      * @apiNote
6386      * <p>This method behaves as if (for non-{@code null} array references):
6387      * <pre>{@code
6388      *     int i = Arrays.mismatch(a, b);
6389      *     if (i >= 0 && i < Math.min(a.length, b.length))
6390      *         return Integer.compare(a[i], b[i]);
6391      *     return a.length - b.length;
6392      * }</pre>
6393      *
6394      * @param a the first array to compare
6395      * @param b the second array to compare
6396      * @return the value {@code 0} if the first and second array are equal and
6397      *         contain the same elements in the same order;
6398      *         a value less than {@code 0} if the first array is
6399      *         lexicographically less than the second array; and
6400      *         a value greater than {@code 0} if the first array is
6401      *         lexicographically greater than the second array
6402      * @since 9
6403      */
6404     public static int compare(int[] a, int[] b) {
6405         if (a == b)
6406             return 0;
6407         if (a == null || b == null)
6408             return a == null ? -1 : 1;
6409 
6410         int i = ArraysSupport.mismatch(a, b,
6411                                        Math.min(a.length, b.length));
6412         if (i >= 0) {
6413             return Integer.compare(a[i], b[i]);
6414         }
6415 
6416         return a.length - b.length;
6417     }
6418 
6419     /**
6420      * Compares two {@code int} arrays lexicographically over the specified
6421      * ranges.
6422      *
6423      * <p>If the two arrays, over the specified ranges, share a common prefix
6424      * then the lexicographic comparison is the result of comparing two
6425      * elements, as if by {@link Integer#compare(int, int)}, at a relative index
6426      * within the respective arrays that is the length of the prefix.
6427      * Otherwise, one array is a proper prefix of the other and, lexicographic
6428      * comparison is the result of comparing the two range lengths.
6429      * (See {@link #mismatch(int[], int, int, int[], int, int)} for the
6430      * definition of a common and proper prefix.)
6431      *
6432      * <p>The comparison is consistent with
6433      * {@link #equals(int[], int, int, int[], int, int) equals}, more
6434      * specifically the following holds for arrays {@code a} and {@code b} with
6435      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
6436      * [{@code bFromIndex}, {@code bToIndex}) respectively:
6437      * <pre>{@code
6438      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6439      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6440      * }</pre>
6441      *
6442      * @apiNote
6443      * <p>This method behaves as if:
6444      * <pre>{@code
6445      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6446      *                             b, bFromIndex, bToIndex);
6447      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6448      *         return Integer.compare(a[aFromIndex + i], b[bFromIndex + i]);
6449      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6450      * }</pre>
6451      *
6452      * @param a the first array to compare
6453      * @param aFromIndex the index (inclusive) of the first element in the
6454      *                   first array to be compared
6455      * @param aToIndex the index (exclusive) of the last element in the
6456      *                 first array to be compared
6457      * @param b the second array to compare
6458      * @param bFromIndex the index (inclusive) of the first element in the
6459      *                   second array to be compared
6460      * @param bToIndex the index (exclusive) of the last element in the
6461      *                 second array to be compared
6462      * @return the value {@code 0} if, over the specified ranges, the first and
6463      *         second array are equal and contain the same elements in the same
6464      *         order;
6465      *         a value less than {@code 0} if, over the specified ranges, the
6466      *         first array is lexicographically less than the second array; and
6467      *         a value greater than {@code 0} if, over the specified ranges, the
6468      *         first array is lexicographically greater than the second array
6469      * @throws IllegalArgumentException
6470      *         if {@code aFromIndex > aToIndex} or
6471      *         if {@code bFromIndex > bToIndex}
6472      * @throws ArrayIndexOutOfBoundsException
6473      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6474      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6475      * @throws NullPointerException
6476      *         if either array is {@code null}
6477      * @since 9
6478      */
6479     public static int compare(int[] a, int aFromIndex, int aToIndex,
6480                               int[] b, int bFromIndex, int bToIndex) {
6481         rangeCheck(a.length, aFromIndex, aToIndex);
6482         rangeCheck(b.length, bFromIndex, bToIndex);
6483 
6484         int aLength = aToIndex - aFromIndex;
6485         int bLength = bToIndex - bFromIndex;
6486         int i = ArraysSupport.mismatch(a, aFromIndex,
6487                                        b, bFromIndex,
6488                                        Math.min(aLength, bLength));
6489         if (i >= 0) {
6490             return Integer.compare(a[aFromIndex + i], b[bFromIndex + i]);
6491         }
6492 
6493         return aLength - bLength;
6494     }
6495 
6496     /**
6497      * Compares two {@code int} arrays lexicographically, numerically treating
6498      * elements as unsigned.
6499      *
6500      * <p>If the two arrays share a common prefix then the lexicographic
6501      * comparison is the result of comparing two elements, as if by
6502      * {@link Integer#compareUnsigned(int, int)}, at an index within the
6503      * respective arrays that is the prefix length.
6504      * Otherwise, one array is a proper prefix of the other and, lexicographic
6505      * comparison is the result of comparing the two array lengths.
6506      * (See {@link #mismatch(int[], int[])} for the definition of a common
6507      * and proper prefix.)
6508      *
6509      * <p>A {@code null} array reference is considered lexicographically less
6510      * than a non-{@code null} array reference.  Two {@code null} array
6511      * references are considered equal.
6512      *
6513      * @apiNote
6514      * <p>This method behaves as if (for non-{@code null} array references):
6515      * <pre>{@code
6516      *     int i = Arrays.mismatch(a, b);
6517      *     if (i >= 0 && i < Math.min(a.length, b.length))
6518      *         return Integer.compareUnsigned(a[i], b[i]);
6519      *     return a.length - b.length;
6520      * }</pre>
6521      *
6522      * @param a the first array to compare
6523      * @param b the second array to compare
6524      * @return the value {@code 0} if the first and second array are
6525      *         equal and contain the same elements in the same order;
6526      *         a value less than {@code 0} if the first array is
6527      *         lexicographically less than the second array; and
6528      *         a value greater than {@code 0} if the first array is
6529      *         lexicographically greater than the second array
6530      * @since 9
6531      */
6532     public static int compareUnsigned(int[] a, int[] b) {
6533         if (a == b)
6534             return 0;
6535         if (a == null || b == null)
6536             return a == null ? -1 : 1;
6537 
6538         int i = ArraysSupport.mismatch(a, b,
6539                                        Math.min(a.length, b.length));
6540         if (i >= 0) {
6541             return Integer.compareUnsigned(a[i], b[i]);
6542         }
6543 
6544         return a.length - b.length;
6545     }
6546 
6547     /**
6548      * Compares two {@code int} arrays lexicographically over the specified
6549      * ranges, numerically treating elements as unsigned.
6550      *
6551      * <p>If the two arrays, over the specified ranges, share a common prefix
6552      * then the lexicographic comparison is the result of comparing two
6553      * elements, as if by {@link Integer#compareUnsigned(int, int)}, at a
6554      * relative index within the respective arrays that is the length of the
6555      * prefix.
6556      * Otherwise, one array is a proper prefix of the other and, lexicographic
6557      * comparison is the result of comparing the two range lengths.
6558      * (See {@link #mismatch(int[], int, int, int[], int, int)} for the
6559      * definition of a common and proper prefix.)
6560      *
6561      * @apiNote
6562      * <p>This method behaves as if:
6563      * <pre>{@code
6564      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6565      *                             b, bFromIndex, bToIndex);
6566      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6567      *         return Integer.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6568      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6569      * }</pre>
6570      *
6571      * @param a the first array to compare
6572      * @param aFromIndex the index (inclusive) of the first element in the
6573      *                   first array to be compared
6574      * @param aToIndex the index (exclusive) of the last element in the
6575      *                 first array to be compared
6576      * @param b the second array to compare
6577      * @param bFromIndex the index (inclusive) of the first element in the
6578      *                   second array to be compared
6579      * @param bToIndex the index (exclusive) of the last element in the
6580      *                 second array to be compared
6581      * @return the value {@code 0} if, over the specified ranges, the first and
6582      *         second array are equal and contain the same elements in the same
6583      *         order;
6584      *         a value less than {@code 0} if, over the specified ranges, the
6585      *         first array is lexicographically less than the second array; and
6586      *         a value greater than {@code 0} if, over the specified ranges, the
6587      *         first array is lexicographically greater than the second array
6588      * @throws IllegalArgumentException
6589      *         if {@code aFromIndex > aToIndex} or
6590      *         if {@code bFromIndex > bToIndex}
6591      * @throws ArrayIndexOutOfBoundsException
6592      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6593      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6594      * @throws NullPointerException
6595      *         if either array is null
6596      * @since 9
6597      */
6598     public static int compareUnsigned(int[] a, int aFromIndex, int aToIndex,
6599                                       int[] b, int bFromIndex, int bToIndex) {
6600         rangeCheck(a.length, aFromIndex, aToIndex);
6601         rangeCheck(b.length, bFromIndex, bToIndex);
6602 
6603         int aLength = aToIndex - aFromIndex;
6604         int bLength = bToIndex - bFromIndex;
6605         int i = ArraysSupport.mismatch(a, aFromIndex,
6606                                        b, bFromIndex,
6607                                        Math.min(aLength, bLength));
6608         if (i >= 0) {
6609             return Integer.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6610         }
6611 
6612         return aLength - bLength;
6613     }
6614 
6615     // Compare long
6616 
6617     /**
6618      * Compares two {@code long} arrays lexicographically.
6619      *
6620      * <p>If the two arrays share a common prefix then the lexicographic
6621      * comparison is the result of comparing two elements, as if by
6622      * {@link Long#compare(long, long)}, at an index within the respective
6623      * arrays that is the prefix length.
6624      * Otherwise, one array is a proper prefix of the other and, lexicographic
6625      * comparison is the result of comparing the two array lengths.
6626      * (See {@link #mismatch(long[], long[])} for the definition of a common and
6627      * proper prefix.)
6628      *
6629      * <p>A {@code null} array reference is considered lexicographically less
6630      * than a non-{@code null} array reference.  Two {@code null} array
6631      * references are considered equal.
6632      *
6633      * <p>The comparison is consistent with {@link #equals(long[], long[]) equals},
6634      * more specifically the following holds for arrays {@code a} and {@code b}:
6635      * <pre>{@code
6636      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6637      * }</pre>
6638      *
6639      * @apiNote
6640      * <p>This method behaves as if (for non-{@code null} array references):
6641      * <pre>{@code
6642      *     int i = Arrays.mismatch(a, b);
6643      *     if (i >= 0 && i < Math.min(a.length, b.length))
6644      *         return Long.compare(a[i], b[i]);
6645      *     return a.length - b.length;
6646      * }</pre>
6647      *
6648      * @param a the first array to compare
6649      * @param b the second array to compare
6650      * @return the value {@code 0} if the first and second array are equal and
6651      *         contain the same elements in the same order;
6652      *         a value less than {@code 0} if the first array is
6653      *         lexicographically less than the second array; and
6654      *         a value greater than {@code 0} if the first array is
6655      *         lexicographically greater than the second array
6656      * @since 9
6657      */
6658     public static int compare(long[] a, long[] b) {
6659         if (a == b)
6660             return 0;
6661         if (a == null || b == null)
6662             return a == null ? -1 : 1;
6663 
6664         int i = ArraysSupport.mismatch(a, b,
6665                                        Math.min(a.length, b.length));
6666         if (i >= 0) {
6667             return Long.compare(a[i], b[i]);
6668         }
6669 
6670         return a.length - b.length;
6671     }
6672 
6673     /**
6674      * Compares two {@code long} arrays lexicographically over the specified
6675      * ranges.
6676      *
6677      * <p>If the two arrays, over the specified ranges, share a common prefix
6678      * then the lexicographic comparison is the result of comparing two
6679      * elements, as if by {@link Long#compare(long, long)}, at a relative index
6680      * within the respective arrays that is the length of the prefix.
6681      * Otherwise, one array is a proper prefix of the other and, lexicographic
6682      * comparison is the result of comparing the two range lengths.
6683      * (See {@link #mismatch(long[], int, int, long[], int, int)} for the
6684      * definition of a common and proper prefix.)
6685      *
6686      * <p>The comparison is consistent with
6687      * {@link #equals(long[], int, int, long[], int, int) equals}, more
6688      * specifically the following holds for arrays {@code a} and {@code b} with
6689      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
6690      * [{@code bFromIndex}, {@code bToIndex}) respectively:
6691      * <pre>{@code
6692      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6693      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6694      * }</pre>
6695      *
6696      * @apiNote
6697      * <p>This method behaves as if:
6698      * <pre>{@code
6699      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6700      *                             b, bFromIndex, bToIndex);
6701      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6702      *         return Long.compare(a[aFromIndex + i], b[bFromIndex + i]);
6703      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6704      * }</pre>
6705      *
6706      * @param a the first array to compare
6707      * @param aFromIndex the index (inclusive) of the first element in the
6708      *                   first array to be compared
6709      * @param aToIndex the index (exclusive) of the last element in the
6710      *                 first array to be compared
6711      * @param b the second array to compare
6712      * @param bFromIndex the index (inclusive) of the first element in the
6713      *                   second array to be compared
6714      * @param bToIndex the index (exclusive) of the last element in the
6715      *                 second array to be compared
6716      * @return the value {@code 0} if, over the specified ranges, the first and
6717      *         second array are equal and contain the same elements in the same
6718      *         order;
6719      *         a value less than {@code 0} if, over the specified ranges, the
6720      *         first array is lexicographically less than the second array; and
6721      *         a value greater than {@code 0} if, over the specified ranges, the
6722      *         first array is lexicographically greater than the second array
6723      * @throws IllegalArgumentException
6724      *         if {@code aFromIndex > aToIndex} or
6725      *         if {@code bFromIndex > bToIndex}
6726      * @throws ArrayIndexOutOfBoundsException
6727      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6728      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6729      * @throws NullPointerException
6730      *         if either array is {@code null}
6731      * @since 9
6732      */
6733     public static int compare(long[] a, int aFromIndex, int aToIndex,
6734                               long[] b, int bFromIndex, int bToIndex) {
6735         rangeCheck(a.length, aFromIndex, aToIndex);
6736         rangeCheck(b.length, bFromIndex, bToIndex);
6737 
6738         int aLength = aToIndex - aFromIndex;
6739         int bLength = bToIndex - bFromIndex;
6740         int i = ArraysSupport.mismatch(a, aFromIndex,
6741                                        b, bFromIndex,
6742                                        Math.min(aLength, bLength));
6743         if (i >= 0) {
6744             return Long.compare(a[aFromIndex + i], b[bFromIndex + i]);
6745         }
6746 
6747         return aLength - bLength;
6748     }
6749 
6750     /**
6751      * Compares two {@code long} arrays lexicographically, numerically treating
6752      * elements as unsigned.
6753      *
6754      * <p>If the two arrays share a common prefix then the lexicographic
6755      * comparison is the result of comparing two elements, as if by
6756      * {@link Long#compareUnsigned(long, long)}, at an index within the
6757      * respective arrays that is the prefix length.
6758      * Otherwise, one array is a proper prefix of the other and, lexicographic
6759      * comparison is the result of comparing the two array lengths.
6760      * (See {@link #mismatch(long[], long[])} for the definition of a common
6761      * and proper prefix.)
6762      *
6763      * <p>A {@code null} array reference is considered lexicographically less
6764      * than a non-{@code null} array reference.  Two {@code null} array
6765      * references are considered equal.
6766      *
6767      * @apiNote
6768      * <p>This method behaves as if (for non-{@code null} array references):
6769      * <pre>{@code
6770      *     int i = Arrays.mismatch(a, b);
6771      *     if (i >= 0 && i < Math.min(a.length, b.length))
6772      *         return Long.compareUnsigned(a[i], b[i]);
6773      *     return a.length - b.length;
6774      * }</pre>
6775      *
6776      * @param a the first array to compare
6777      * @param b the second array to compare
6778      * @return the value {@code 0} if the first and second array are
6779      *         equal and contain the same elements in the same order;
6780      *         a value less than {@code 0} if the first array is
6781      *         lexicographically less than the second array; and
6782      *         a value greater than {@code 0} if the first array is
6783      *         lexicographically greater than the second array
6784      * @since 9
6785      */
6786     public static int compareUnsigned(long[] a, long[] b) {
6787         if (a == b)
6788             return 0;
6789         if (a == null || b == null)
6790             return a == null ? -1 : 1;
6791 
6792         int i = ArraysSupport.mismatch(a, b,
6793                                        Math.min(a.length, b.length));
6794         if (i >= 0) {
6795             return Long.compareUnsigned(a[i], b[i]);
6796         }
6797 
6798         return a.length - b.length;
6799     }
6800 
6801     /**
6802      * Compares two {@code long} arrays lexicographically over the specified
6803      * ranges, numerically treating elements as unsigned.
6804      *
6805      * <p>If the two arrays, over the specified ranges, share a common prefix
6806      * then the lexicographic comparison is the result of comparing two
6807      * elements, as if by {@link Long#compareUnsigned(long, long)}, at a
6808      * relative index within the respective arrays that is the length of the
6809      * prefix.
6810      * Otherwise, one array is a proper prefix of the other and, lexicographic
6811      * comparison is the result of comparing the two range lengths.
6812      * (See {@link #mismatch(long[], int, int, long[], int, int)} for the
6813      * definition of a common and proper prefix.)
6814      *
6815      * @apiNote
6816      * <p>This method behaves as if:
6817      * <pre>{@code
6818      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6819      *                             b, bFromIndex, bToIndex);
6820      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6821      *         return Long.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6822      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6823      * }</pre>
6824      *
6825      * @param a the first array to compare
6826      * @param aFromIndex the index (inclusive) of the first element in the
6827      *                   first array to be compared
6828      * @param aToIndex the index (exclusive) of the last element in the
6829      *                 first array to be compared
6830      * @param b the second array to compare
6831      * @param bFromIndex the index (inclusive) of the first element in the
6832      *                   second array to be compared
6833      * @param bToIndex the index (exclusive) of the last element in the
6834      *                 second array to be compared
6835      * @return the value {@code 0} if, over the specified ranges, the first and
6836      *         second array are equal and contain the same elements in the same
6837      *         order;
6838      *         a value less than {@code 0} if, over the specified ranges, the
6839      *         first array is lexicographically less than the second array; and
6840      *         a value greater than {@code 0} if, over the specified ranges, the
6841      *         first array is lexicographically greater than the second array
6842      * @throws IllegalArgumentException
6843      *         if {@code aFromIndex > aToIndex} or
6844      *         if {@code bFromIndex > bToIndex}
6845      * @throws ArrayIndexOutOfBoundsException
6846      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6847      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6848      * @throws NullPointerException
6849      *         if either array is null
6850      * @since 9
6851      */
6852     public static int compareUnsigned(long[] a, int aFromIndex, int aToIndex,
6853                                       long[] b, int bFromIndex, int bToIndex) {
6854         rangeCheck(a.length, aFromIndex, aToIndex);
6855         rangeCheck(b.length, bFromIndex, bToIndex);
6856 
6857         int aLength = aToIndex - aFromIndex;
6858         int bLength = bToIndex - bFromIndex;
6859         int i = ArraysSupport.mismatch(a, aFromIndex,
6860                                        b, bFromIndex,
6861                                        Math.min(aLength, bLength));
6862         if (i >= 0) {
6863             return Long.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]);
6864         }
6865 
6866         return aLength - bLength;
6867     }
6868 
6869     // Compare float
6870 
6871     /**
6872      * Compares two {@code float} arrays lexicographically.
6873      *
6874      * <p>If the two arrays share a common prefix then the lexicographic
6875      * comparison is the result of comparing two elements, as if by
6876      * {@link Float#compare(float, float)}, at an index within the respective
6877      * arrays that is the prefix length.
6878      * Otherwise, one array is a proper prefix of the other and, lexicographic
6879      * comparison is the result of comparing the two array lengths.
6880      * (See {@link #mismatch(float[], float[])} for the definition of a common
6881      * and proper prefix.)
6882      *
6883      * <p>A {@code null} array reference is considered lexicographically less
6884      * than a non-{@code null} array reference.  Two {@code null} array
6885      * references are considered equal.
6886      *
6887      * <p>The comparison is consistent with {@link #equals(float[], float[]) equals},
6888      * more specifically the following holds for arrays {@code a} and {@code b}:
6889      * <pre>{@code
6890      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
6891      * }</pre>
6892      *
6893      * @apiNote
6894      * <p>This method behaves as if (for non-{@code null} array references):
6895      * <pre>{@code
6896      *     int i = Arrays.mismatch(a, b);
6897      *     if (i >= 0 && i < Math.min(a.length, b.length))
6898      *         return Float.compare(a[i], b[i]);
6899      *     return a.length - b.length;
6900      * }</pre>
6901      *
6902      * @param a the first array to compare
6903      * @param b the second array to compare
6904      * @return the value {@code 0} if the first and second array are equal and
6905      *         contain the same elements in the same order;
6906      *         a value less than {@code 0} if the first array is
6907      *         lexicographically less than the second array; and
6908      *         a value greater than {@code 0} if the first array is
6909      *         lexicographically greater than the second array
6910      * @since 9
6911      */
6912     public static int compare(float[] a, float[] b) {
6913         if (a == b)
6914             return 0;
6915         if (a == null || b == null)
6916             return a == null ? -1 : 1;
6917 
6918         int i = ArraysSupport.mismatch(a, b,
6919                                        Math.min(a.length, b.length));
6920         if (i >= 0) {
6921             return Float.compare(a[i], b[i]);
6922         }
6923 
6924         return a.length - b.length;
6925     }
6926 
6927     /**
6928      * Compares two {@code float} arrays lexicographically over the specified
6929      * ranges.
6930      *
6931      * <p>If the two arrays, over the specified ranges, share a common prefix
6932      * then the lexicographic comparison is the result of comparing two
6933      * elements, as if by {@link Float#compare(float, float)}, at a relative
6934      * index within the respective arrays that is the length of the prefix.
6935      * Otherwise, one array is a proper prefix of the other and, lexicographic
6936      * comparison is the result of comparing the two range lengths.
6937      * (See {@link #mismatch(float[], int, int, float[], int, int)} for the
6938      * definition of a common and proper prefix.)
6939      *
6940      * <p>The comparison is consistent with
6941      * {@link #equals(float[], int, int, float[], int, int) equals}, more
6942      * specifically the following holds for arrays {@code a} and {@code b} with
6943      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
6944      * [{@code bFromIndex}, {@code bToIndex}) respectively:
6945      * <pre>{@code
6946      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
6947      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
6948      * }</pre>
6949      *
6950      * @apiNote
6951      * <p>This method behaves as if:
6952      * <pre>{@code
6953      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
6954      *                             b, bFromIndex, bToIndex);
6955      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
6956      *         return Float.compare(a[aFromIndex + i], b[bFromIndex + i]);
6957      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
6958      * }</pre>
6959      *
6960      * @param a the first array to compare
6961      * @param aFromIndex the index (inclusive) of the first element in the
6962      *                   first array to be compared
6963      * @param aToIndex the index (exclusive) of the last element in the
6964      *                 first array to be compared
6965      * @param b the second array to compare
6966      * @param bFromIndex the index (inclusive) of the first element in the
6967      *                   second array to be compared
6968      * @param bToIndex the index (exclusive) of the last element in the
6969      *                 second array to be compared
6970      * @return the value {@code 0} if, over the specified ranges, the first and
6971      *         second array are equal and contain the same elements in the same
6972      *         order;
6973      *         a value less than {@code 0} if, over the specified ranges, the
6974      *         first array is lexicographically less than the second array; and
6975      *         a value greater than {@code 0} if, over the specified ranges, the
6976      *         first array is lexicographically greater than the second array
6977      * @throws IllegalArgumentException
6978      *         if {@code aFromIndex > aToIndex} or
6979      *         if {@code bFromIndex > bToIndex}
6980      * @throws ArrayIndexOutOfBoundsException
6981      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
6982      *         if {@code bFromIndex < 0 or bToIndex > b.length}
6983      * @throws NullPointerException
6984      *         if either array is {@code null}
6985      * @since 9
6986      */
6987     public static int compare(float[] a, int aFromIndex, int aToIndex,
6988                               float[] b, int bFromIndex, int bToIndex) {
6989         rangeCheck(a.length, aFromIndex, aToIndex);
6990         rangeCheck(b.length, bFromIndex, bToIndex);
6991 
6992         int aLength = aToIndex - aFromIndex;
6993         int bLength = bToIndex - bFromIndex;
6994         int i = ArraysSupport.mismatch(a, aFromIndex,
6995                                        b, bFromIndex,
6996                                        Math.min(aLength, bLength));
6997         if (i >= 0) {
6998             return Float.compare(a[aFromIndex + i], b[bFromIndex + i]);
6999         }
7000 
7001         return aLength - bLength;
7002     }
7003 
7004     // Compare double
7005 
7006     /**
7007      * Compares two {@code double} arrays lexicographically.
7008      *
7009      * <p>If the two arrays share a common prefix then the lexicographic
7010      * comparison is the result of comparing two elements, as if by
7011      * {@link Double#compare(double, double)}, at an index within the respective
7012      * arrays that is the prefix length.
7013      * Otherwise, one array is a proper prefix of the other and, lexicographic
7014      * comparison is the result of comparing the two array lengths.
7015      * (See {@link #mismatch(double[], double[])} for the definition of a common
7016      * and proper prefix.)
7017      *
7018      * <p>A {@code null} array reference is considered lexicographically less
7019      * than a non-{@code null} array reference.  Two {@code null} array
7020      * references are considered equal.
7021      *
7022      * <p>The comparison is consistent with {@link #equals(double[], double[]) equals},
7023      * more specifically the following holds for arrays {@code a} and {@code b}:
7024      * <pre>{@code
7025      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
7026      * }</pre>
7027      *
7028      * @apiNote
7029      * <p>This method behaves as if (for non-{@code null} array references):
7030      * <pre>{@code
7031      *     int i = Arrays.mismatch(a, b);
7032      *     if (i >= 0 && i < Math.min(a.length, b.length))
7033      *         return Double.compare(a[i], b[i]);
7034      *     return a.length - b.length;
7035      * }</pre>
7036      *
7037      * @param a the first array to compare
7038      * @param b the second array to compare
7039      * @return the value {@code 0} if the first and second array are equal and
7040      *         contain the same elements in the same order;
7041      *         a value less than {@code 0} if the first array is
7042      *         lexicographically less than the second array; and
7043      *         a value greater than {@code 0} if the first array is
7044      *         lexicographically greater than the second array
7045      * @since 9
7046      */
7047     public static int compare(double[] a, double[] b) {
7048         if (a == b)
7049             return 0;
7050         if (a == null || b == null)
7051             return a == null ? -1 : 1;
7052 
7053         int i = ArraysSupport.mismatch(a, b,
7054                                        Math.min(a.length, b.length));
7055         if (i >= 0) {
7056             return Double.compare(a[i], b[i]);
7057         }
7058 
7059         return a.length - b.length;
7060     }
7061 
7062     /**
7063      * Compares two {@code double} arrays lexicographically over the specified
7064      * ranges.
7065      *
7066      * <p>If the two arrays, over the specified ranges, share a common prefix
7067      * then the lexicographic comparison is the result of comparing two
7068      * elements, as if by {@link Double#compare(double, double)}, at a relative
7069      * index within the respective arrays that is the length of the prefix.
7070      * Otherwise, one array is a proper prefix of the other and, lexicographic
7071      * comparison is the result of comparing the two range lengths.
7072      * (See {@link #mismatch(double[], int, int, double[], int, int)} for the
7073      * definition of a common and proper prefix.)
7074      *
7075      * <p>The comparison is consistent with
7076      * {@link #equals(double[], int, int, double[], int, int) equals}, more
7077      * specifically the following holds for arrays {@code a} and {@code b} with
7078      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
7079      * [{@code bFromIndex}, {@code bToIndex}) respectively:
7080      * <pre>{@code
7081      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
7082      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
7083      * }</pre>
7084      *
7085      * @apiNote
7086      * <p>This method behaves as if:
7087      * <pre>{@code
7088      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
7089      *                             b, bFromIndex, bToIndex);
7090      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7091      *         return Double.compare(a[aFromIndex + i], b[bFromIndex + i]);
7092      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
7093      * }</pre>
7094      *
7095      * @param a the first array to compare
7096      * @param aFromIndex the index (inclusive) of the first element in the
7097      *                   first array to be compared
7098      * @param aToIndex the index (exclusive) of the last element in the
7099      *                 first array to be compared
7100      * @param b the second array to compare
7101      * @param bFromIndex the index (inclusive) of the first element in the
7102      *                   second array to be compared
7103      * @param bToIndex the index (exclusive) of the last element in the
7104      *                 second array to be compared
7105      * @return the value {@code 0} if, over the specified ranges, the first and
7106      *         second array are equal and contain the same elements in the same
7107      *         order;
7108      *         a value less than {@code 0} if, over the specified ranges, the
7109      *         first array is lexicographically less than the second array; and
7110      *         a value greater than {@code 0} if, over the specified ranges, the
7111      *         first array is lexicographically greater than the second array
7112      * @throws IllegalArgumentException
7113      *         if {@code aFromIndex > aToIndex} or
7114      *         if {@code bFromIndex > bToIndex}
7115      * @throws ArrayIndexOutOfBoundsException
7116      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7117      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7118      * @throws NullPointerException
7119      *         if either array is {@code null}
7120      * @since 9
7121      */
7122     public static int compare(double[] a, int aFromIndex, int aToIndex,
7123                               double[] b, int bFromIndex, int bToIndex) {
7124         rangeCheck(a.length, aFromIndex, aToIndex);
7125         rangeCheck(b.length, bFromIndex, bToIndex);
7126 
7127         int aLength = aToIndex - aFromIndex;
7128         int bLength = bToIndex - bFromIndex;
7129         int i = ArraysSupport.mismatch(a, aFromIndex,
7130                                        b, bFromIndex,
7131                                        Math.min(aLength, bLength));
7132         if (i >= 0) {
7133             return Double.compare(a[aFromIndex + i], b[bFromIndex + i]);
7134         }
7135 
7136         return aLength - bLength;
7137     }
7138 
7139     // Compare objects
7140 
7141     /**
7142      * Compares two {@code Object} arrays, within comparable elements,
7143      * lexicographically.
7144      *
7145      * <p>If the two arrays share a common prefix then the lexicographic
7146      * comparison is the result of comparing two elements of type {@code T} at
7147      * an index {@code i} within the respective arrays that is the prefix
7148      * length, as if by:
7149      * <pre>{@code
7150      *     Comparator.nullsFirst(Comparator.<T>naturalOrder()).
7151      *         compare(a[i], b[i])
7152      * }</pre>
7153      * Otherwise, one array is a proper prefix of the other and, lexicographic
7154      * comparison is the result of comparing the two array lengths.
7155      * (See {@link #mismatch(Object[], Object[])} for the definition of a common
7156      * and proper prefix.)
7157      *
7158      * <p>A {@code null} array reference is considered lexicographically less
7159      * than a non-{@code null} array reference. Two {@code null} array
7160      * references are considered equal.
7161      * A {@code null} array element is considered lexicographically less than a
7162      * non-{@code null} array element. Two {@code null} array elements are
7163      * considered equal.
7164      *
7165      * <p>The comparison is consistent with {@link #equals(Object[], Object[]) equals},
7166      * more specifically the following holds for arrays {@code a} and {@code b}:
7167      * <pre>{@code
7168      *     Arrays.equals(a, b) == (Arrays.compare(a, b) == 0)
7169      * }</pre>
7170      *
7171      * @apiNote
7172      * <p>This method behaves as if (for non-{@code null} array references
7173      * and elements):
7174      * <pre>{@code
7175      *     int i = Arrays.mismatch(a, b);
7176      *     if (i >= 0 && i < Math.min(a.length, b.length))
7177      *         return a[i].compareTo(b[i]);
7178      *     return a.length - b.length;
7179      * }</pre>
7180      *
7181      * @param a the first array to compare
7182      * @param b the second array to compare
7183      * @param <T> the type of comparable array elements
7184      * @return the value {@code 0} if the first and second array are equal and
7185      *         contain the same elements in the same order;
7186      *         a value less than {@code 0} if the first array is
7187      *         lexicographically less than the second array; and
7188      *         a value greater than {@code 0} if the first array is
7189      *         lexicographically greater than the second array
7190      * @since 9
7191      */
7192     public static <T extends Comparable<? super T>> int compare(T[] a, T[] b) {
7193         if (a == b)
7194             return 0;
7195         // A null array is less than a non-null array
7196         if (a == null || b == null)
7197             return a == null ? -1 : 1;
7198 
7199         int length = Math.min(a.length, b.length);
7200         for (int i = 0; i < length; i++) {
7201             T oa = a[i];
7202             T ob = b[i];
7203             if (oa != ob) {
7204                 // A null element is less than a non-null element
7205                 if (oa == null || ob == null)
7206                     return oa == null ? -1 : 1;
7207                 int v = oa.compareTo(ob);
7208                 if (v != 0) {
7209                     return v;
7210                 }
7211             }
7212         }
7213 
7214         return a.length - b.length;
7215     }
7216 
7217     /**
7218      * Compares two {@code Object} arrays lexicographically over the specified
7219      * ranges.
7220      *
7221      * <p>If the two arrays, over the specified ranges, share a common prefix
7222      * then the lexicographic comparison is the result of comparing two
7223      * elements of type {@code T} at a relative index {@code i} within the
7224      * respective arrays that is the prefix length, as if by:
7225      * <pre>{@code
7226      *     Comparator.nullsFirst(Comparator.<T>naturalOrder()).
7227      *         compare(a[aFromIndex + i, b[bFromIndex + i])
7228      * }</pre>
7229      * Otherwise, one array is a proper prefix of the other and, lexicographic
7230      * comparison is the result of comparing the two range lengths.
7231      * (See {@link #mismatch(Object[], int, int, Object[], int, int)} for the
7232      * definition of a common and proper prefix.)
7233      *
7234      * <p>The comparison is consistent with
7235      * {@link #equals(Object[], int, int, Object[], int, int) equals}, more
7236      * specifically the following holds for arrays {@code a} and {@code b} with
7237      * specified ranges [{@code aFromIndex}, {@code aToIndex}) and
7238      * [{@code bFromIndex}, {@code bToIndex}) respectively:
7239      * <pre>{@code
7240      *     Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) ==
7241      *         (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0)
7242      * }</pre>
7243      *
7244      * @apiNote
7245      * <p>This method behaves as if (for non-{@code null} array elements):
7246      * <pre>{@code
7247      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
7248      *                             b, bFromIndex, bToIndex);
7249      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7250      *         return a[aFromIndex + i].compareTo(b[bFromIndex + i]);
7251      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
7252      * }</pre>
7253      *
7254      * @param a the first array to compare
7255      * @param aFromIndex the index (inclusive) of the first element in the
7256      *                   first array to be compared
7257      * @param aToIndex the index (exclusive) of the last element in the
7258      *                 first array to be compared
7259      * @param b the second array to compare
7260      * @param bFromIndex the index (inclusive) of the first element in the
7261      *                   second array to be compared
7262      * @param bToIndex the index (exclusive) of the last element in the
7263      *                 second array to be compared
7264      * @param <T> the type of comparable array elements
7265      * @return the value {@code 0} if, over the specified ranges, the first and
7266      *         second array are equal and contain the same elements in the same
7267      *         order;
7268      *         a value less than {@code 0} if, over the specified ranges, the
7269      *         first array is lexicographically less than the second array; and
7270      *         a value greater than {@code 0} if, over the specified ranges, the
7271      *         first array is lexicographically greater than the second array
7272      * @throws IllegalArgumentException
7273      *         if {@code aFromIndex > aToIndex} or
7274      *         if {@code bFromIndex > bToIndex}
7275      * @throws ArrayIndexOutOfBoundsException
7276      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7277      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7278      * @throws NullPointerException
7279      *         if either array is {@code null}
7280      * @since 9
7281      */
7282     public static <T extends Comparable<? super T>> int compare(
7283             T[] a, int aFromIndex, int aToIndex,
7284             T[] b, int bFromIndex, int bToIndex) {
7285         rangeCheck(a.length, aFromIndex, aToIndex);
7286         rangeCheck(b.length, bFromIndex, bToIndex);
7287 
7288         int aLength = aToIndex - aFromIndex;
7289         int bLength = bToIndex - bFromIndex;
7290         int length = Math.min(aLength, bLength);
7291         for (int i = 0; i < length; i++) {
7292             T oa = a[aFromIndex++];
7293             T ob = b[bFromIndex++];
7294             if (oa != ob) {
7295                 if (oa == null || ob == null)
7296                     return oa == null ? -1 : 1;
7297                 int v = oa.compareTo(ob);
7298                 if (v != 0) {
7299                     return v;
7300                 }
7301             }
7302         }
7303 
7304         return aLength - bLength;
7305     }
7306 
7307     /**
7308      * Compares two {@code Object} arrays lexicographically using a specified
7309      * comparator.
7310      *
7311      * <p>If the two arrays share a common prefix then the lexicographic
7312      * comparison is the result of comparing with the specified comparator two
7313      * elements at an index within the respective arrays that is the prefix
7314      * length.
7315      * Otherwise, one array is a proper prefix of the other and, lexicographic
7316      * comparison is the result of comparing the two array lengths.
7317      * (See {@link #mismatch(Object[], Object[])} for the definition of a common
7318      * and proper prefix.)
7319      *
7320      * <p>A {@code null} array reference is considered lexicographically less
7321      * than a non-{@code null} array reference.  Two {@code null} array
7322      * references are considered equal.
7323      *
7324      * @apiNote
7325      * <p>This method behaves as if (for non-{@code null} array references):
7326      * <pre>{@code
7327      *     int i = Arrays.mismatch(a, b, cmp);
7328      *     if (i >= 0 && i < Math.min(a.length, b.length))
7329      *         return cmp.compare(a[i], b[i]);
7330      *     return a.length - b.length;
7331      * }</pre>
7332      *
7333      * @param a the first array to compare
7334      * @param b the second array to compare
7335      * @param cmp the comparator to compare array elements
7336      * @param <T> the type of array elements
7337      * @return the value {@code 0} if the first and second array are equal and
7338      *         contain the same elements in the same order;
7339      *         a value less than {@code 0} if the first array is
7340      *         lexicographically less than the second array; and
7341      *         a value greater than {@code 0} if the first array is
7342      *         lexicographically greater than the second array
7343      * @throws NullPointerException if the comparator is {@code null}
7344      * @since 9
7345      */
7346     public static <T> int compare(T[] a, T[] b,
7347                                   Comparator<? super T> cmp) {
7348         Objects.requireNonNull(cmp);
7349         if (a == b)
7350             return 0;
7351         if (a == null || b == null)
7352             return a == null ? -1 : 1;
7353 
7354         int length = Math.min(a.length, b.length);
7355         for (int i = 0; i < length; i++) {
7356             T oa = a[i];
7357             T ob = b[i];
7358             if (oa != ob) {
7359                 // Null-value comparison is deferred to the comparator
7360                 int v = cmp.compare(oa, ob);
7361                 if (v != 0) {
7362                     return v;
7363                 }
7364             }
7365         }
7366 
7367         return a.length - b.length;
7368     }
7369 
7370     /**
7371      * Compares two {@code Object} arrays lexicographically over the specified
7372      * ranges.
7373      *
7374      * <p>If the two arrays, over the specified ranges, share a common prefix
7375      * then the lexicographic comparison is the result of comparing with the
7376      * specified comparator two elements at a relative index within the
7377      * respective arrays that is the prefix length.
7378      * Otherwise, one array is a proper prefix of the other and, lexicographic
7379      * comparison is the result of comparing the two range lengths.
7380      * (See {@link #mismatch(Object[], int, int, Object[], int, int)} for the
7381      * definition of a common and proper prefix.)
7382      *
7383      * @apiNote
7384      * <p>This method behaves as if (for non-{@code null} array elements):
7385      * <pre>{@code
7386      *     int i = Arrays.mismatch(a, aFromIndex, aToIndex,
7387      *                             b, bFromIndex, bToIndex, cmp);
7388      *     if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7389      *         return cmp.compare(a[aFromIndex + i], b[bFromIndex + i]);
7390      *     return (aToIndex - aFromIndex) - (bToIndex - bFromIndex);
7391      * }</pre>
7392      *
7393      * @param a the first array to compare
7394      * @param aFromIndex the index (inclusive) of the first element in the
7395      *                   first array to be compared
7396      * @param aToIndex the index (exclusive) of the last element in the
7397      *                 first array to be compared
7398      * @param b the second array to compare
7399      * @param bFromIndex the index (inclusive) of the first element in the
7400      *                   second array to be compared
7401      * @param bToIndex the index (exclusive) of the last element in the
7402      *                 second array to be compared
7403      * @param cmp the comparator to compare array elements
7404      * @param <T> the type of array elements
7405      * @return the value {@code 0} if, over the specified ranges, the first and
7406      *         second array are equal and contain the same elements in the same
7407      *         order;
7408      *         a value less than {@code 0} if, over the specified ranges, the
7409      *         first array is lexicographically less than the second array; and
7410      *         a value greater than {@code 0} if, over the specified ranges, the
7411      *         first array is lexicographically greater than the second array
7412      * @throws IllegalArgumentException
7413      *         if {@code aFromIndex > aToIndex} or
7414      *         if {@code bFromIndex > bToIndex}
7415      * @throws ArrayIndexOutOfBoundsException
7416      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7417      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7418      * @throws NullPointerException
7419      *         if either array or the comparator is {@code null}
7420      * @since 9
7421      */
7422     public static <T> int compare(
7423             T[] a, int aFromIndex, int aToIndex,
7424             T[] b, int bFromIndex, int bToIndex,
7425             Comparator<? super T> cmp) {
7426         Objects.requireNonNull(cmp);
7427         rangeCheck(a.length, aFromIndex, aToIndex);
7428         rangeCheck(b.length, bFromIndex, bToIndex);
7429 
7430         int aLength = aToIndex - aFromIndex;
7431         int bLength = bToIndex - bFromIndex;
7432         int length = Math.min(aLength, bLength);
7433         for (int i = 0; i < length; i++) {
7434             T oa = a[aFromIndex++];
7435             T ob = b[bFromIndex++];
7436             if (oa != ob) {
7437                 // Null-value comparison is deferred to the comparator
7438                 int v = cmp.compare(oa, ob);
7439                 if (v != 0) {
7440                     return v;
7441                 }
7442             }
7443         }
7444 
7445         return aLength - bLength;
7446     }
7447 
7448 
7449     // Mismatch methods
7450 
7451     // Mismatch boolean
7452 
7453     /**
7454      * Finds and returns the index of the first mismatch between two
7455      * {@code boolean} arrays, otherwise return -1 if no mismatch is found.  The
7456      * index will be in the range of 0 (inclusive) up to the length (inclusive)
7457      * of the smaller array.
7458      *
7459      * <p>If the two arrays share a common prefix then the returned index is the
7460      * length of the common prefix and it follows that there is a mismatch
7461      * between the two elements at that index within the respective arrays.
7462      * If one array is a proper prefix of the other then the returned index is
7463      * the length of the smaller array and it follows that the index is only
7464      * valid for the larger array.
7465      * Otherwise, there is no mismatch.
7466      *
7467      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7468      * prefix of length {@code pl} if the following expression is true:
7469      * <pre>{@code
7470      *     pl >= 0 &&
7471      *     pl < Math.min(a.length, b.length) &&
7472      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7473      *     a[pl] != b[pl]
7474      * }</pre>
7475      * Note that a common prefix length of {@code 0} indicates that the first
7476      * elements from each array mismatch.
7477      *
7478      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7479      * prefix if the following expression is true:
7480      * <pre>{@code
7481      *     a.length != b.length &&
7482      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7483      *                   b, 0, Math.min(a.length, b.length))
7484      * }</pre>
7485      *
7486      * @param a the first array to be tested for a mismatch
7487      * @param b the second array to be tested for a mismatch
7488      * @return the index of the first mismatch between the two arrays,
7489      *         otherwise {@code -1}.
7490      * @throws NullPointerException
7491      *         if either array is {@code null}
7492      * @since 9
7493      */
7494     public static int mismatch(boolean[] a, boolean[] b) {
7495         int length = Math.min(a.length, b.length); // Check null array refs
7496         if (a == b)
7497             return -1;
7498 
7499         int i = ArraysSupport.mismatch(a, b, length);
7500         return (i < 0 && a.length != b.length) ? length : i;
7501     }
7502 
7503     /**
7504      * Finds and returns the relative index of the first mismatch between two
7505      * {@code boolean} arrays over the specified ranges, otherwise return -1 if
7506      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
7507      * to the length (inclusive) of the smaller range.
7508      *
7509      * <p>If the two arrays, over the specified ranges, share a common prefix
7510      * then the returned relative index is the length of the common prefix and
7511      * it follows that there is a mismatch between the two elements at that
7512      * relative index within the respective arrays.
7513      * If one array is a proper prefix of the other, over the specified ranges,
7514      * then the returned relative index is the length of the smaller range and
7515      * it follows that the relative index is only valid for the array with the
7516      * larger range.
7517      * Otherwise, there is no mismatch.
7518      *
7519      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7520      * ranges [{@code aFromIndex}, {@code aToIndex}) and
7521      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
7522      * prefix of length {@code pl} if the following expression is true:
7523      * <pre>{@code
7524      *     pl >= 0 &&
7525      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
7526      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
7527      *     a[aFromIndex + pl] != b[bFromIndex + pl]
7528      * }</pre>
7529      * Note that a common prefix length of {@code 0} indicates that the first
7530      * elements from each array mismatch.
7531      *
7532      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7533      * ranges [{@code aFromIndex}, {@code aToIndex}) and
7534      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
7535      * prefix if the following expression is true:
7536      * <pre>{@code
7537      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
7538      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
7539      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7540      * }</pre>
7541      *
7542      * @param a the first array to be tested for a mismatch
7543      * @param aFromIndex the index (inclusive) of the first element in the
7544      *                   first array to be tested
7545      * @param aToIndex the index (exclusive) of the last element in the
7546      *                 first array to be tested
7547      * @param b the second array to be tested for a mismatch
7548      * @param bFromIndex the index (inclusive) of the first element in the
7549      *                   second array to be tested
7550      * @param bToIndex the index (exclusive) of the last element in the
7551      *                 second array to be tested
7552      * @return the relative index of the first mismatch between the two arrays
7553      *         over the specified ranges, otherwise {@code -1}.
7554      * @throws IllegalArgumentException
7555      *         if {@code aFromIndex > aToIndex} or
7556      *         if {@code bFromIndex > bToIndex}
7557      * @throws ArrayIndexOutOfBoundsException
7558      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7559      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7560      * @throws NullPointerException
7561      *         if either array is {@code null}
7562      * @since 9
7563      */
7564     public static int mismatch(boolean[] a, int aFromIndex, int aToIndex,
7565                                boolean[] b, int bFromIndex, int bToIndex) {
7566         rangeCheck(a.length, aFromIndex, aToIndex);
7567         rangeCheck(b.length, bFromIndex, bToIndex);
7568 
7569         int aLength = aToIndex - aFromIndex;
7570         int bLength = bToIndex - bFromIndex;
7571         int length = Math.min(aLength, bLength);
7572         int i = ArraysSupport.mismatch(a, aFromIndex,
7573                                        b, bFromIndex,
7574                                        length);
7575         return (i < 0 && aLength != bLength) ? length : i;
7576     }
7577 
7578     // Mismatch byte
7579 
7580     /**
7581      * Finds and returns the index of the first mismatch between two {@code byte}
7582      * arrays, otherwise return -1 if no mismatch is found.  The index will be
7583      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
7584      * array.
7585      *
7586      * <p>If the two arrays share a common prefix then the returned index is the
7587      * length of the common prefix and it follows that there is a mismatch
7588      * between the two elements at that index within the respective arrays.
7589      * If one array is a proper prefix of the other then the returned index is
7590      * the length of the smaller array and it follows that the index is only
7591      * valid for the larger array.
7592      * Otherwise, there is no mismatch.
7593      *
7594      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7595      * prefix of length {@code pl} if the following expression is true:
7596      * <pre>{@code
7597      *     pl >= 0 &&
7598      *     pl < Math.min(a.length, b.length) &&
7599      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7600      *     a[pl] != b[pl]
7601      * }</pre>
7602      * Note that a common prefix length of {@code 0} indicates that the first
7603      * elements from each array mismatch.
7604      *
7605      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7606      * prefix if the following expression is true:
7607      * <pre>{@code
7608      *     a.length != b.length &&
7609      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7610      *                   b, 0, Math.min(a.length, b.length))
7611      * }</pre>
7612      *
7613      * @param a the first array to be tested for a mismatch
7614      * @param b the second array to be tested for a mismatch
7615      * @return the index of the first mismatch between the two arrays,
7616      *         otherwise {@code -1}.
7617      * @throws NullPointerException
7618      *         if either array is {@code null}
7619      * @since 9
7620      */
7621     public static int mismatch(byte[] a, byte[] b) {
7622         int length = Math.min(a.length, b.length); // Check null array refs
7623         if (a == b)
7624             return -1;
7625 
7626         int i = ArraysSupport.mismatch(a, b, length);
7627         return (i < 0 && a.length != b.length) ? length : i;
7628     }
7629 
7630     /**
7631      * Finds and returns the relative index of the first mismatch between two
7632      * {@code byte} arrays over the specified ranges, otherwise return -1 if no
7633      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
7634      * the length (inclusive) of the smaller range.
7635      *
7636      * <p>If the two arrays, over the specified ranges, share a common prefix
7637      * then the returned relative index is the length of the common prefix and
7638      * it follows that there is a mismatch between the two elements at that
7639      * relative index within the respective arrays.
7640      * If one array is a proper prefix of the other, over the specified ranges,
7641      * then the returned relative index is the length of the smaller range and
7642      * it follows that the relative index is only valid for the array with the
7643      * larger range.
7644      * Otherwise, there is no mismatch.
7645      *
7646      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7647      * ranges [{@code aFromIndex}, {@code aToIndex}) and
7648      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
7649      * prefix of length {@code pl} if the following expression is true:
7650      * <pre>{@code
7651      *     pl >= 0 &&
7652      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
7653      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
7654      *     a[aFromIndex + pl] != b[bFromIndex + pl]
7655      * }</pre>
7656      * Note that a common prefix length of {@code 0} indicates that the first
7657      * elements from each array mismatch.
7658      *
7659      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7660      * ranges [{@code aFromIndex}, {@code aToIndex}) and
7661      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
7662      * prefix if the following expression is true:
7663      * <pre>{@code
7664      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
7665      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
7666      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7667      * }</pre>
7668      *
7669      * @param a the first array to be tested for a mismatch
7670      * @param aFromIndex the index (inclusive) of the first element in the
7671      *                   first array to be tested
7672      * @param aToIndex the index (exclusive) of the last element in the
7673      *                 first array to be tested
7674      * @param b the second array to be tested for a mismatch
7675      * @param bFromIndex the index (inclusive) of the first element in the
7676      *                   second array to be tested
7677      * @param bToIndex the index (exclusive) of the last element in the
7678      *                 second array to be tested
7679      * @return the relative index of the first mismatch between the two arrays
7680      *         over the specified ranges, otherwise {@code -1}.
7681      * @throws IllegalArgumentException
7682      *         if {@code aFromIndex > aToIndex} or
7683      *         if {@code bFromIndex > bToIndex}
7684      * @throws ArrayIndexOutOfBoundsException
7685      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7686      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7687      * @throws NullPointerException
7688      *         if either array is {@code null}
7689      * @since 9
7690      */
7691     public static int mismatch(byte[] a, int aFromIndex, int aToIndex,
7692                                byte[] b, int bFromIndex, int bToIndex) {
7693         rangeCheck(a.length, aFromIndex, aToIndex);
7694         rangeCheck(b.length, bFromIndex, bToIndex);
7695 
7696         int aLength = aToIndex - aFromIndex;
7697         int bLength = bToIndex - bFromIndex;
7698         int length = Math.min(aLength, bLength);
7699         int i = ArraysSupport.mismatch(a, aFromIndex,
7700                                        b, bFromIndex,
7701                                        length);
7702         return (i < 0 && aLength != bLength) ? length : i;
7703     }
7704 
7705     // Mismatch char
7706 
7707     /**
7708      * Finds and returns the index of the first mismatch between two {@code char}
7709      * arrays, otherwise return -1 if no mismatch is found.  The index will be
7710      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
7711      * array.
7712      *
7713      * <p>If the two arrays share a common prefix then the returned index is the
7714      * length of the common prefix and it follows that there is a mismatch
7715      * between the two elements at that index within the respective arrays.
7716      * If one array is a proper prefix of the other then the returned index is
7717      * the length of the smaller array and it follows that the index is only
7718      * valid for the larger array.
7719      * Otherwise, there is no mismatch.
7720      *
7721      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7722      * prefix of length {@code pl} if the following expression is true:
7723      * <pre>{@code
7724      *     pl >= 0 &&
7725      *     pl < Math.min(a.length, b.length) &&
7726      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7727      *     a[pl] != b[pl]
7728      * }</pre>
7729      * Note that a common prefix length of {@code 0} indicates that the first
7730      * elements from each array mismatch.
7731      *
7732      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7733      * prefix if the following expression is true:
7734      * <pre>{@code
7735      *     a.length != b.length &&
7736      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7737      *                   b, 0, Math.min(a.length, b.length))
7738      * }</pre>
7739      *
7740      * @param a the first array to be tested for a mismatch
7741      * @param b the second array to be tested for a mismatch
7742      * @return the index of the first mismatch between the two arrays,
7743      *         otherwise {@code -1}.
7744      * @throws NullPointerException
7745      *         if either array is {@code null}
7746      * @since 9
7747      */
7748     public static int mismatch(char[] a, char[] b) {
7749         int length = Math.min(a.length, b.length); // Check null array refs
7750         if (a == b)
7751             return -1;
7752 
7753         int i = ArraysSupport.mismatch(a, b, length);
7754         return (i < 0 && a.length != b.length) ? length : i;
7755     }
7756 
7757     /**
7758      * Finds and returns the relative index of the first mismatch between two
7759      * {@code char} arrays over the specified ranges, otherwise return -1 if no
7760      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
7761      * the length (inclusive) of the smaller range.
7762      *
7763      * <p>If the two arrays, over the specified ranges, share a common prefix
7764      * then the returned relative index is the length of the common prefix and
7765      * it follows that there is a mismatch between the two elements at that
7766      * relative index within the respective arrays.
7767      * If one array is a proper prefix of the other, over the specified ranges,
7768      * then the returned relative index is the length of the smaller range and
7769      * it follows that the relative index is only valid for the array with the
7770      * larger range.
7771      * Otherwise, there is no mismatch.
7772      *
7773      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7774      * ranges [{@code aFromIndex}, {@code aToIndex}) and
7775      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
7776      * prefix of length {@code pl} if the following expression is true:
7777      * <pre>{@code
7778      *     pl >= 0 &&
7779      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
7780      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
7781      *     a[aFromIndex + pl] != b[bFromIndex + pl]
7782      * }</pre>
7783      * Note that a common prefix length of {@code 0} indicates that the first
7784      * elements from each array mismatch.
7785      *
7786      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7787      * ranges [{@code aFromIndex}, {@code aToIndex}) and
7788      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
7789      * prefix if the following expression is true:
7790      * <pre>{@code
7791      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
7792      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
7793      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7794      * }</pre>
7795      *
7796      * @param a the first array to be tested for a mismatch
7797      * @param aFromIndex the index (inclusive) of the first element in the
7798      *                   first array to be tested
7799      * @param aToIndex the index (exclusive) of the last element in the
7800      *                 first array to be tested
7801      * @param b the second array to be tested for a mismatch
7802      * @param bFromIndex the index (inclusive) of the first element in the
7803      *                   second array to be tested
7804      * @param bToIndex the index (exclusive) of the last element in the
7805      *                 second array to be tested
7806      * @return the relative index of the first mismatch between the two arrays
7807      *         over the specified ranges, otherwise {@code -1}.
7808      * @throws IllegalArgumentException
7809      *         if {@code aFromIndex > aToIndex} or
7810      *         if {@code bFromIndex > bToIndex}
7811      * @throws ArrayIndexOutOfBoundsException
7812      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7813      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7814      * @throws NullPointerException
7815      *         if either array is {@code null}
7816      * @since 9
7817      */
7818     public static int mismatch(char[] a, int aFromIndex, int aToIndex,
7819                                char[] b, int bFromIndex, int bToIndex) {
7820         rangeCheck(a.length, aFromIndex, aToIndex);
7821         rangeCheck(b.length, bFromIndex, bToIndex);
7822 
7823         int aLength = aToIndex - aFromIndex;
7824         int bLength = bToIndex - bFromIndex;
7825         int length = Math.min(aLength, bLength);
7826         int i = ArraysSupport.mismatch(a, aFromIndex,
7827                                        b, bFromIndex,
7828                                        length);
7829         return (i < 0 && aLength != bLength) ? length : i;
7830     }
7831 
7832     // Mismatch short
7833 
7834     /**
7835      * Finds and returns the index of the first mismatch between two {@code short}
7836      * arrays, otherwise return -1 if no mismatch is found.  The index will be
7837      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
7838      * array.
7839      *
7840      * <p>If the two arrays share a common prefix then the returned index is the
7841      * length of the common prefix and it follows that there is a mismatch
7842      * between the two elements at that index within the respective arrays.
7843      * If one array is a proper prefix of the other then the returned index is
7844      * the length of the smaller array and it follows that the index is only
7845      * valid for the larger array.
7846      * Otherwise, there is no mismatch.
7847      *
7848      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7849      * prefix of length {@code pl} if the following expression is true:
7850      * <pre>{@code
7851      *     pl >= 0 &&
7852      *     pl < Math.min(a.length, b.length) &&
7853      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7854      *     a[pl] != b[pl]
7855      * }</pre>
7856      * Note that a common prefix length of {@code 0} indicates that the first
7857      * elements from each array mismatch.
7858      *
7859      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7860      * prefix if the following expression is true:
7861      * <pre>{@code
7862      *     a.length != b.length &&
7863      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7864      *                   b, 0, Math.min(a.length, b.length))
7865      * }</pre>
7866      *
7867      * @param a the first array to be tested for a mismatch
7868      * @param b the second array to be tested for a mismatch
7869      * @return the index of the first mismatch between the two arrays,
7870      *         otherwise {@code -1}.
7871      * @throws NullPointerException
7872      *         if either array is {@code null}
7873      * @since 9
7874      */
7875     public static int mismatch(short[] a, short[] b) {
7876         int length = Math.min(a.length, b.length); // Check null array refs
7877         if (a == b)
7878             return -1;
7879 
7880         int i = ArraysSupport.mismatch(a, b, length);
7881         return (i < 0 && a.length != b.length) ? length : i;
7882     }
7883 
7884     /**
7885      * Finds and returns the relative index of the first mismatch between two
7886      * {@code short} arrays over the specified ranges, otherwise return -1 if no
7887      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
7888      * the length (inclusive) of the smaller range.
7889      *
7890      * <p>If the two arrays, over the specified ranges, share a common prefix
7891      * then the returned relative index is the length of the common prefix and
7892      * it follows that there is a mismatch between the two elements at that
7893      * relative index within the respective arrays.
7894      * If one array is a proper prefix of the other, over the specified ranges,
7895      * then the returned relative index is the length of the smaller range and
7896      * it follows that the relative index is only valid for the array with the
7897      * larger range.
7898      * Otherwise, there is no mismatch.
7899      *
7900      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7901      * ranges [{@code aFromIndex}, {@code aToIndex}) and
7902      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
7903      * prefix of length {@code pl} if the following expression is true:
7904      * <pre>{@code
7905      *     pl >= 0 &&
7906      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
7907      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
7908      *     a[aFromIndex + pl] != b[bFromIndex + pl]
7909      * }</pre>
7910      * Note that a common prefix length of {@code 0} indicates that the first
7911      * elements from each array mismatch.
7912      *
7913      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
7914      * ranges [{@code aFromIndex}, {@code aToIndex}) and
7915      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
7916      * prefix if the following expression is true:
7917      * <pre>{@code
7918      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
7919      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
7920      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
7921      * }</pre>
7922      *
7923      * @param a the first array to be tested for a mismatch
7924      * @param aFromIndex the index (inclusive) of the first element in the
7925      *                   first array to be tested
7926      * @param aToIndex the index (exclusive) of the last element in the
7927      *                 first array to be tested
7928      * @param b the second array to be tested for a mismatch
7929      * @param bFromIndex the index (inclusive) of the first element in the
7930      *                   second array to be tested
7931      * @param bToIndex the index (exclusive) of the last element in the
7932      *                 second array to be tested
7933      * @return the relative index of the first mismatch between the two arrays
7934      *         over the specified ranges, otherwise {@code -1}.
7935      * @throws IllegalArgumentException
7936      *         if {@code aFromIndex > aToIndex} or
7937      *         if {@code bFromIndex > bToIndex}
7938      * @throws ArrayIndexOutOfBoundsException
7939      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
7940      *         if {@code bFromIndex < 0 or bToIndex > b.length}
7941      * @throws NullPointerException
7942      *         if either array is {@code null}
7943      * @since 9
7944      */
7945     public static int mismatch(short[] a, int aFromIndex, int aToIndex,
7946                                short[] b, int bFromIndex, int bToIndex) {
7947         rangeCheck(a.length, aFromIndex, aToIndex);
7948         rangeCheck(b.length, bFromIndex, bToIndex);
7949 
7950         int aLength = aToIndex - aFromIndex;
7951         int bLength = bToIndex - bFromIndex;
7952         int length = Math.min(aLength, bLength);
7953         int i = ArraysSupport.mismatch(a, aFromIndex,
7954                                        b, bFromIndex,
7955                                        length);
7956         return (i < 0 && aLength != bLength) ? length : i;
7957     }
7958 
7959     // Mismatch int
7960 
7961     /**
7962      * Finds and returns the index of the first mismatch between two {@code int}
7963      * arrays, otherwise return -1 if no mismatch is found.  The index will be
7964      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
7965      * array.
7966      *
7967      * <p>If the two arrays share a common prefix then the returned index is the
7968      * length of the common prefix and it follows that there is a mismatch
7969      * between the two elements at that index within the respective arrays.
7970      * If one array is a proper prefix of the other then the returned index is
7971      * the length of the smaller array and it follows that the index is only
7972      * valid for the larger array.
7973      * Otherwise, there is no mismatch.
7974      *
7975      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
7976      * prefix of length {@code pl} if the following expression is true:
7977      * <pre>{@code
7978      *     pl >= 0 &&
7979      *     pl < Math.min(a.length, b.length) &&
7980      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
7981      *     a[pl] != b[pl]
7982      * }</pre>
7983      * Note that a common prefix length of {@code 0} indicates that the first
7984      * elements from each array mismatch.
7985      *
7986      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
7987      * prefix if the following expression is true:
7988      * <pre>{@code
7989      *     a.length != b.length &&
7990      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
7991      *                   b, 0, Math.min(a.length, b.length))
7992      * }</pre>
7993      *
7994      * @param a the first array to be tested for a mismatch
7995      * @param b the second array to be tested for a mismatch
7996      * @return the index of the first mismatch between the two arrays,
7997      *         otherwise {@code -1}.
7998      * @throws NullPointerException
7999      *         if either array is {@code null}
8000      * @since 9
8001      */
8002     public static int mismatch(int[] a, int[] b) {
8003         int length = Math.min(a.length, b.length); // Check null array refs
8004         if (a == b)
8005             return -1;
8006 
8007         int i = ArraysSupport.mismatch(a, b, length);
8008         return (i < 0 && a.length != b.length) ? length : i;
8009     }
8010 
8011     /**
8012      * Finds and returns the relative index of the first mismatch between two
8013      * {@code int} arrays over the specified ranges, otherwise return -1 if no
8014      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
8015      * the length (inclusive) of the smaller range.
8016      *
8017      * <p>If the two arrays, over the specified ranges, share a common prefix
8018      * then the returned relative index is the length of the common prefix and
8019      * it follows that there is a mismatch between the two elements at that
8020      * relative index within the respective arrays.
8021      * If one array is a proper prefix of the other, over the specified ranges,
8022      * then the returned relative index is the length of the smaller range and
8023      * it follows that the relative index is only valid for the array with the
8024      * larger range.
8025      * Otherwise, there is no mismatch.
8026      *
8027      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8028      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8029      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
8030      * prefix of length {@code pl} if the following expression is true:
8031      * <pre>{@code
8032      *     pl >= 0 &&
8033      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8034      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8035      *     a[aFromIndex + pl] != b[bFromIndex + pl]
8036      * }</pre>
8037      * Note that a common prefix length of {@code 0} indicates that the first
8038      * elements from each array mismatch.
8039      *
8040      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8041      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8042      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
8043      * prefix if the following expression is true:
8044      * <pre>{@code
8045      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8046      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8047      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8048      * }</pre>
8049      *
8050      * @param a the first array to be tested for a mismatch
8051      * @param aFromIndex the index (inclusive) of the first element in the
8052      *                   first array to be tested
8053      * @param aToIndex the index (exclusive) of the last element in the
8054      *                 first array to be tested
8055      * @param b the second array to be tested for a mismatch
8056      * @param bFromIndex the index (inclusive) of the first element in the
8057      *                   second array to be tested
8058      * @param bToIndex the index (exclusive) of the last element in the
8059      *                 second array to be tested
8060      * @return the relative index of the first mismatch between the two arrays
8061      *         over the specified ranges, otherwise {@code -1}.
8062      * @throws IllegalArgumentException
8063      *         if {@code aFromIndex > aToIndex} or
8064      *         if {@code bFromIndex > bToIndex}
8065      * @throws ArrayIndexOutOfBoundsException
8066      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8067      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8068      * @throws NullPointerException
8069      *         if either array is {@code null}
8070      * @since 9
8071      */
8072     public static int mismatch(int[] a, int aFromIndex, int aToIndex,
8073                                int[] b, int bFromIndex, int bToIndex) {
8074         rangeCheck(a.length, aFromIndex, aToIndex);
8075         rangeCheck(b.length, bFromIndex, bToIndex);
8076 
8077         int aLength = aToIndex - aFromIndex;
8078         int bLength = bToIndex - bFromIndex;
8079         int length = Math.min(aLength, bLength);
8080         int i = ArraysSupport.mismatch(a, aFromIndex,
8081                                        b, bFromIndex,
8082                                        length);
8083         return (i < 0 && aLength != bLength) ? length : i;
8084     }
8085 
8086     // Mismatch long
8087 
8088     /**
8089      * Finds and returns the index of the first mismatch between two {@code long}
8090      * arrays, otherwise return -1 if no mismatch is found.  The index will be
8091      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
8092      * array.
8093      *
8094      * <p>If the two arrays share a common prefix then the returned index is the
8095      * length of the common prefix and it follows that there is a mismatch
8096      * between the two elements at that index within the respective arrays.
8097      * If one array is a proper prefix of the other then the returned index is
8098      * the length of the smaller array and it follows that the index is only
8099      * valid for the larger array.
8100      * Otherwise, there is no mismatch.
8101      *
8102      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8103      * prefix of length {@code pl} if the following expression is true:
8104      * <pre>{@code
8105      *     pl >= 0 &&
8106      *     pl < Math.min(a.length, b.length) &&
8107      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8108      *     a[pl] != b[pl]
8109      * }</pre>
8110      * Note that a common prefix length of {@code 0} indicates that the first
8111      * elements from each array mismatch.
8112      *
8113      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8114      * prefix if the following expression is true:
8115      * <pre>{@code
8116      *     a.length != b.length &&
8117      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8118      *                   b, 0, Math.min(a.length, b.length))
8119      * }</pre>
8120      *
8121      * @param a the first array to be tested for a mismatch
8122      * @param b the second array to be tested for a mismatch
8123      * @return the index of the first mismatch between the two arrays,
8124      *         otherwise {@code -1}.
8125      * @throws NullPointerException
8126      *         if either array is {@code null}
8127      * @since 9
8128      */
8129     public static int mismatch(long[] a, long[] b) {
8130         int length = Math.min(a.length, b.length); // Check null array refs
8131         if (a == b)
8132             return -1;
8133 
8134         int i = ArraysSupport.mismatch(a, b, length);
8135         return (i < 0 && a.length != b.length) ? length : i;
8136     }
8137 
8138     /**
8139      * Finds and returns the relative index of the first mismatch between two
8140      * {@code long} arrays over the specified ranges, otherwise return -1 if no
8141      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
8142      * the length (inclusive) of the smaller range.
8143      *
8144      * <p>If the two arrays, over the specified ranges, share a common prefix
8145      * then the returned relative index is the length of the common prefix and
8146      * it follows that there is a mismatch between the two elements at that
8147      * relative index within the respective arrays.
8148      * If one array is a proper prefix of the other, over the specified ranges,
8149      * then the returned relative index is the length of the smaller range and
8150      * it follows that the relative index is only valid for the array with the
8151      * larger range.
8152      * Otherwise, there is no mismatch.
8153      *
8154      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8155      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8156      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
8157      * prefix of length {@code pl} if the following expression is true:
8158      * <pre>{@code
8159      *     pl >= 0 &&
8160      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8161      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8162      *     a[aFromIndex + pl] != b[bFromIndex + pl]
8163      * }</pre>
8164      * Note that a common prefix length of {@code 0} indicates that the first
8165      * elements from each array mismatch.
8166      *
8167      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8168      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8169      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
8170      * prefix if the following expression is true:
8171      * <pre>{@code
8172      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8173      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8174      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8175      * }</pre>
8176      *
8177      * @param a the first array to be tested for a mismatch
8178      * @param aFromIndex the index (inclusive) of the first element in the
8179      *                   first array to be tested
8180      * @param aToIndex the index (exclusive) of the last element in the
8181      *                 first array to be tested
8182      * @param b the second array to be tested for a mismatch
8183      * @param bFromIndex the index (inclusive) of the first element in the
8184      *                   second array to be tested
8185      * @param bToIndex the index (exclusive) of the last element in the
8186      *                 second array to be tested
8187      * @return the relative index of the first mismatch between the two arrays
8188      *         over the specified ranges, otherwise {@code -1}.
8189      * @throws IllegalArgumentException
8190      *         if {@code aFromIndex > aToIndex} or
8191      *         if {@code bFromIndex > bToIndex}
8192      * @throws ArrayIndexOutOfBoundsException
8193      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8194      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8195      * @throws NullPointerException
8196      *         if either array is {@code null}
8197      * @since 9
8198      */
8199     public static int mismatch(long[] a, int aFromIndex, int aToIndex,
8200                                long[] b, int bFromIndex, int bToIndex) {
8201         rangeCheck(a.length, aFromIndex, aToIndex);
8202         rangeCheck(b.length, bFromIndex, bToIndex);
8203 
8204         int aLength = aToIndex - aFromIndex;
8205         int bLength = bToIndex - bFromIndex;
8206         int length = Math.min(aLength, bLength);
8207         int i = ArraysSupport.mismatch(a, aFromIndex,
8208                                        b, bFromIndex,
8209                                        length);
8210         return (i < 0 && aLength != bLength) ? length : i;
8211     }
8212 
8213     // Mismatch float
8214 
8215     /**
8216      * Finds and returns the index of the first mismatch between two {@code float}
8217      * arrays, otherwise return -1 if no mismatch is found.  The index will be
8218      * in the range of 0 (inclusive) up to the length (inclusive) of the smaller
8219      * array.
8220      *
8221      * <p>If the two arrays share a common prefix then the returned index is the
8222      * length of the common prefix and it follows that there is a mismatch
8223      * between the two elements at that index within the respective arrays.
8224      * If one array is a proper prefix of the other then the returned index is
8225      * the length of the smaller array and it follows that the index is only
8226      * valid for the larger array.
8227      * Otherwise, there is no mismatch.
8228      *
8229      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8230      * prefix of length {@code pl} if the following expression is true:
8231      * <pre>{@code
8232      *     pl >= 0 &&
8233      *     pl < Math.min(a.length, b.length) &&
8234      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8235      *     Float.compare(a[pl], b[pl]) != 0
8236      * }</pre>
8237      * Note that a common prefix length of {@code 0} indicates that the first
8238      * elements from each array mismatch.
8239      *
8240      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8241      * prefix if the following expression is true:
8242      * <pre>{@code
8243      *     a.length != b.length &&
8244      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8245      *                   b, 0, Math.min(a.length, b.length))
8246      * }</pre>
8247      *
8248      * @param a the first array to be tested for a mismatch
8249      * @param b the second array to be tested for a mismatch
8250      * @return the index of the first mismatch between the two arrays,
8251      *         otherwise {@code -1}.
8252      * @throws NullPointerException
8253      *         if either array is {@code null}
8254      * @since 9
8255      */
8256     public static int mismatch(float[] a, float[] b) {
8257         int length = Math.min(a.length, b.length); // Check null array refs
8258         if (a == b)
8259             return -1;
8260 
8261         int i = ArraysSupport.mismatch(a, b, length);
8262         return (i < 0 && a.length != b.length) ? length : i;
8263     }
8264 
8265     /**
8266      * Finds and returns the relative index of the first mismatch between two
8267      * {@code float} arrays over the specified ranges, otherwise return -1 if no
8268      * mismatch is found.  The index will be in the range of 0 (inclusive) up to
8269      * the length (inclusive) of the smaller range.
8270      *
8271      * <p>If the two arrays, over the specified ranges, share a common prefix
8272      * then the returned relative index is the length of the common prefix and
8273      * it follows that there is a mismatch between the two elements at that
8274      * relative index within the respective arrays.
8275      * If one array is a proper prefix of the other, over the specified ranges,
8276      * then the returned relative index is the length of the smaller range and
8277      * it follows that the relative index is only valid for the array with the
8278      * larger range.
8279      * Otherwise, there is no mismatch.
8280      *
8281      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8282      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8283      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
8284      * prefix of length {@code pl} if the following expression is true:
8285      * <pre>{@code
8286      *     pl >= 0 &&
8287      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8288      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8289      *     Float.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
8290      * }</pre>
8291      * Note that a common prefix length of {@code 0} indicates that the first
8292      * elements from each array mismatch.
8293      *
8294      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8295      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8296      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
8297      * prefix if the following expression is true:
8298      * <pre>{@code
8299      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8300      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8301      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8302      * }</pre>
8303      *
8304      * @param a the first array to be tested for a mismatch
8305      * @param aFromIndex the index (inclusive) of the first element in the
8306      *                   first array to be tested
8307      * @param aToIndex the index (exclusive) of the last element in the
8308      *                 first array to be tested
8309      * @param b the second array to be tested for a mismatch
8310      * @param bFromIndex the index (inclusive) of the first element in the
8311      *                   second array to be tested
8312      * @param bToIndex the index (exclusive) of the last element in the
8313      *                 second array to be tested
8314      * @return the relative index of the first mismatch between the two arrays
8315      *         over the specified ranges, otherwise {@code -1}.
8316      * @throws IllegalArgumentException
8317      *         if {@code aFromIndex > aToIndex} or
8318      *         if {@code bFromIndex > bToIndex}
8319      * @throws ArrayIndexOutOfBoundsException
8320      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8321      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8322      * @throws NullPointerException
8323      *         if either array is {@code null}
8324      * @since 9
8325      */
8326     public static int mismatch(float[] a, int aFromIndex, int aToIndex,
8327                                float[] b, int bFromIndex, int bToIndex) {
8328         rangeCheck(a.length, aFromIndex, aToIndex);
8329         rangeCheck(b.length, bFromIndex, bToIndex);
8330 
8331         int aLength = aToIndex - aFromIndex;
8332         int bLength = bToIndex - bFromIndex;
8333         int length = Math.min(aLength, bLength);
8334         int i = ArraysSupport.mismatch(a, aFromIndex,
8335                                        b, bFromIndex,
8336                                        length);
8337         return (i < 0 && aLength != bLength) ? length : i;
8338     }
8339 
8340     // Mismatch double
8341 
8342     /**
8343      * Finds and returns the index of the first mismatch between two
8344      * {@code double} arrays, otherwise return -1 if no mismatch is found.  The
8345      * index will be in the range of 0 (inclusive) up to the length (inclusive)
8346      * of the smaller array.
8347      *
8348      * <p>If the two arrays share a common prefix then the returned index is the
8349      * length of the common prefix and it follows that there is a mismatch
8350      * between the two elements at that index within the respective arrays.
8351      * If one array is a proper prefix of the other then the returned index is
8352      * the length of the smaller array and it follows that the index is only
8353      * valid for the larger array.
8354      * Otherwise, there is no mismatch.
8355      *
8356      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8357      * prefix of length {@code pl} if the following expression is true:
8358      * <pre>{@code
8359      *     pl >= 0 &&
8360      *     pl < Math.min(a.length, b.length) &&
8361      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8362      *     Double.compare(a[pl], b[pl]) != 0
8363      * }</pre>
8364      * Note that a common prefix length of {@code 0} indicates that the first
8365      * elements from each array mismatch.
8366      *
8367      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8368      * prefix if the following expression is true:
8369      * <pre>{@code
8370      *     a.length != b.length &&
8371      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8372      *                   b, 0, Math.min(a.length, b.length))
8373      * }</pre>
8374      *
8375      * @param a the first array to be tested for a mismatch
8376      * @param b the second array to be tested for a mismatch
8377      * @return the index of the first mismatch between the two arrays,
8378      *         otherwise {@code -1}.
8379      * @throws NullPointerException
8380      *         if either array is {@code null}
8381      * @since 9
8382      */
8383     public static int mismatch(double[] a, double[] b) {
8384         int length = Math.min(a.length, b.length); // Check null array refs
8385         if (a == b)
8386             return -1;
8387 
8388         int i = ArraysSupport.mismatch(a, b, length);
8389         return (i < 0 && a.length != b.length) ? length : i;
8390     }
8391 
8392     /**
8393      * Finds and returns the relative index of the first mismatch between two
8394      * {@code double} arrays over the specified ranges, otherwise return -1 if
8395      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
8396      * to the length (inclusive) of the smaller range.
8397      *
8398      * <p>If the two arrays, over the specified ranges, share a common prefix
8399      * then the returned relative index is the length of the common prefix and
8400      * it follows that there is a mismatch between the two elements at that
8401      * relative index within the respective arrays.
8402      * If one array is a proper prefix of the other, over the specified ranges,
8403      * then the returned relative index is the length of the smaller range and
8404      * it follows that the relative index is only valid for the array with the
8405      * larger range.
8406      * Otherwise, there is no mismatch.
8407      *
8408      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8409      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8410      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
8411      * prefix of length {@code pl} if the following expression is true:
8412      * <pre>{@code
8413      *     pl >= 0 &&
8414      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8415      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8416      *     Double.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
8417      * }</pre>
8418      * Note that a common prefix length of {@code 0} indicates that the first
8419      * elements from each array mismatch.
8420      *
8421      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8422      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8423      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
8424      * prefix if the following expression is true:
8425      * <pre>{@code
8426      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8427      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8428      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8429      * }</pre>
8430      *
8431      * @param a the first array to be tested for a mismatch
8432      * @param aFromIndex the index (inclusive) of the first element in the
8433      *                   first array to be tested
8434      * @param aToIndex the index (exclusive) of the last element in the
8435      *                 first array to be tested
8436      * @param b the second array to be tested for a mismatch
8437      * @param bFromIndex the index (inclusive) of the first element in the
8438      *                   second array to be tested
8439      * @param bToIndex the index (exclusive) of the last element in the
8440      *                 second array to be tested
8441      * @return the relative index of the first mismatch between the two arrays
8442      *         over the specified ranges, otherwise {@code -1}.
8443      * @throws IllegalArgumentException
8444      *         if {@code aFromIndex > aToIndex} or
8445      *         if {@code bFromIndex > bToIndex}
8446      * @throws ArrayIndexOutOfBoundsException
8447      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8448      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8449      * @throws NullPointerException
8450      *         if either array is {@code null}
8451      * @since 9
8452      */
8453     public static int mismatch(double[] a, int aFromIndex, int aToIndex,
8454                                double[] b, int bFromIndex, int bToIndex) {
8455         rangeCheck(a.length, aFromIndex, aToIndex);
8456         rangeCheck(b.length, bFromIndex, bToIndex);
8457 
8458         int aLength = aToIndex - aFromIndex;
8459         int bLength = bToIndex - bFromIndex;
8460         int length = Math.min(aLength, bLength);
8461         int i = ArraysSupport.mismatch(a, aFromIndex,
8462                                        b, bFromIndex,
8463                                        length);
8464         return (i < 0 && aLength != bLength) ? length : i;
8465     }
8466 
8467     // Mismatch objects
8468 
8469     /**
8470      * Finds and returns the index of the first mismatch between two
8471      * {@code Object} arrays, otherwise return -1 if no mismatch is found.  The
8472      * index will be in the range of 0 (inclusive) up to the length (inclusive)
8473      * of the smaller array.
8474      *
8475      * <p>If the two arrays share a common prefix then the returned index is the
8476      * length of the common prefix and it follows that there is a mismatch
8477      * between the two elements at that index within the respective arrays.
8478      * If one array is a proper prefix of the other then the returned index is
8479      * the length of the smaller array and it follows that the index is only
8480      * valid for the larger array.
8481      * Otherwise, there is no mismatch.
8482      *
8483      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8484      * prefix of length {@code pl} if the following expression is true:
8485      * <pre>{@code
8486      *     pl >= 0 &&
8487      *     pl < Math.min(a.length, b.length) &&
8488      *     Arrays.equals(a, 0, pl, b, 0, pl) &&
8489      *     !Objects.equals(a[pl], b[pl])
8490      * }</pre>
8491      * Note that a common prefix length of {@code 0} indicates that the first
8492      * elements from each array mismatch.
8493      *
8494      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8495      * prefix if the following expression is true:
8496      * <pre>{@code
8497      *     a.length != b.length &&
8498      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8499      *                   b, 0, Math.min(a.length, b.length))
8500      * }</pre>
8501      *
8502      * @param a the first array to be tested for a mismatch
8503      * @param b the second array to be tested for a mismatch
8504      * @return the index of the first mismatch between the two arrays,
8505      *         otherwise {@code -1}.
8506      * @throws NullPointerException
8507      *         if either array is {@code null}
8508      * @since 9
8509      */
8510     public static int mismatch(Object[] a, Object[] b) {
8511         int length = Math.min(a.length, b.length); // Check null array refs
8512         if (a == b)
8513             return -1;
8514 
8515         for (int i = 0; i < length; i++) {
8516             if (!Objects.equals(a[i], b[i]))
8517                 return i;
8518         }
8519 
8520         return a.length != b.length ? length : -1;
8521     }
8522 
8523     /**
8524      * Finds and returns the relative index of the first mismatch between two
8525      * {@code Object} arrays over the specified ranges, otherwise return -1 if
8526      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
8527      * to the length (inclusive) of the smaller range.
8528      *
8529      * <p>If the two arrays, over the specified ranges, share a common prefix
8530      * then the returned relative index is the length of the common prefix and
8531      * it follows that there is a mismatch between the two elements at that
8532      * relative index within the respective arrays.
8533      * If one array is a proper prefix of the other, over the specified ranges,
8534      * then the returned relative index is the length of the smaller range and
8535      * it follows that the relative index is only valid for the array with the
8536      * larger range.
8537      * Otherwise, there is no mismatch.
8538      *
8539      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8540      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8541      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
8542      * prefix of length {@code pl} if the following expression is true:
8543      * <pre>{@code
8544      *     pl >= 0 &&
8545      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8546      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) &&
8547      *     !Objects.equals(a[aFromIndex + pl], b[bFromIndex + pl])
8548      * }</pre>
8549      * Note that a common prefix length of {@code 0} indicates that the first
8550      * elements from each array mismatch.
8551      *
8552      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8553      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8554      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
8555      * prefix if the following expression is true:
8556      * <pre>{@code
8557      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8558      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8559      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex))
8560      * }</pre>
8561      *
8562      * @param a the first array to be tested for a mismatch
8563      * @param aFromIndex the index (inclusive) of the first element in the
8564      *                   first array to be tested
8565      * @param aToIndex the index (exclusive) of the last element in the
8566      *                 first array to be tested
8567      * @param b the second array to be tested for a mismatch
8568      * @param bFromIndex the index (inclusive) of the first element in the
8569      *                   second array to be tested
8570      * @param bToIndex the index (exclusive) of the last element in the
8571      *                 second array to be tested
8572      * @return the relative index of the first mismatch between the two arrays
8573      *         over the specified ranges, otherwise {@code -1}.
8574      * @throws IllegalArgumentException
8575      *         if {@code aFromIndex > aToIndex} or
8576      *         if {@code bFromIndex > bToIndex}
8577      * @throws ArrayIndexOutOfBoundsException
8578      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8579      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8580      * @throws NullPointerException
8581      *         if either array is {@code null}
8582      * @since 9
8583      */
8584     public static int mismatch(
8585             Object[] a, int aFromIndex, int aToIndex,
8586             Object[] b, int bFromIndex, int bToIndex) {
8587         rangeCheck(a.length, aFromIndex, aToIndex);
8588         rangeCheck(b.length, bFromIndex, bToIndex);
8589 
8590         int aLength = aToIndex - aFromIndex;
8591         int bLength = bToIndex - bFromIndex;
8592         int length = Math.min(aLength, bLength);
8593         for (int i = 0; i < length; i++) {
8594             if (!Objects.equals(a[aFromIndex++], b[bFromIndex++]))
8595                 return i;
8596         }
8597 
8598         return aLength != bLength ? length : -1;
8599     }
8600 
8601     /**
8602      * Finds and returns the index of the first mismatch between two
8603      * {@code Object} arrays, otherwise return -1 if no mismatch is found.
8604      * The index will be in the range of 0 (inclusive) up to the length
8605      * (inclusive) of the smaller array.
8606      *
8607      * <p>The specified comparator is used to determine if two array elements
8608      * from the each array are not equal.
8609      *
8610      * <p>If the two arrays share a common prefix then the returned index is the
8611      * length of the common prefix and it follows that there is a mismatch
8612      * between the two elements at that index within the respective arrays.
8613      * If one array is a proper prefix of the other then the returned index is
8614      * the length of the smaller array and it follows that the index is only
8615      * valid for the larger array.
8616      * Otherwise, there is no mismatch.
8617      *
8618      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common
8619      * prefix of length {@code pl} if the following expression is true:
8620      * <pre>{@code
8621      *     pl >= 0 &&
8622      *     pl < Math.min(a.length, b.length) &&
8623      *     Arrays.equals(a, 0, pl, b, 0, pl, cmp)
8624      *     cmp.compare(a[pl], b[pl]) != 0
8625      * }</pre>
8626      * Note that a common prefix length of {@code 0} indicates that the first
8627      * elements from each array mismatch.
8628      *
8629      * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper
8630      * prefix if the following expression is true:
8631      * <pre>{@code
8632      *     a.length != b.length &&
8633      *     Arrays.equals(a, 0, Math.min(a.length, b.length),
8634      *                   b, 0, Math.min(a.length, b.length),
8635      *                   cmp)
8636      * }</pre>
8637      *
8638      * @param a the first array to be tested for a mismatch
8639      * @param b the second array to be tested for a mismatch
8640      * @param cmp the comparator to compare array elements
8641      * @param <T> the type of array elements
8642      * @return the index of the first mismatch between the two arrays,
8643      *         otherwise {@code -1}.
8644      * @throws NullPointerException
8645      *         if either array or the comparator is {@code null}
8646      * @since 9
8647      */
8648     public static <T> int mismatch(T[] a, T[] b, Comparator<? super T> cmp) {
8649         Objects.requireNonNull(cmp);
8650         int length = Math.min(a.length, b.length); // Check null array refs
8651         if (a == b)
8652             return -1;
8653 
8654         for (int i = 0; i < length; i++) {
8655             T oa = a[i];
8656             T ob = b[i];
8657             if (oa != ob) {
8658                 // Null-value comparison is deferred to the comparator
8659                 int v = cmp.compare(oa, ob);
8660                 if (v != 0) {
8661                     return i;
8662                 }
8663             }
8664         }
8665 
8666         return a.length != b.length ? length : -1;
8667     }
8668 
8669     /**
8670      * Finds and returns the relative index of the first mismatch between two
8671      * {@code Object} arrays over the specified ranges, otherwise return -1 if
8672      * no mismatch is found.  The index will be in the range of 0 (inclusive) up
8673      * to the length (inclusive) of the smaller range.
8674      *
8675      * <p>If the two arrays, over the specified ranges, share a common prefix
8676      * then the returned relative index is the length of the common prefix and
8677      * it follows that there is a mismatch between the two elements at that
8678      * relative index within the respective arrays.
8679      * If one array is a proper prefix of the other, over the specified ranges,
8680      * then the returned relative index is the length of the smaller range and
8681      * it follows that the relative index is only valid for the array with the
8682      * larger range.
8683      * Otherwise, there is no mismatch.
8684      *
8685      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8686      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8687      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common
8688      * prefix of length {@code pl} if the following expression is true:
8689      * <pre>{@code
8690      *     pl >= 0 &&
8691      *     pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) &&
8692      *     Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl, cmp) &&
8693      *     cmp.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0
8694      * }</pre>
8695      * Note that a common prefix length of {@code 0} indicates that the first
8696      * elements from each array mismatch.
8697      *
8698      * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified
8699      * ranges [{@code aFromIndex}, {@code aToIndex}) and
8700      * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper
8701      * prefix if the following expression is true:
8702      * <pre>{@code
8703      *     (aToIndex - aFromIndex) != (bToIndex - bFromIndex) &&
8704      *     Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8705      *                   b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex),
8706      *                   cmp)
8707      * }</pre>
8708      *
8709      * @param a the first array to be tested for a mismatch
8710      * @param aFromIndex the index (inclusive) of the first element in the
8711      *                   first array to be tested
8712      * @param aToIndex the index (exclusive) of the last element in the
8713      *                 first array to be tested
8714      * @param b the second array to be tested for a mismatch
8715      * @param bFromIndex the index (inclusive) of the first element in the
8716      *                   second array to be tested
8717      * @param bToIndex the index (exclusive) of the last element in the
8718      *                 second array to be tested
8719      * @param cmp the comparator to compare array elements
8720      * @param <T> the type of array elements
8721      * @return the relative index of the first mismatch between the two arrays
8722      *         over the specified ranges, otherwise {@code -1}.
8723      * @throws IllegalArgumentException
8724      *         if {@code aFromIndex > aToIndex} or
8725      *         if {@code bFromIndex > bToIndex}
8726      * @throws ArrayIndexOutOfBoundsException
8727      *         if {@code aFromIndex < 0 or aToIndex > a.length} or
8728      *         if {@code bFromIndex < 0 or bToIndex > b.length}
8729      * @throws NullPointerException
8730      *         if either array or the comparator is {@code null}
8731      * @since 9
8732      */
8733     public static <T> int mismatch(
8734             T[] a, int aFromIndex, int aToIndex,
8735             T[] b, int bFromIndex, int bToIndex,
8736             Comparator<? super T> cmp) {
8737         Objects.requireNonNull(cmp);
8738         rangeCheck(a.length, aFromIndex, aToIndex);
8739         rangeCheck(b.length, bFromIndex, bToIndex);
8740 
8741         int aLength = aToIndex - aFromIndex;
8742         int bLength = bToIndex - bFromIndex;
8743         int length = Math.min(aLength, bLength);
8744         for (int i = 0; i < length; i++) {
8745             T oa = a[aFromIndex++];
8746             T ob = b[bFromIndex++];
8747             if (oa != ob) {
8748                 // Null-value comparison is deferred to the comparator
8749                 int v = cmp.compare(oa, ob);
8750                 if (v != 0) {
8751                     return i;
8752                 }
8753             }
8754         }
8755 
8756         return aLength != bLength ? length : -1;
8757     }
8758 }
--- EOF ---