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