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