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