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