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