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