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