1 /* 2 * Copyright (c) 1997, 2024, Oracle and/or its affiliates. All rights reserved. 3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER. 4 * 5 * This code is free software; you can redistribute it and/or modify it 6 * under the terms of the GNU General Public License version 2 only, as 7 * published by the Free Software Foundation. Oracle designates this 8 * particular file as subject to the "Classpath" exception as provided 9 * by Oracle in the LICENSE file that accompanied this code. 10 * 11 * This code is distributed in the hope that it will be useful, but WITHOUT 12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or 13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License 14 * version 2 for more details (a copy is included in the LICENSE file that 15 * accompanied this code). 16 * 17 * You should have received a copy of the GNU General Public License version 18 * 2 along with this work; if not, write to the Free Software Foundation, 19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA. 20 * 21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA 22 * or visit www.oracle.com if you need additional information or have any 23 * questions. 24 */ 25 26 package java.util; 27 28 import jdk.internal.util.ArraysSupport; 29 import jdk.internal.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 <T> the class of the objects in the returned array 3496 * @param <U> the class of the objects in the original 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 <T> the class of the objects in the returned array 3790 * @param <U> the class of the objects in the original 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 ArraysSupport.hashCode(a, 0, a.length, 1); 4369 } 4370 4371 /** 4372 * Returns a hash code based on the contents of the specified array. 4373 * For any two {@code short} arrays {@code a} and {@code b} 4374 * such that {@code Arrays.equals(a, b)}, it is also the case that 4375 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}. 4376 * 4377 * <p>The value returned by this method is the same value that would be 4378 * obtained by invoking the {@link List#hashCode() hashCode} 4379 * method on a {@link List} containing a sequence of {@link Short} 4380 * instances representing the elements of {@code a} in the same order. 4381 * If {@code a} is {@code null}, this method returns 0. 4382 * 4383 * @param a the array whose hash value to compute 4384 * @return a content-based hash code for {@code a} 4385 * @since 1.5 4386 */ 4387 public static int hashCode(short[] a) { 4388 if (a == null) { 4389 return 0; 4390 } 4391 return ArraysSupport.hashCode(a, 0, a.length, 1); 4392 } 4393 4394 /** 4395 * Returns a hash code based on the contents of the specified array. 4396 * For any two {@code char} arrays {@code a} and {@code b} 4397 * such that {@code Arrays.equals(a, b)}, it is also the case that 4398 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}. 4399 * 4400 * <p>The value returned by this method is the same value that would be 4401 * obtained by invoking the {@link List#hashCode() hashCode} 4402 * method on a {@link List} containing a sequence of {@link Character} 4403 * instances representing the elements of {@code a} in the same order. 4404 * If {@code a} is {@code null}, this method returns 0. 4405 * 4406 * @param a the array whose hash value to compute 4407 * @return a content-based hash code for {@code a} 4408 * @since 1.5 4409 */ 4410 public static int hashCode(char[] a) { 4411 if (a == null) { 4412 return 0; 4413 } 4414 return ArraysSupport.hashCode(a, 0, a.length, 1); 4415 } 4416 4417 /** 4418 * Returns a hash code based on the contents of the specified array. 4419 * For any two {@code byte} arrays {@code a} and {@code b} 4420 * such that {@code Arrays.equals(a, b)}, it is also the case that 4421 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}. 4422 * 4423 * <p>The value returned by this method is the same value that would be 4424 * obtained by invoking the {@link List#hashCode() hashCode} 4425 * method on a {@link List} containing a sequence of {@link Byte} 4426 * instances representing the elements of {@code a} in the same order. 4427 * If {@code a} is {@code null}, this method returns 0. 4428 * 4429 * @param a the array whose hash value to compute 4430 * @return a content-based hash code for {@code a} 4431 * @since 1.5 4432 */ 4433 public static int hashCode(byte[] a) { 4434 if (a == null) { 4435 return 0; 4436 } 4437 return ArraysSupport.hashCode(a, 0, a.length, 1); 4438 } 4439 4440 /** 4441 * Returns a hash code based on the contents of the specified array. 4442 * For any two {@code boolean} arrays {@code a} and {@code b} 4443 * such that {@code Arrays.equals(a, b)}, it is also the case that 4444 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}. 4445 * 4446 * <p>The value returned by this method is the same value that would be 4447 * obtained by invoking the {@link List#hashCode() hashCode} 4448 * method on a {@link List} containing a sequence of {@link Boolean} 4449 * instances representing the elements of {@code a} in the same order. 4450 * If {@code a} is {@code null}, this method returns 0. 4451 * 4452 * @param a the array whose hash value to compute 4453 * @return a content-based hash code for {@code a} 4454 * @since 1.5 4455 */ 4456 public static int hashCode(boolean[] a) { 4457 if (a == null) 4458 return 0; 4459 4460 int result = 1; 4461 for (boolean element : a) 4462 result = 31 * result + Boolean.hashCode(element); 4463 4464 return result; 4465 } 4466 4467 /** 4468 * Returns a hash code based on the contents of the specified array. 4469 * For any two {@code float} arrays {@code a} and {@code b} 4470 * such that {@code Arrays.equals(a, b)}, it is also the case that 4471 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}. 4472 * 4473 * <p>The value returned by this method is the same value that would be 4474 * obtained by invoking the {@link List#hashCode() hashCode} 4475 * method on a {@link List} containing a sequence of {@link Float} 4476 * instances representing the elements of {@code a} in the same order. 4477 * If {@code a} is {@code null}, this method returns 0. 4478 * 4479 * @param a the array whose hash value to compute 4480 * @return a content-based hash code for {@code a} 4481 * @since 1.5 4482 */ 4483 public static int hashCode(float[] a) { 4484 if (a == null) 4485 return 0; 4486 4487 int result = 1; 4488 for (float element : a) 4489 result = 31 * result + Float.hashCode(element); 4490 4491 return result; 4492 } 4493 4494 /** 4495 * Returns a hash code based on the contents of the specified array. 4496 * For any two {@code double} arrays {@code a} and {@code b} 4497 * such that {@code Arrays.equals(a, b)}, it is also the case that 4498 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}. 4499 * 4500 * <p>The value returned by this method is the same value that would be 4501 * obtained by invoking the {@link List#hashCode() hashCode} 4502 * method on a {@link List} containing a sequence of {@link Double} 4503 * instances representing the elements of {@code a} in the same order. 4504 * If {@code a} is {@code null}, this method returns 0. 4505 * 4506 * @param a the array whose hash value to compute 4507 * @return a content-based hash code for {@code a} 4508 * @since 1.5 4509 */ 4510 public static int hashCode(double[] a) { 4511 if (a == null) 4512 return 0; 4513 4514 int result = 1; 4515 for (double element : a) { 4516 result = 31 * result + Double.hashCode(element); 4517 } 4518 return result; 4519 } 4520 4521 /** 4522 * Returns a hash code based on the contents of the specified array. If 4523 * the array contains other arrays as elements, the hash code is based on 4524 * their identities rather than their contents. It is therefore 4525 * acceptable to invoke this method on an array that contains itself as an 4526 * element, either directly or indirectly through one or more levels of 4527 * arrays. 4528 * 4529 * <p>For any two arrays {@code a} and {@code b} such that 4530 * {@code Arrays.equals(a, b)}, it is also the case that 4531 * {@code Arrays.hashCode(a) == Arrays.hashCode(b)}. 4532 * 4533 * <p>The value returned by this method is equal to the value that would 4534 * be returned by {@code Arrays.asList(a).hashCode()}, unless {@code a} 4535 * is {@code null}, in which case {@code 0} is returned. 4536 * 4537 * @param a the array whose content-based hash code to compute 4538 * @return a content-based hash code for {@code a} 4539 * @see #deepHashCode(Object[]) 4540 * @since 1.5 4541 */ 4542 public static int hashCode(Object[] a) { 4543 if (a == null) { 4544 return 0; 4545 } 4546 return ArraysSupport.hashCode(a, 0, a.length, 1); 4547 } 4548 4549 /** 4550 * Returns a hash code based on the "deep contents" of the specified 4551 * array. If the array contains other arrays as elements, the 4552 * hash code is based on their contents and so on, ad infinitum. 4553 * It is therefore unacceptable to invoke this method on an array that 4554 * contains itself as an element, either directly or indirectly through 4555 * one or more levels of arrays. The behavior of such an invocation is 4556 * undefined. 4557 * 4558 * <p>For any two arrays {@code a} and {@code b} such that 4559 * {@code Arrays.deepEquals(a, b)}, it is also the case that 4560 * {@code Arrays.deepHashCode(a) == Arrays.deepHashCode(b)}. 4561 * 4562 * <p>The computation of the value returned by this method is similar to 4563 * that of the value returned by {@link List#hashCode()} on a list 4564 * containing the same elements as {@code a} in the same order, with one 4565 * difference: If an element {@code e} of {@code a} is itself an array, 4566 * its hash code is computed not by calling {@code e.hashCode()}, but as 4567 * by calling the appropriate overloading of {@code Arrays.hashCode(e)} 4568 * if {@code e} is an array of a primitive type, or as by calling 4569 * {@code Arrays.deepHashCode(e)} recursively if {@code e} is an array 4570 * of a reference type. If {@code a} is {@code null}, this method 4571 * returns 0. 4572 * 4573 * @param a the array whose deep-content-based hash code to compute 4574 * @return a deep-content-based hash code for {@code a} 4575 * @see #hashCode(Object[]) 4576 * @since 1.5 4577 */ 4578 public static int deepHashCode(Object[] a) { 4579 if (a == null) 4580 return 0; 4581 4582 int result = 1; 4583 4584 for (Object element : a) { 4585 final int elementHash; 4586 final Class<?> cl; 4587 if (element == null) 4588 elementHash = 0; 4589 else if ((cl = element.getClass().getComponentType()) == null) 4590 elementHash = element.hashCode(); 4591 else if (element instanceof Object[]) 4592 elementHash = deepHashCode((Object[]) element); 4593 else 4594 elementHash = primitiveArrayHashCode(element, cl); 4595 4596 result = 31 * result + elementHash; 4597 } 4598 4599 return result; 4600 } 4601 4602 private static int primitiveArrayHashCode(Object a, Class<?> cl) { 4603 return 4604 (cl == byte.class) ? hashCode((byte[]) a) : 4605 (cl == int.class) ? hashCode((int[]) a) : 4606 (cl == long.class) ? hashCode((long[]) a) : 4607 (cl == char.class) ? hashCode((char[]) a) : 4608 (cl == short.class) ? hashCode((short[]) a) : 4609 (cl == boolean.class) ? hashCode((boolean[]) a) : 4610 (cl == double.class) ? hashCode((double[]) a) : 4611 // If new primitive types are ever added, this method must be 4612 // expanded or we will fail here with ClassCastException. 4613 hashCode((float[]) a); 4614 } 4615 4616 /** 4617 * Returns {@code true} if the two specified arrays are <i>deeply 4618 * equal</i> to one another. Unlike the {@link #equals(Object[],Object[])} 4619 * method, this method is appropriate for use with nested arrays of 4620 * arbitrary depth. 4621 * 4622 * <p>Two array references are considered deeply equal if both 4623 * are {@code null}, or if they refer to arrays that contain the same 4624 * number of elements and all corresponding pairs of elements in the two 4625 * arrays are deeply equal. 4626 * 4627 * <p>Two possibly {@code null} elements {@code e1} and {@code e2} are 4628 * deeply equal if any of the following conditions hold: 4629 * <ul> 4630 * <li> {@code e1} and {@code e2} are both arrays of object reference 4631 * types, and {@code Arrays.deepEquals(e1, e2) would return true} 4632 * <li> {@code e1} and {@code e2} are arrays of the same primitive 4633 * type, and the appropriate overloading of 4634 * {@code Arrays.equals(e1, e2)} would return true. 4635 * <li> {@code e1 == e2} 4636 * <li> {@code e1.equals(e2)} would return true. 4637 * </ul> 4638 * Note that this definition permits {@code null} elements at any depth. 4639 * 4640 * <p>If either of the specified arrays contain themselves as elements 4641 * either directly or indirectly through one or more levels of arrays, 4642 * the behavior of this method is undefined. 4643 * 4644 * @param a1 one array to be tested for equality 4645 * @param a2 the other array to be tested for equality 4646 * @return {@code true} if the two arrays are equal 4647 * @see #equals(Object[],Object[]) 4648 * @see Objects#deepEquals(Object, Object) 4649 * @since 1.5 4650 */ 4651 public static boolean deepEquals(Object[] a1, Object[] a2) { 4652 if (a1 == a2) 4653 return true; 4654 if (a1 == null || a2==null) 4655 return false; 4656 int length = a1.length; 4657 if (a2.length != length) 4658 return false; 4659 4660 for (int i = 0; i < length; i++) { 4661 Object e1 = a1[i]; 4662 Object e2 = a2[i]; 4663 4664 if (e1 == e2) 4665 continue; 4666 if (e1 == null) 4667 return false; 4668 4669 // Figure out whether the two elements are equal 4670 boolean eq = deepEquals0(e1, e2); 4671 4672 if (!eq) 4673 return false; 4674 } 4675 return true; 4676 } 4677 4678 static boolean deepEquals0(Object e1, Object e2) { 4679 assert e1 != null; 4680 boolean eq; 4681 if (e1 instanceof Object[] && e2 instanceof Object[]) 4682 eq = deepEquals ((Object[]) e1, (Object[]) e2); 4683 else if (e1 instanceof byte[] && e2 instanceof byte[]) 4684 eq = equals((byte[]) e1, (byte[]) e2); 4685 else if (e1 instanceof short[] && e2 instanceof short[]) 4686 eq = equals((short[]) e1, (short[]) e2); 4687 else if (e1 instanceof int[] && e2 instanceof int[]) 4688 eq = equals((int[]) e1, (int[]) e2); 4689 else if (e1 instanceof long[] && e2 instanceof long[]) 4690 eq = equals((long[]) e1, (long[]) e2); 4691 else if (e1 instanceof char[] && e2 instanceof char[]) 4692 eq = equals((char[]) e1, (char[]) e2); 4693 else if (e1 instanceof float[] && e2 instanceof float[]) 4694 eq = equals((float[]) e1, (float[]) e2); 4695 else if (e1 instanceof double[] && e2 instanceof double[]) 4696 eq = equals((double[]) e1, (double[]) e2); 4697 else if (e1 instanceof boolean[] && e2 instanceof boolean[]) 4698 eq = equals((boolean[]) e1, (boolean[]) e2); 4699 else 4700 eq = e1.equals(e2); 4701 return eq; 4702 } 4703 4704 /** 4705 * Returns a string representation of the contents of the specified array. 4706 * The string representation consists of a list of the array's elements, 4707 * enclosed in square brackets ({@code "[]"}). Adjacent elements are 4708 * separated by the characters {@code ", "} (a comma followed by a 4709 * space). Elements are converted to strings as by 4710 * {@code String.valueOf(long)}. Returns {@code "null"} if {@code a} 4711 * is {@code null}. 4712 * 4713 * @param a the array whose string representation to return 4714 * @return a string representation of {@code a} 4715 * @since 1.5 4716 */ 4717 public static String toString(long[] a) { 4718 if (a == null) 4719 return "null"; 4720 int iMax = a.length - 1; 4721 if (iMax == -1) 4722 return "[]"; 4723 4724 StringBuilder b = new StringBuilder(); 4725 b.append('['); 4726 for (int i = 0; ; i++) { 4727 b.append(a[i]); 4728 if (i == iMax) 4729 return b.append(']').toString(); 4730 b.append(", "); 4731 } 4732 } 4733 4734 /** 4735 * Returns a string representation of the contents of the specified array. 4736 * The string representation consists of a list of the array's elements, 4737 * enclosed in square brackets ({@code "[]"}). Adjacent elements are 4738 * separated by the characters {@code ", "} (a comma followed by a 4739 * space). Elements are converted to strings as by 4740 * {@code String.valueOf(int)}. Returns {@code "null"} if {@code a} is 4741 * {@code null}. 4742 * 4743 * @param a the array whose string representation to return 4744 * @return a string representation of {@code a} 4745 * @since 1.5 4746 */ 4747 public static String toString(int[] a) { 4748 if (a == null) 4749 return "null"; 4750 int iMax = a.length - 1; 4751 if (iMax == -1) 4752 return "[]"; 4753 4754 StringBuilder b = new StringBuilder(); 4755 b.append('['); 4756 for (int i = 0; ; i++) { 4757 b.append(a[i]); 4758 if (i == iMax) 4759 return b.append(']').toString(); 4760 b.append(", "); 4761 } 4762 } 4763 4764 /** 4765 * Returns a string representation of the contents of the specified array. 4766 * The string representation consists of a list of the array's elements, 4767 * enclosed in square brackets ({@code "[]"}). Adjacent elements are 4768 * separated by the characters {@code ", "} (a comma followed by a 4769 * space). Elements are converted to strings as by 4770 * {@code String.valueOf(short)}. Returns {@code "null"} if {@code a} 4771 * is {@code null}. 4772 * 4773 * @param a the array whose string representation to return 4774 * @return a string representation of {@code a} 4775 * @since 1.5 4776 */ 4777 public static String toString(short[] a) { 4778 if (a == null) 4779 return "null"; 4780 int iMax = a.length - 1; 4781 if (iMax == -1) 4782 return "[]"; 4783 4784 StringBuilder b = new StringBuilder(); 4785 b.append('['); 4786 for (int i = 0; ; i++) { 4787 b.append(a[i]); 4788 if (i == iMax) 4789 return b.append(']').toString(); 4790 b.append(", "); 4791 } 4792 } 4793 4794 /** 4795 * Returns a string representation of the contents of the specified array. 4796 * The string representation consists of a list of the array's elements, 4797 * enclosed in square brackets ({@code "[]"}). Adjacent elements are 4798 * separated by the characters {@code ", "} (a comma followed by a 4799 * space). Elements are converted to strings as by 4800 * {@code String.valueOf(char)}. Returns {@code "null"} if {@code a} 4801 * is {@code null}. 4802 * 4803 * @param a the array whose string representation to return 4804 * @return a string representation of {@code a} 4805 * @since 1.5 4806 */ 4807 public static String toString(char[] a) { 4808 if (a == null) 4809 return "null"; 4810 int iMax = a.length - 1; 4811 if (iMax == -1) 4812 return "[]"; 4813 4814 StringBuilder b = new StringBuilder(); 4815 b.append('['); 4816 for (int i = 0; ; i++) { 4817 b.append(a[i]); 4818 if (i == iMax) 4819 return b.append(']').toString(); 4820 b.append(", "); 4821 } 4822 } 4823 4824 /** 4825 * Returns a string representation of the contents of the specified array. 4826 * The string representation consists of a list of the array's elements, 4827 * enclosed in square brackets ({@code "[]"}). Adjacent elements 4828 * are separated by the characters {@code ", "} (a comma followed 4829 * by a space). Elements are converted to strings as by 4830 * {@code String.valueOf(byte)}. Returns {@code "null"} if 4831 * {@code a} is {@code null}. 4832 * 4833 * @param a the array whose string representation to return 4834 * @return a string representation of {@code a} 4835 * @since 1.5 4836 */ 4837 public static String toString(byte[] a) { 4838 if (a == null) 4839 return "null"; 4840 int iMax = a.length - 1; 4841 if (iMax == -1) 4842 return "[]"; 4843 4844 StringBuilder b = new StringBuilder(); 4845 b.append('['); 4846 for (int i = 0; ; i++) { 4847 b.append(a[i]); 4848 if (i == iMax) 4849 return b.append(']').toString(); 4850 b.append(", "); 4851 } 4852 } 4853 4854 /** 4855 * Returns a string representation of the contents of the specified array. 4856 * The string representation consists of a list of the array's elements, 4857 * enclosed in square brackets ({@code "[]"}). Adjacent elements are 4858 * separated by the characters {@code ", "} (a comma followed by a 4859 * space). Elements are converted to strings as by 4860 * {@code String.valueOf(boolean)}. Returns {@code "null"} if 4861 * {@code a} is {@code null}. 4862 * 4863 * @param a the array whose string representation to return 4864 * @return a string representation of {@code a} 4865 * @since 1.5 4866 */ 4867 public static String toString(boolean[] a) { 4868 if (a == null) 4869 return "null"; 4870 int iMax = a.length - 1; 4871 if (iMax == -1) 4872 return "[]"; 4873 4874 StringBuilder b = new StringBuilder(); 4875 b.append('['); 4876 for (int i = 0; ; i++) { 4877 b.append(a[i]); 4878 if (i == iMax) 4879 return b.append(']').toString(); 4880 b.append(", "); 4881 } 4882 } 4883 4884 /** 4885 * Returns a string representation of the contents of the specified array. 4886 * The string representation consists of a list of the array's elements, 4887 * enclosed in square brackets ({@code "[]"}). Adjacent elements are 4888 * separated by the characters {@code ", "} (a comma followed by a 4889 * space). Elements are converted to strings as by 4890 * {@code String.valueOf(float)}. Returns {@code "null"} if {@code a} 4891 * is {@code null}. 4892 * 4893 * @param a the array whose string representation to return 4894 * @return a string representation of {@code a} 4895 * @since 1.5 4896 */ 4897 public static String toString(float[] a) { 4898 if (a == null) 4899 return "null"; 4900 4901 int iMax = a.length - 1; 4902 if (iMax == -1) 4903 return "[]"; 4904 4905 StringBuilder b = new StringBuilder(); 4906 b.append('['); 4907 for (int i = 0; ; i++) { 4908 b.append(a[i]); 4909 if (i == iMax) 4910 return b.append(']').toString(); 4911 b.append(", "); 4912 } 4913 } 4914 4915 /** 4916 * Returns a string representation of the contents of the specified array. 4917 * The string representation consists of a list of the array's elements, 4918 * enclosed in square brackets ({@code "[]"}). Adjacent elements are 4919 * separated by the characters {@code ", "} (a comma followed by a 4920 * space). Elements are converted to strings as by 4921 * {@code String.valueOf(double)}. Returns {@code "null"} if {@code a} 4922 * is {@code null}. 4923 * 4924 * @param a the array whose string representation to return 4925 * @return a string representation of {@code a} 4926 * @since 1.5 4927 */ 4928 public static String toString(double[] a) { 4929 if (a == null) 4930 return "null"; 4931 int iMax = a.length - 1; 4932 if (iMax == -1) 4933 return "[]"; 4934 4935 StringBuilder b = new StringBuilder(); 4936 b.append('['); 4937 for (int i = 0; ; i++) { 4938 b.append(a[i]); 4939 if (i == iMax) 4940 return b.append(']').toString(); 4941 b.append(", "); 4942 } 4943 } 4944 4945 /** 4946 * Returns a string representation of the contents of the specified array. 4947 * If the array contains other arrays as elements, they are converted to 4948 * strings by the {@link Object#toString} method inherited from 4949 * {@code Object}, which describes their <i>identities</i> rather than 4950 * their contents. 4951 * 4952 * <p>The value returned by this method is equal to the value that would 4953 * be returned by {@code Arrays.asList(a).toString()}, unless {@code a} 4954 * is {@code null}, in which case {@code "null"} is returned. 4955 * 4956 * @param a the array whose string representation to return 4957 * @return a string representation of {@code a} 4958 * @see #deepToString(Object[]) 4959 * @since 1.5 4960 */ 4961 public static String toString(Object[] a) { 4962 if (a == null) 4963 return "null"; 4964 4965 int iMax = a.length - 1; 4966 if (iMax == -1) 4967 return "[]"; 4968 4969 StringBuilder b = new StringBuilder(); 4970 b.append('['); 4971 for (int i = 0; ; i++) { 4972 b.append(String.valueOf(a[i])); 4973 if (i == iMax) 4974 return b.append(']').toString(); 4975 b.append(", "); 4976 } 4977 } 4978 4979 /** 4980 * Returns a string representation of the "deep contents" of the specified 4981 * array. If the array contains other arrays as elements, the string 4982 * representation contains their contents and so on. This method is 4983 * designed for converting multidimensional arrays to strings. 4984 * 4985 * <p>The string representation consists of a list of the array's 4986 * elements, enclosed in square brackets ({@code "[]"}). Adjacent 4987 * elements are separated by the characters {@code ", "} (a comma 4988 * followed by a space). Elements are converted to strings as by 4989 * {@code String.valueOf(Object)}, unless they are themselves 4990 * arrays. 4991 * 4992 * <p>If an element {@code e} is an array of a primitive type, it is 4993 * converted to a string as by invoking the appropriate overloading of 4994 * {@code Arrays.toString(e)}. If an element {@code e} is an array of a 4995 * reference type, it is converted to a string as by invoking 4996 * this method recursively. 4997 * 4998 * <p>To avoid infinite recursion, if the specified array contains itself 4999 * as an element, or contains an indirect reference to itself through one 5000 * or more levels of arrays, the self-reference is converted to the string 5001 * {@code "[...]"}. For example, an array containing only a reference 5002 * to itself would be rendered as {@code "[[...]]"}. 5003 * 5004 * <p>This method returns {@code "null"} if the specified array 5005 * is {@code null}. 5006 * 5007 * @param a the array whose string representation to return 5008 * @return a string representation of {@code a} 5009 * @see #toString(Object[]) 5010 * @since 1.5 5011 */ 5012 public static String deepToString(Object[] a) { 5013 if (a == null) 5014 return "null"; 5015 5016 int bufLen = 20 * a.length; 5017 if (a.length != 0 && bufLen <= 0) 5018 bufLen = Integer.MAX_VALUE; 5019 StringBuilder buf = new StringBuilder(bufLen); 5020 deepToString(a, buf, new HashSet<>()); 5021 return buf.toString(); 5022 } 5023 5024 private static void deepToString(Object[] a, StringBuilder buf, 5025 Set<Object[]> dejaVu) { 5026 if (a == null) { 5027 buf.append("null"); 5028 return; 5029 } 5030 int iMax = a.length - 1; 5031 if (iMax == -1) { 5032 buf.append("[]"); 5033 return; 5034 } 5035 5036 dejaVu.add(a); 5037 buf.append('['); 5038 for (int i = 0; ; i++) { 5039 5040 Object element = a[i]; 5041 if (element == null) { 5042 buf.append("null"); 5043 } else { 5044 Class<?> eClass = element.getClass(); 5045 5046 if (eClass.isArray()) { 5047 if (eClass == byte[].class) 5048 buf.append(toString((byte[]) element)); 5049 else if (eClass == short[].class) 5050 buf.append(toString((short[]) element)); 5051 else if (eClass == int[].class) 5052 buf.append(toString((int[]) element)); 5053 else if (eClass == long[].class) 5054 buf.append(toString((long[]) element)); 5055 else if (eClass == char[].class) 5056 buf.append(toString((char[]) element)); 5057 else if (eClass == float[].class) 5058 buf.append(toString((float[]) element)); 5059 else if (eClass == double[].class) 5060 buf.append(toString((double[]) element)); 5061 else if (eClass == boolean[].class) 5062 buf.append(toString((boolean[]) element)); 5063 else { // element is an array of object references 5064 if (dejaVu.contains(element)) 5065 buf.append("[...]"); 5066 else 5067 deepToString((Object[])element, buf, dejaVu); 5068 } 5069 } else { // element is non-null and not an array 5070 buf.append(element.toString()); 5071 } 5072 } 5073 if (i == iMax) 5074 break; 5075 buf.append(", "); 5076 } 5077 buf.append(']'); 5078 dejaVu.remove(a); 5079 } 5080 5081 5082 /** 5083 * Set all elements of the specified array, using the provided 5084 * generator function to compute each element. 5085 * 5086 * <p>If the generator function throws an exception, it is relayed to 5087 * the caller and the array is left in an indeterminate state. 5088 * 5089 * @apiNote 5090 * Setting a subrange of an array, using a generator function to compute 5091 * each element, can be written as follows: 5092 * <pre>{@code 5093 * IntStream.range(startInclusive, endExclusive) 5094 * .forEach(i -> array[i] = generator.apply(i)); 5095 * }</pre> 5096 * 5097 * @param <T> type of elements of the array 5098 * @param array array to be initialized 5099 * @param generator a function accepting an index and producing the desired 5100 * value for that position 5101 * @throws NullPointerException if the generator is null 5102 * @since 1.8 5103 */ 5104 public static <T> void setAll(T[] array, IntFunction<? extends T> generator) { 5105 Objects.requireNonNull(generator); 5106 for (int i = 0; i < array.length; i++) 5107 array[i] = generator.apply(i); 5108 } 5109 5110 /** 5111 * Set all elements of the specified array, in parallel, using the 5112 * provided generator function to compute each element. 5113 * 5114 * <p>If the generator function throws an exception, an unchecked exception 5115 * is thrown from {@code parallelSetAll} and the array is left in an 5116 * indeterminate state. 5117 * 5118 * @apiNote 5119 * Setting a subrange of an array, in parallel, using a generator function 5120 * to compute each element, can be written as follows: 5121 * <pre>{@code 5122 * IntStream.range(startInclusive, endExclusive) 5123 * .parallel() 5124 * .forEach(i -> array[i] = generator.apply(i)); 5125 * }</pre> 5126 * 5127 * @param <T> type of elements of the array 5128 * @param array array to be initialized 5129 * @param generator a function accepting an index and producing the desired 5130 * value for that position 5131 * @throws NullPointerException if the generator is null 5132 * @since 1.8 5133 */ 5134 public static <T> void parallelSetAll(T[] array, IntFunction<? extends T> generator) { 5135 Objects.requireNonNull(generator); 5136 IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.apply(i); }); 5137 } 5138 5139 /** 5140 * Set all elements of the specified array, using the provided 5141 * generator function to compute each element. 5142 * 5143 * <p>If the generator function throws an exception, it is relayed to 5144 * the caller and the array is left in an indeterminate state. 5145 * 5146 * @apiNote 5147 * Setting a subrange of an array, using a generator function to compute 5148 * each element, can be written as follows: 5149 * <pre>{@code 5150 * IntStream.range(startInclusive, endExclusive) 5151 * .forEach(i -> array[i] = generator.applyAsInt(i)); 5152 * }</pre> 5153 * 5154 * @param array array to be initialized 5155 * @param generator a function accepting an index and producing the desired 5156 * value for that position 5157 * @throws NullPointerException if the generator is null 5158 * @since 1.8 5159 */ 5160 public static void setAll(int[] array, IntUnaryOperator generator) { 5161 Objects.requireNonNull(generator); 5162 for (int i = 0; i < array.length; i++) 5163 array[i] = generator.applyAsInt(i); 5164 } 5165 5166 /** 5167 * Set all elements of the specified array, in parallel, using the 5168 * provided generator function to compute each element. 5169 * 5170 * <p>If the generator function throws an exception, an unchecked exception 5171 * is thrown from {@code parallelSetAll} and the array is left in an 5172 * indeterminate state. 5173 * 5174 * @apiNote 5175 * Setting a subrange of an array, in parallel, using a generator function 5176 * to compute each element, can be written as follows: 5177 * <pre>{@code 5178 * IntStream.range(startInclusive, endExclusive) 5179 * .parallel() 5180 * .forEach(i -> array[i] = generator.applyAsInt(i)); 5181 * }</pre> 5182 * 5183 * @param array array to be initialized 5184 * @param generator a function accepting an index and producing the desired 5185 * value for that position 5186 * @throws NullPointerException if the generator is null 5187 * @since 1.8 5188 */ 5189 public static void parallelSetAll(int[] array, IntUnaryOperator generator) { 5190 Objects.requireNonNull(generator); 5191 IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsInt(i); }); 5192 } 5193 5194 /** 5195 * Set all elements of the specified array, using the provided 5196 * generator function to compute each element. 5197 * 5198 * <p>If the generator function throws an exception, it is relayed to 5199 * the caller and the array is left in an indeterminate state. 5200 * 5201 * @apiNote 5202 * Setting a subrange of an array, using a generator function to compute 5203 * each element, can be written as follows: 5204 * <pre>{@code 5205 * IntStream.range(startInclusive, endExclusive) 5206 * .forEach(i -> array[i] = generator.applyAsLong(i)); 5207 * }</pre> 5208 * 5209 * @param array array to be initialized 5210 * @param generator a function accepting an index and producing the desired 5211 * value for that position 5212 * @throws NullPointerException if the generator is null 5213 * @since 1.8 5214 */ 5215 public static void setAll(long[] array, IntToLongFunction generator) { 5216 Objects.requireNonNull(generator); 5217 for (int i = 0; i < array.length; i++) 5218 array[i] = generator.applyAsLong(i); 5219 } 5220 5221 /** 5222 * Set all elements of the specified array, in parallel, using the 5223 * provided generator function to compute each element. 5224 * 5225 * <p>If the generator function throws an exception, an unchecked exception 5226 * is thrown from {@code parallelSetAll} and the array is left in an 5227 * indeterminate state. 5228 * 5229 * @apiNote 5230 * Setting a subrange of an array, in parallel, using a generator function 5231 * to compute each element, can be written as follows: 5232 * <pre>{@code 5233 * IntStream.range(startInclusive, endExclusive) 5234 * .parallel() 5235 * .forEach(i -> array[i] = generator.applyAsLong(i)); 5236 * }</pre> 5237 * 5238 * @param array array to be initialized 5239 * @param generator a function accepting an index and producing the desired 5240 * value for that position 5241 * @throws NullPointerException if the generator is null 5242 * @since 1.8 5243 */ 5244 public static void parallelSetAll(long[] array, IntToLongFunction generator) { 5245 Objects.requireNonNull(generator); 5246 IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsLong(i); }); 5247 } 5248 5249 /** 5250 * Set all elements of the specified array, using the provided 5251 * generator function to compute each element. 5252 * 5253 * <p>If the generator function throws an exception, it is relayed to 5254 * the caller and the array is left in an indeterminate state. 5255 * 5256 * @apiNote 5257 * Setting a subrange of an array, using a generator function to compute 5258 * each element, can be written as follows: 5259 * <pre>{@code 5260 * IntStream.range(startInclusive, endExclusive) 5261 * .forEach(i -> array[i] = generator.applyAsDouble(i)); 5262 * }</pre> 5263 * 5264 * @param array array to be initialized 5265 * @param generator a function accepting an index and producing the desired 5266 * value for that position 5267 * @throws NullPointerException if the generator is null 5268 * @since 1.8 5269 */ 5270 public static void setAll(double[] array, IntToDoubleFunction generator) { 5271 Objects.requireNonNull(generator); 5272 for (int i = 0; i < array.length; i++) 5273 array[i] = generator.applyAsDouble(i); 5274 } 5275 5276 /** 5277 * Set all elements of the specified array, in parallel, using the 5278 * provided generator function to compute each element. 5279 * 5280 * <p>If the generator function throws an exception, an unchecked exception 5281 * is thrown from {@code parallelSetAll} and the array is left in an 5282 * indeterminate state. 5283 * 5284 * @apiNote 5285 * Setting a subrange of an array, in parallel, using a generator function 5286 * to compute each element, can be written as follows: 5287 * <pre>{@code 5288 * IntStream.range(startInclusive, endExclusive) 5289 * .parallel() 5290 * .forEach(i -> array[i] = generator.applyAsDouble(i)); 5291 * }</pre> 5292 * 5293 * @param array array to be initialized 5294 * @param generator a function accepting an index and producing the desired 5295 * value for that position 5296 * @throws NullPointerException if the generator is null 5297 * @since 1.8 5298 */ 5299 public static void parallelSetAll(double[] array, IntToDoubleFunction generator) { 5300 Objects.requireNonNull(generator); 5301 IntStream.range(0, array.length).parallel().forEach(i -> { array[i] = generator.applyAsDouble(i); }); 5302 } 5303 5304 /** 5305 * Returns a {@link Spliterator} covering all of the specified array. 5306 * 5307 * <p>The spliterator reports {@link Spliterator#SIZED}, 5308 * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and 5309 * {@link Spliterator#IMMUTABLE}. 5310 * 5311 * @param <T> type of elements 5312 * @param array the array, assumed to be unmodified during use 5313 * @return a spliterator for the array elements 5314 * @since 1.8 5315 */ 5316 public static <T> Spliterator<T> spliterator(T[] array) { 5317 return Spliterators.spliterator(array, 5318 Spliterator.ORDERED | Spliterator.IMMUTABLE); 5319 } 5320 5321 /** 5322 * Returns a {@link Spliterator} covering the specified range of the 5323 * specified array. 5324 * 5325 * <p>The spliterator reports {@link Spliterator#SIZED}, 5326 * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and 5327 * {@link Spliterator#IMMUTABLE}. 5328 * 5329 * @param <T> type of elements 5330 * @param array the array, assumed to be unmodified during use 5331 * @param startInclusive the first index to cover, inclusive 5332 * @param endExclusive index immediately past the last index to cover 5333 * @return a spliterator for the array elements 5334 * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is 5335 * negative, {@code endExclusive} is less than 5336 * {@code startInclusive}, or {@code endExclusive} is greater than 5337 * the array size 5338 * @since 1.8 5339 */ 5340 public static <T> Spliterator<T> spliterator(T[] array, int startInclusive, int endExclusive) { 5341 return Spliterators.spliterator(array, startInclusive, endExclusive, 5342 Spliterator.ORDERED | Spliterator.IMMUTABLE); 5343 } 5344 5345 /** 5346 * Returns a {@link Spliterator.OfInt} covering all of the specified array. 5347 * 5348 * <p>The spliterator reports {@link Spliterator#SIZED}, 5349 * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and 5350 * {@link Spliterator#IMMUTABLE}. 5351 * 5352 * @param array the array, assumed to be unmodified during use 5353 * @return a spliterator for the array elements 5354 * @since 1.8 5355 */ 5356 public static Spliterator.OfInt spliterator(int[] array) { 5357 return Spliterators.spliterator(array, 5358 Spliterator.ORDERED | Spliterator.IMMUTABLE); 5359 } 5360 5361 /** 5362 * Returns a {@link Spliterator.OfInt} covering the specified range of the 5363 * specified array. 5364 * 5365 * <p>The spliterator reports {@link Spliterator#SIZED}, 5366 * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and 5367 * {@link Spliterator#IMMUTABLE}. 5368 * 5369 * @param array the array, assumed to be unmodified during use 5370 * @param startInclusive the first index to cover, inclusive 5371 * @param endExclusive index immediately past the last index to cover 5372 * @return a spliterator for the array elements 5373 * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is 5374 * negative, {@code endExclusive} is less than 5375 * {@code startInclusive}, or {@code endExclusive} is greater than 5376 * the array size 5377 * @since 1.8 5378 */ 5379 public static Spliterator.OfInt spliterator(int[] array, int startInclusive, int endExclusive) { 5380 return Spliterators.spliterator(array, startInclusive, endExclusive, 5381 Spliterator.ORDERED | Spliterator.IMMUTABLE); 5382 } 5383 5384 /** 5385 * Returns a {@link Spliterator.OfLong} covering all of the specified array. 5386 * 5387 * <p>The spliterator reports {@link Spliterator#SIZED}, 5388 * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and 5389 * {@link Spliterator#IMMUTABLE}. 5390 * 5391 * @param array the array, assumed to be unmodified during use 5392 * @return the spliterator for the array elements 5393 * @since 1.8 5394 */ 5395 public static Spliterator.OfLong spliterator(long[] array) { 5396 return Spliterators.spliterator(array, 5397 Spliterator.ORDERED | Spliterator.IMMUTABLE); 5398 } 5399 5400 /** 5401 * Returns a {@link Spliterator.OfLong} covering the specified range of the 5402 * specified array. 5403 * 5404 * <p>The spliterator reports {@link Spliterator#SIZED}, 5405 * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and 5406 * {@link Spliterator#IMMUTABLE}. 5407 * 5408 * @param array the array, assumed to be unmodified during use 5409 * @param startInclusive the first index to cover, inclusive 5410 * @param endExclusive index immediately past the last index to cover 5411 * @return a spliterator for the array elements 5412 * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is 5413 * negative, {@code endExclusive} is less than 5414 * {@code startInclusive}, or {@code endExclusive} is greater than 5415 * the array size 5416 * @since 1.8 5417 */ 5418 public static Spliterator.OfLong spliterator(long[] array, int startInclusive, int endExclusive) { 5419 return Spliterators.spliterator(array, startInclusive, endExclusive, 5420 Spliterator.ORDERED | Spliterator.IMMUTABLE); 5421 } 5422 5423 /** 5424 * Returns a {@link Spliterator.OfDouble} covering all of the specified 5425 * array. 5426 * 5427 * <p>The spliterator reports {@link Spliterator#SIZED}, 5428 * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and 5429 * {@link Spliterator#IMMUTABLE}. 5430 * 5431 * @param array the array, assumed to be unmodified during use 5432 * @return a spliterator for the array elements 5433 * @since 1.8 5434 */ 5435 public static Spliterator.OfDouble spliterator(double[] array) { 5436 return Spliterators.spliterator(array, 5437 Spliterator.ORDERED | Spliterator.IMMUTABLE); 5438 } 5439 5440 /** 5441 * Returns a {@link Spliterator.OfDouble} covering the specified range of 5442 * the specified array. 5443 * 5444 * <p>The spliterator reports {@link Spliterator#SIZED}, 5445 * {@link Spliterator#SUBSIZED}, {@link Spliterator#ORDERED}, and 5446 * {@link Spliterator#IMMUTABLE}. 5447 * 5448 * @param array the array, assumed to be unmodified during use 5449 * @param startInclusive the first index to cover, inclusive 5450 * @param endExclusive index immediately past the last index to cover 5451 * @return a spliterator for the array elements 5452 * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is 5453 * negative, {@code endExclusive} is less than 5454 * {@code startInclusive}, or {@code endExclusive} is greater than 5455 * the array size 5456 * @since 1.8 5457 */ 5458 public static Spliterator.OfDouble spliterator(double[] array, int startInclusive, int endExclusive) { 5459 return Spliterators.spliterator(array, startInclusive, endExclusive, 5460 Spliterator.ORDERED | Spliterator.IMMUTABLE); 5461 } 5462 5463 /** 5464 * Returns a sequential {@link Stream} with the specified array as its 5465 * source. 5466 * 5467 * @param <T> The type of the array elements 5468 * @param array The array, assumed to be unmodified during use 5469 * @return a {@code Stream} for the array 5470 * @since 1.8 5471 */ 5472 public static <T> Stream<T> stream(T[] array) { 5473 return stream(array, 0, array.length); 5474 } 5475 5476 /** 5477 * Returns a sequential {@link Stream} with the specified range of the 5478 * specified array as its source. 5479 * 5480 * @param <T> the type of the array elements 5481 * @param array the array, assumed to be unmodified during use 5482 * @param startInclusive the first index to cover, inclusive 5483 * @param endExclusive index immediately past the last index to cover 5484 * @return a {@code Stream} for the array range 5485 * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is 5486 * negative, {@code endExclusive} is less than 5487 * {@code startInclusive}, or {@code endExclusive} is greater than 5488 * the array size 5489 * @since 1.8 5490 */ 5491 public static <T> Stream<T> stream(T[] array, int startInclusive, int endExclusive) { 5492 return StreamSupport.stream(spliterator(array, startInclusive, endExclusive), false); 5493 } 5494 5495 /** 5496 * Returns a sequential {@link IntStream} with the specified array as its 5497 * source. 5498 * 5499 * @param array the array, assumed to be unmodified during use 5500 * @return an {@code IntStream} for the array 5501 * @since 1.8 5502 */ 5503 public static IntStream stream(int[] array) { 5504 return stream(array, 0, array.length); 5505 } 5506 5507 /** 5508 * Returns a sequential {@link IntStream} with the specified range of the 5509 * specified array as its source. 5510 * 5511 * @param array the array, assumed to be unmodified during use 5512 * @param startInclusive the first index to cover, inclusive 5513 * @param endExclusive index immediately past the last index to cover 5514 * @return an {@code IntStream} for the array range 5515 * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is 5516 * negative, {@code endExclusive} is less than 5517 * {@code startInclusive}, or {@code endExclusive} is greater than 5518 * the array size 5519 * @since 1.8 5520 */ 5521 public static IntStream stream(int[] array, int startInclusive, int endExclusive) { 5522 return StreamSupport.intStream(spliterator(array, startInclusive, endExclusive), false); 5523 } 5524 5525 /** 5526 * Returns a sequential {@link LongStream} with the specified array as its 5527 * source. 5528 * 5529 * @param array the array, assumed to be unmodified during use 5530 * @return a {@code LongStream} for the array 5531 * @since 1.8 5532 */ 5533 public static LongStream stream(long[] array) { 5534 return stream(array, 0, array.length); 5535 } 5536 5537 /** 5538 * Returns a sequential {@link LongStream} with the specified range of the 5539 * specified array as its source. 5540 * 5541 * @param array the array, assumed to be unmodified during use 5542 * @param startInclusive the first index to cover, inclusive 5543 * @param endExclusive index immediately past the last index to cover 5544 * @return a {@code LongStream} for the array range 5545 * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is 5546 * negative, {@code endExclusive} is less than 5547 * {@code startInclusive}, or {@code endExclusive} is greater than 5548 * the array size 5549 * @since 1.8 5550 */ 5551 public static LongStream stream(long[] array, int startInclusive, int endExclusive) { 5552 return StreamSupport.longStream(spliterator(array, startInclusive, endExclusive), false); 5553 } 5554 5555 /** 5556 * Returns a sequential {@link DoubleStream} with the specified array as its 5557 * source. 5558 * 5559 * @param array the array, assumed to be unmodified during use 5560 * @return a {@code DoubleStream} for the array 5561 * @since 1.8 5562 */ 5563 public static DoubleStream stream(double[] array) { 5564 return stream(array, 0, array.length); 5565 } 5566 5567 /** 5568 * Returns a sequential {@link DoubleStream} with the specified range of the 5569 * specified array as its source. 5570 * 5571 * @param array the array, assumed to be unmodified during use 5572 * @param startInclusive the first index to cover, inclusive 5573 * @param endExclusive index immediately past the last index to cover 5574 * @return a {@code DoubleStream} for the array range 5575 * @throws ArrayIndexOutOfBoundsException if {@code startInclusive} is 5576 * negative, {@code endExclusive} is less than 5577 * {@code startInclusive}, or {@code endExclusive} is greater than 5578 * the array size 5579 * @since 1.8 5580 */ 5581 public static DoubleStream stream(double[] array, int startInclusive, int endExclusive) { 5582 return StreamSupport.doubleStream(spliterator(array, startInclusive, endExclusive), false); 5583 } 5584 5585 5586 // Comparison methods 5587 5588 // Compare boolean 5589 5590 /** 5591 * Compares two {@code boolean} arrays lexicographically. 5592 * 5593 * <p>If the two arrays share a common prefix then the lexicographic 5594 * comparison is the result of comparing two elements, as if by 5595 * {@link Boolean#compare(boolean, boolean)}, at an index within the 5596 * respective arrays that is the prefix length. 5597 * Otherwise, one array is a proper prefix of the other and, lexicographic 5598 * comparison is the result of comparing the two array lengths. 5599 * (See {@link #mismatch(boolean[], boolean[])} for the definition of a 5600 * common and proper prefix.) 5601 * 5602 * <p>A {@code null} array reference is considered lexicographically less 5603 * than a non-{@code null} array reference. Two {@code null} array 5604 * references are considered equal. 5605 * 5606 * <p>The comparison is consistent with {@link #equals(boolean[], boolean[]) equals}, 5607 * more specifically the following holds for arrays {@code a} and {@code b}: 5608 * <pre>{@code 5609 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 5610 * }</pre> 5611 * 5612 * @apiNote 5613 * <p>This method behaves as if (for non-{@code null} array references): 5614 * <pre>{@code 5615 * int i = Arrays.mismatch(a, b); 5616 * if (i >= 0 && i < Math.min(a.length, b.length)) 5617 * return Boolean.compare(a[i], b[i]); 5618 * return a.length - b.length; 5619 * }</pre> 5620 * 5621 * @param a the first array to compare 5622 * @param b the second array to compare 5623 * @return the value {@code 0} if the first and second array are equal and 5624 * contain the same elements in the same order; 5625 * a value less than {@code 0} if the first array is 5626 * lexicographically less than the second array; and 5627 * a value greater than {@code 0} if the first array is 5628 * lexicographically greater than the second array 5629 * @since 9 5630 */ 5631 public static int compare(boolean[] a, boolean[] b) { 5632 if (a == b) 5633 return 0; 5634 if (a == null || b == null) 5635 return a == null ? -1 : 1; 5636 5637 int i = ArraysSupport.mismatch(a, b, 5638 Math.min(a.length, b.length)); 5639 if (i >= 0) { 5640 return Boolean.compare(a[i], b[i]); 5641 } 5642 5643 return a.length - b.length; 5644 } 5645 5646 /** 5647 * Compares two {@code boolean} arrays lexicographically over the specified 5648 * ranges. 5649 * 5650 * <p>If the two arrays, over the specified ranges, share a common prefix 5651 * then the lexicographic comparison is the result of comparing two 5652 * elements, as if by {@link Boolean#compare(boolean, boolean)}, at a 5653 * relative index within the respective arrays that is the length of the 5654 * prefix. 5655 * Otherwise, one array is a proper prefix of the other and, lexicographic 5656 * comparison is the result of comparing the two range lengths. 5657 * (See {@link #mismatch(boolean[], int, int, boolean[], int, int)} for the 5658 * definition of a common and proper prefix.) 5659 * 5660 * <p>The comparison is consistent with 5661 * {@link #equals(boolean[], int, int, boolean[], int, int) equals}, more 5662 * specifically the following holds for arrays {@code a} and {@code b} with 5663 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 5664 * [{@code bFromIndex}, {@code bToIndex}) respectively: 5665 * <pre>{@code 5666 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 5667 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 5668 * }</pre> 5669 * 5670 * @apiNote 5671 * <p>This method behaves as if: 5672 * <pre>{@code 5673 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 5674 * b, bFromIndex, bToIndex); 5675 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 5676 * return Boolean.compare(a[aFromIndex + i], b[bFromIndex + i]); 5677 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 5678 * }</pre> 5679 * 5680 * @param a the first array to compare 5681 * @param aFromIndex the index (inclusive) of the first element in the 5682 * first array to be compared 5683 * @param aToIndex the index (exclusive) of the last element in the 5684 * first array to be compared 5685 * @param b the second array to compare 5686 * @param bFromIndex the index (inclusive) of the first element in the 5687 * second array to be compared 5688 * @param bToIndex the index (exclusive) of the last element in the 5689 * second array to be compared 5690 * @return the value {@code 0} if, over the specified ranges, the first and 5691 * second array are equal and contain the same elements in the same 5692 * order; 5693 * a value less than {@code 0} if, over the specified ranges, the 5694 * first array is lexicographically less than the second array; and 5695 * a value greater than {@code 0} if, over the specified ranges, the 5696 * first array is lexicographically greater than the second array 5697 * @throws IllegalArgumentException 5698 * if {@code aFromIndex > aToIndex} or 5699 * if {@code bFromIndex > bToIndex} 5700 * @throws ArrayIndexOutOfBoundsException 5701 * if {@code aFromIndex < 0 or aToIndex > a.length} or 5702 * if {@code bFromIndex < 0 or bToIndex > b.length} 5703 * @throws NullPointerException 5704 * if either array is {@code null} 5705 * @since 9 5706 */ 5707 public static int compare(boolean[] a, int aFromIndex, int aToIndex, 5708 boolean[] b, int bFromIndex, int bToIndex) { 5709 rangeCheck(a.length, aFromIndex, aToIndex); 5710 rangeCheck(b.length, bFromIndex, bToIndex); 5711 5712 int aLength = aToIndex - aFromIndex; 5713 int bLength = bToIndex - bFromIndex; 5714 int i = ArraysSupport.mismatch(a, aFromIndex, 5715 b, bFromIndex, 5716 Math.min(aLength, bLength)); 5717 if (i >= 0) { 5718 return Boolean.compare(a[aFromIndex + i], b[bFromIndex + i]); 5719 } 5720 5721 return aLength - bLength; 5722 } 5723 5724 // Compare byte 5725 5726 /** 5727 * Compares two {@code byte} arrays lexicographically. 5728 * 5729 * <p>If the two arrays share a common prefix then the lexicographic 5730 * comparison is the result of comparing two elements, as if by 5731 * {@link Byte#compare(byte, byte)}, at an index within the respective 5732 * arrays that is the prefix length. 5733 * Otherwise, one array is a proper prefix of the other and, lexicographic 5734 * comparison is the result of comparing the two array lengths. 5735 * (See {@link #mismatch(byte[], byte[])} for the definition of a common and 5736 * proper prefix.) 5737 * 5738 * <p>A {@code null} array reference is considered lexicographically less 5739 * than a non-{@code null} array reference. Two {@code null} array 5740 * references are considered equal. 5741 * 5742 * <p>The comparison is consistent with {@link #equals(byte[], byte[]) equals}, 5743 * more specifically the following holds for arrays {@code a} and {@code b}: 5744 * <pre>{@code 5745 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 5746 * }</pre> 5747 * 5748 * @apiNote 5749 * <p>This method behaves as if (for non-{@code null} array references): 5750 * <pre>{@code 5751 * int i = Arrays.mismatch(a, b); 5752 * if (i >= 0 && i < Math.min(a.length, b.length)) 5753 * return Byte.compare(a[i], b[i]); 5754 * return a.length - b.length; 5755 * }</pre> 5756 * 5757 * @param a the first array to compare 5758 * @param b the second array to compare 5759 * @return the value {@code 0} if the first and second array are equal and 5760 * contain the same elements in the same order; 5761 * a value less than {@code 0} if the first array is 5762 * lexicographically less than the second array; and 5763 * a value greater than {@code 0} if the first array is 5764 * lexicographically greater than the second array 5765 * @since 9 5766 */ 5767 public static int compare(byte[] a, byte[] b) { 5768 if (a == b) 5769 return 0; 5770 if (a == null || b == null) 5771 return a == null ? -1 : 1; 5772 5773 int i = ArraysSupport.mismatch(a, b, 5774 Math.min(a.length, b.length)); 5775 if (i >= 0) { 5776 return Byte.compare(a[i], b[i]); 5777 } 5778 5779 return a.length - b.length; 5780 } 5781 5782 /** 5783 * Compares two {@code byte} arrays lexicographically over the specified 5784 * ranges. 5785 * 5786 * <p>If the two arrays, over the specified ranges, share a common prefix 5787 * then the lexicographic comparison is the result of comparing two 5788 * elements, as if by {@link Byte#compare(byte, byte)}, at a relative index 5789 * within the respective arrays that is the length of the prefix. 5790 * Otherwise, one array is a proper prefix of the other and, lexicographic 5791 * comparison is the result of comparing the two range lengths. 5792 * (See {@link #mismatch(byte[], int, int, byte[], int, int)} for the 5793 * definition of a common and proper prefix.) 5794 * 5795 * <p>The comparison is consistent with 5796 * {@link #equals(byte[], int, int, byte[], int, int) equals}, more 5797 * specifically the following holds for arrays {@code a} and {@code b} with 5798 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 5799 * [{@code bFromIndex}, {@code bToIndex}) respectively: 5800 * <pre>{@code 5801 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 5802 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 5803 * }</pre> 5804 * 5805 * @apiNote 5806 * <p>This method behaves as if: 5807 * <pre>{@code 5808 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 5809 * b, bFromIndex, bToIndex); 5810 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 5811 * return Byte.compare(a[aFromIndex + i], b[bFromIndex + i]); 5812 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 5813 * }</pre> 5814 * 5815 * @param a the first array to compare 5816 * @param aFromIndex the index (inclusive) of the first element in the 5817 * first array to be compared 5818 * @param aToIndex the index (exclusive) of the last element in the 5819 * first array to be compared 5820 * @param b the second array to compare 5821 * @param bFromIndex the index (inclusive) of the first element in the 5822 * second array to be compared 5823 * @param bToIndex the index (exclusive) of the last element in the 5824 * second array to be compared 5825 * @return the value {@code 0} if, over the specified ranges, the first and 5826 * second array are equal and contain the same elements in the same 5827 * order; 5828 * a value less than {@code 0} if, over the specified ranges, the 5829 * first array is lexicographically less than the second array; and 5830 * a value greater than {@code 0} if, over the specified ranges, the 5831 * first array is lexicographically greater than the second array 5832 * @throws IllegalArgumentException 5833 * if {@code aFromIndex > aToIndex} or 5834 * if {@code bFromIndex > bToIndex} 5835 * @throws ArrayIndexOutOfBoundsException 5836 * if {@code aFromIndex < 0 or aToIndex > a.length} or 5837 * if {@code bFromIndex < 0 or bToIndex > b.length} 5838 * @throws NullPointerException 5839 * if either array is {@code null} 5840 * @since 9 5841 */ 5842 public static int compare(byte[] a, int aFromIndex, int aToIndex, 5843 byte[] b, int bFromIndex, int bToIndex) { 5844 rangeCheck(a.length, aFromIndex, aToIndex); 5845 rangeCheck(b.length, bFromIndex, bToIndex); 5846 5847 int aLength = aToIndex - aFromIndex; 5848 int bLength = bToIndex - bFromIndex; 5849 int i = ArraysSupport.mismatch(a, aFromIndex, 5850 b, bFromIndex, 5851 Math.min(aLength, bLength)); 5852 if (i >= 0) { 5853 return Byte.compare(a[aFromIndex + i], b[bFromIndex + i]); 5854 } 5855 5856 return aLength - bLength; 5857 } 5858 5859 /** 5860 * Compares two {@code byte} arrays lexicographically, numerically treating 5861 * elements as unsigned. 5862 * 5863 * <p>If the two arrays share a common prefix then the lexicographic 5864 * comparison is the result of comparing two elements, as if by 5865 * {@link Byte#compareUnsigned(byte, byte)}, at an index within the 5866 * respective arrays that is the prefix length. 5867 * Otherwise, one array is a proper prefix of the other and, lexicographic 5868 * comparison is the result of comparing the two array lengths. 5869 * (See {@link #mismatch(byte[], byte[])} for the definition of a common 5870 * and proper prefix.) 5871 * 5872 * <p>A {@code null} array reference is considered lexicographically less 5873 * than a non-{@code null} array reference. Two {@code null} array 5874 * references are considered equal. 5875 * 5876 * @apiNote 5877 * <p>This method behaves as if (for non-{@code null} array references): 5878 * <pre>{@code 5879 * int i = Arrays.mismatch(a, b); 5880 * if (i >= 0 && i < Math.min(a.length, b.length)) 5881 * return Byte.compareUnsigned(a[i], b[i]); 5882 * return a.length - b.length; 5883 * }</pre> 5884 * 5885 * @param a the first array to compare 5886 * @param b the second array to compare 5887 * @return the value {@code 0} if the first and second array are 5888 * equal and contain the same elements in the same order; 5889 * a value less than {@code 0} if the first array is 5890 * lexicographically less than the second array; and 5891 * a value greater than {@code 0} if the first array is 5892 * lexicographically greater than the second array 5893 * @since 9 5894 */ 5895 public static int compareUnsigned(byte[] a, byte[] b) { 5896 if (a == b) 5897 return 0; 5898 if (a == null || b == null) 5899 return a == null ? -1 : 1; 5900 5901 int i = ArraysSupport.mismatch(a, b, 5902 Math.min(a.length, b.length)); 5903 if (i >= 0) { 5904 return Byte.compareUnsigned(a[i], b[i]); 5905 } 5906 5907 return a.length - b.length; 5908 } 5909 5910 5911 /** 5912 * Compares two {@code byte} arrays lexicographically over the specified 5913 * ranges, numerically treating elements as unsigned. 5914 * 5915 * <p>If the two arrays, over the specified ranges, share a common prefix 5916 * then the lexicographic comparison is the result of comparing two 5917 * elements, as if by {@link Byte#compareUnsigned(byte, byte)}, at a 5918 * relative index within the respective arrays that is the length of the 5919 * prefix. 5920 * Otherwise, one array is a proper prefix of the other and, lexicographic 5921 * comparison is the result of comparing the two range lengths. 5922 * (See {@link #mismatch(byte[], int, int, byte[], int, int)} for the 5923 * definition of a common and proper prefix.) 5924 * 5925 * @apiNote 5926 * <p>This method behaves as if: 5927 * <pre>{@code 5928 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 5929 * b, bFromIndex, bToIndex); 5930 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 5931 * return Byte.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]); 5932 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 5933 * }</pre> 5934 * 5935 * @param a the first array to compare 5936 * @param aFromIndex the index (inclusive) of the first element in the 5937 * first array to be compared 5938 * @param aToIndex the index (exclusive) of the last element in the 5939 * first array to be compared 5940 * @param b the second array to compare 5941 * @param bFromIndex the index (inclusive) of the first element in the 5942 * second array to be compared 5943 * @param bToIndex the index (exclusive) of the last element in the 5944 * second array to be compared 5945 * @return the value {@code 0} if, over the specified ranges, the first and 5946 * second array are equal and contain the same elements in the same 5947 * order; 5948 * a value less than {@code 0} if, over the specified ranges, the 5949 * first array is lexicographically less than the second array; and 5950 * a value greater than {@code 0} if, over the specified ranges, the 5951 * first array is lexicographically greater than the second array 5952 * @throws IllegalArgumentException 5953 * if {@code aFromIndex > aToIndex} or 5954 * if {@code bFromIndex > bToIndex} 5955 * @throws ArrayIndexOutOfBoundsException 5956 * if {@code aFromIndex < 0 or aToIndex > a.length} or 5957 * if {@code bFromIndex < 0 or bToIndex > b.length} 5958 * @throws NullPointerException 5959 * if either array is null 5960 * @since 9 5961 */ 5962 public static int compareUnsigned(byte[] a, int aFromIndex, int aToIndex, 5963 byte[] b, int bFromIndex, int bToIndex) { 5964 rangeCheck(a.length, aFromIndex, aToIndex); 5965 rangeCheck(b.length, bFromIndex, bToIndex); 5966 5967 int aLength = aToIndex - aFromIndex; 5968 int bLength = bToIndex - bFromIndex; 5969 int i = ArraysSupport.mismatch(a, aFromIndex, 5970 b, bFromIndex, 5971 Math.min(aLength, bLength)); 5972 if (i >= 0) { 5973 return Byte.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]); 5974 } 5975 5976 return aLength - bLength; 5977 } 5978 5979 // Compare short 5980 5981 /** 5982 * Compares two {@code short} arrays lexicographically. 5983 * 5984 * <p>If the two arrays share a common prefix then the lexicographic 5985 * comparison is the result of comparing two elements, as if by 5986 * {@link Short#compare(short, short)}, at an index within the respective 5987 * arrays that is the prefix length. 5988 * Otherwise, one array is a proper prefix of the other and, lexicographic 5989 * comparison is the result of comparing the two array lengths. 5990 * (See {@link #mismatch(short[], short[])} for the definition of a common 5991 * and proper prefix.) 5992 * 5993 * <p>A {@code null} array reference is considered lexicographically less 5994 * than a non-{@code null} array reference. Two {@code null} array 5995 * references are considered equal. 5996 * 5997 * <p>The comparison is consistent with {@link #equals(short[], short[]) equals}, 5998 * more specifically the following holds for arrays {@code a} and {@code b}: 5999 * <pre>{@code 6000 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 6001 * }</pre> 6002 * 6003 * @apiNote 6004 * <p>This method behaves as if (for non-{@code null} array references): 6005 * <pre>{@code 6006 * int i = Arrays.mismatch(a, b); 6007 * if (i >= 0 && i < Math.min(a.length, b.length)) 6008 * return Short.compare(a[i], b[i]); 6009 * return a.length - b.length; 6010 * }</pre> 6011 * 6012 * @param a the first array to compare 6013 * @param b the second array to compare 6014 * @return the value {@code 0} if the first and second array are equal and 6015 * contain the same elements in the same order; 6016 * a value less than {@code 0} if the first array is 6017 * lexicographically less than the second array; and 6018 * a value greater than {@code 0} if the first array is 6019 * lexicographically greater than the second array 6020 * @since 9 6021 */ 6022 public static int compare(short[] a, short[] b) { 6023 if (a == b) 6024 return 0; 6025 if (a == null || b == null) 6026 return a == null ? -1 : 1; 6027 6028 int i = ArraysSupport.mismatch(a, b, 6029 Math.min(a.length, b.length)); 6030 if (i >= 0) { 6031 return Short.compare(a[i], b[i]); 6032 } 6033 6034 return a.length - b.length; 6035 } 6036 6037 /** 6038 * Compares two {@code short} arrays lexicographically over the specified 6039 * ranges. 6040 * 6041 * <p>If the two arrays, over the specified ranges, share a common prefix 6042 * then the lexicographic comparison is the result of comparing two 6043 * elements, as if by {@link Short#compare(short, short)}, at a relative 6044 * index within the respective arrays that is the length of the prefix. 6045 * Otherwise, one array is a proper prefix of the other and, lexicographic 6046 * comparison is the result of comparing the two range lengths. 6047 * (See {@link #mismatch(short[], int, int, short[], int, int)} for the 6048 * definition of a common and proper prefix.) 6049 * 6050 * <p>The comparison is consistent with 6051 * {@link #equals(short[], int, int, short[], int, int) equals}, more 6052 * specifically the following holds for arrays {@code a} and {@code b} with 6053 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 6054 * [{@code bFromIndex}, {@code bToIndex}) respectively: 6055 * <pre>{@code 6056 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 6057 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 6058 * }</pre> 6059 * 6060 * @apiNote 6061 * <p>This method behaves as if: 6062 * <pre>{@code 6063 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 6064 * b, bFromIndex, bToIndex); 6065 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 6066 * return Short.compare(a[aFromIndex + i], b[bFromIndex + i]); 6067 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 6068 * }</pre> 6069 * 6070 * @param a the first array to compare 6071 * @param aFromIndex the index (inclusive) of the first element in the 6072 * first array to be compared 6073 * @param aToIndex the index (exclusive) of the last element in the 6074 * first array to be compared 6075 * @param b the second array to compare 6076 * @param bFromIndex the index (inclusive) of the first element in the 6077 * second array to be compared 6078 * @param bToIndex the index (exclusive) of the last element in the 6079 * second array to be compared 6080 * @return the value {@code 0} if, over the specified ranges, the first and 6081 * second array are equal and contain the same elements in the same 6082 * order; 6083 * a value less than {@code 0} if, over the specified ranges, the 6084 * first array is lexicographically less than the second array; and 6085 * a value greater than {@code 0} if, over the specified ranges, the 6086 * first array is lexicographically greater than the second array 6087 * @throws IllegalArgumentException 6088 * if {@code aFromIndex > aToIndex} or 6089 * if {@code bFromIndex > bToIndex} 6090 * @throws ArrayIndexOutOfBoundsException 6091 * if {@code aFromIndex < 0 or aToIndex > a.length} or 6092 * if {@code bFromIndex < 0 or bToIndex > b.length} 6093 * @throws NullPointerException 6094 * if either array is {@code null} 6095 * @since 9 6096 */ 6097 public static int compare(short[] a, int aFromIndex, int aToIndex, 6098 short[] b, int bFromIndex, int bToIndex) { 6099 rangeCheck(a.length, aFromIndex, aToIndex); 6100 rangeCheck(b.length, bFromIndex, bToIndex); 6101 6102 int aLength = aToIndex - aFromIndex; 6103 int bLength = bToIndex - bFromIndex; 6104 int i = ArraysSupport.mismatch(a, aFromIndex, 6105 b, bFromIndex, 6106 Math.min(aLength, bLength)); 6107 if (i >= 0) { 6108 return Short.compare(a[aFromIndex + i], b[bFromIndex + i]); 6109 } 6110 6111 return aLength - bLength; 6112 } 6113 6114 /** 6115 * Compares two {@code short} arrays lexicographically, numerically treating 6116 * elements as unsigned. 6117 * 6118 * <p>If the two arrays share a common prefix then the lexicographic 6119 * comparison is the result of comparing two elements, as if by 6120 * {@link Short#compareUnsigned(short, short)}, at an index within the 6121 * respective arrays that is the prefix length. 6122 * Otherwise, one array is a proper prefix of the other and, lexicographic 6123 * comparison is the result of comparing the two array lengths. 6124 * (See {@link #mismatch(short[], short[])} for the definition of a common 6125 * and proper prefix.) 6126 * 6127 * <p>A {@code null} array reference is considered lexicographically less 6128 * than a non-{@code null} array reference. Two {@code null} array 6129 * references are considered equal. 6130 * 6131 * @apiNote 6132 * <p>This method behaves as if (for non-{@code null} array references): 6133 * <pre>{@code 6134 * int i = Arrays.mismatch(a, b); 6135 * if (i >= 0 && i < Math.min(a.length, b.length)) 6136 * return Short.compareUnsigned(a[i], b[i]); 6137 * return a.length - b.length; 6138 * }</pre> 6139 * 6140 * @param a the first array to compare 6141 * @param b the second array to compare 6142 * @return the value {@code 0} if the first and second array are 6143 * equal and contain the same elements in the same order; 6144 * a value less than {@code 0} if the first array is 6145 * lexicographically less than the second array; and 6146 * a value greater than {@code 0} if the first array is 6147 * lexicographically greater than the second array 6148 * @since 9 6149 */ 6150 public static int compareUnsigned(short[] a, short[] b) { 6151 if (a == b) 6152 return 0; 6153 if (a == null || b == null) 6154 return a == null ? -1 : 1; 6155 6156 int i = ArraysSupport.mismatch(a, b, 6157 Math.min(a.length, b.length)); 6158 if (i >= 0) { 6159 return Short.compareUnsigned(a[i], b[i]); 6160 } 6161 6162 return a.length - b.length; 6163 } 6164 6165 /** 6166 * Compares two {@code short} arrays lexicographically over the specified 6167 * ranges, numerically treating elements as unsigned. 6168 * 6169 * <p>If the two arrays, over the specified ranges, share a common prefix 6170 * then the lexicographic comparison is the result of comparing two 6171 * elements, as if by {@link Short#compareUnsigned(short, short)}, at a 6172 * relative index within the respective arrays that is the length of the 6173 * prefix. 6174 * Otherwise, one array is a proper prefix of the other and, lexicographic 6175 * comparison is the result of comparing the two range lengths. 6176 * (See {@link #mismatch(short[], int, int, short[], int, int)} for the 6177 * definition of a common and proper prefix.) 6178 * 6179 * @apiNote 6180 * <p>This method behaves as if: 6181 * <pre>{@code 6182 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 6183 * b, bFromIndex, bToIndex); 6184 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 6185 * return Short.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]); 6186 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 6187 * }</pre> 6188 * 6189 * @param a the first array to compare 6190 * @param aFromIndex the index (inclusive) of the first element in the 6191 * first array to be compared 6192 * @param aToIndex the index (exclusive) of the last element in the 6193 * first array to be compared 6194 * @param b the second array to compare 6195 * @param bFromIndex the index (inclusive) of the first element in the 6196 * second array to be compared 6197 * @param bToIndex the index (exclusive) of the last element in the 6198 * second array to be compared 6199 * @return the value {@code 0} if, over the specified ranges, the first and 6200 * second array are equal and contain the same elements in the same 6201 * order; 6202 * a value less than {@code 0} if, over the specified ranges, the 6203 * first array is lexicographically less than the second array; and 6204 * a value greater than {@code 0} if, over the specified ranges, the 6205 * first array is lexicographically greater than the second array 6206 * @throws IllegalArgumentException 6207 * if {@code aFromIndex > aToIndex} or 6208 * if {@code bFromIndex > bToIndex} 6209 * @throws ArrayIndexOutOfBoundsException 6210 * if {@code aFromIndex < 0 or aToIndex > a.length} or 6211 * if {@code bFromIndex < 0 or bToIndex > b.length} 6212 * @throws NullPointerException 6213 * if either array is null 6214 * @since 9 6215 */ 6216 public static int compareUnsigned(short[] a, int aFromIndex, int aToIndex, 6217 short[] b, int bFromIndex, int bToIndex) { 6218 rangeCheck(a.length, aFromIndex, aToIndex); 6219 rangeCheck(b.length, bFromIndex, bToIndex); 6220 6221 int aLength = aToIndex - aFromIndex; 6222 int bLength = bToIndex - bFromIndex; 6223 int i = ArraysSupport.mismatch(a, aFromIndex, 6224 b, bFromIndex, 6225 Math.min(aLength, bLength)); 6226 if (i >= 0) { 6227 return Short.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]); 6228 } 6229 6230 return aLength - bLength; 6231 } 6232 6233 // Compare char 6234 6235 /** 6236 * Compares two {@code char} arrays lexicographically. 6237 * 6238 * <p>If the two arrays share a common prefix then the lexicographic 6239 * comparison is the result of comparing two elements, as if by 6240 * {@link Character#compare(char, char)}, at an index within the respective 6241 * arrays that is the prefix length. 6242 * Otherwise, one array is a proper prefix of the other and, lexicographic 6243 * comparison is the result of comparing the two array lengths. 6244 * (See {@link #mismatch(char[], char[])} for the definition of a common and 6245 * proper prefix.) 6246 * 6247 * <p>A {@code null} array reference is considered lexicographically less 6248 * than a non-{@code null} array reference. Two {@code null} array 6249 * references are considered equal. 6250 * 6251 * <p>The comparison is consistent with {@link #equals(char[], char[]) equals}, 6252 * more specifically the following holds for arrays {@code a} and {@code b}: 6253 * <pre>{@code 6254 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 6255 * }</pre> 6256 * 6257 * @apiNote 6258 * <p>This method behaves as if (for non-{@code null} array references): 6259 * <pre>{@code 6260 * int i = Arrays.mismatch(a, b); 6261 * if (i >= 0 && i < Math.min(a.length, b.length)) 6262 * return Character.compare(a[i], b[i]); 6263 * return a.length - b.length; 6264 * }</pre> 6265 * 6266 * @param a the first array to compare 6267 * @param b the second array to compare 6268 * @return the value {@code 0} if the first and second array are equal and 6269 * contain the same elements in the same order; 6270 * a value less than {@code 0} if the first array is 6271 * lexicographically less than the second array; and 6272 * a value greater than {@code 0} if the first array is 6273 * lexicographically greater than the second array 6274 * @since 9 6275 */ 6276 public static int compare(char[] a, char[] b) { 6277 if (a == b) 6278 return 0; 6279 if (a == null || b == null) 6280 return a == null ? -1 : 1; 6281 6282 int i = ArraysSupport.mismatch(a, b, 6283 Math.min(a.length, b.length)); 6284 if (i >= 0) { 6285 return Character.compare(a[i], b[i]); 6286 } 6287 6288 return a.length - b.length; 6289 } 6290 6291 /** 6292 * Compares two {@code char} arrays lexicographically over the specified 6293 * ranges. 6294 * 6295 * <p>If the two arrays, over the specified ranges, share a common prefix 6296 * then the lexicographic comparison is the result of comparing two 6297 * elements, as if by {@link Character#compare(char, char)}, at a relative 6298 * index within the respective arrays that is the length of the prefix. 6299 * Otherwise, one array is a proper prefix of the other and, lexicographic 6300 * comparison is the result of comparing the two range lengths. 6301 * (See {@link #mismatch(char[], int, int, char[], int, int)} for the 6302 * definition of a common and proper prefix.) 6303 * 6304 * <p>The comparison is consistent with 6305 * {@link #equals(char[], int, int, char[], int, int) equals}, more 6306 * specifically the following holds for arrays {@code a} and {@code b} with 6307 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 6308 * [{@code bFromIndex}, {@code bToIndex}) respectively: 6309 * <pre>{@code 6310 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 6311 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 6312 * }</pre> 6313 * 6314 * @apiNote 6315 * <p>This method behaves as if: 6316 * <pre>{@code 6317 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 6318 * b, bFromIndex, bToIndex); 6319 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 6320 * return Character.compare(a[aFromIndex + i], b[bFromIndex + i]); 6321 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 6322 * }</pre> 6323 * 6324 * @param a the first array to compare 6325 * @param aFromIndex the index (inclusive) of the first element in the 6326 * first array to be compared 6327 * @param aToIndex the index (exclusive) of the last element in the 6328 * first array to be compared 6329 * @param b the second array to compare 6330 * @param bFromIndex the index (inclusive) of the first element in the 6331 * second array to be compared 6332 * @param bToIndex the index (exclusive) of the last element in the 6333 * second array to be compared 6334 * @return the value {@code 0} if, over the specified ranges, the first and 6335 * second array are equal and contain the same elements in the same 6336 * order; 6337 * a value less than {@code 0} if, over the specified ranges, the 6338 * first array is lexicographically less than the second array; and 6339 * a value greater than {@code 0} if, over the specified ranges, the 6340 * first array is lexicographically greater than the second array 6341 * @throws IllegalArgumentException 6342 * if {@code aFromIndex > aToIndex} or 6343 * if {@code bFromIndex > bToIndex} 6344 * @throws ArrayIndexOutOfBoundsException 6345 * if {@code aFromIndex < 0 or aToIndex > a.length} or 6346 * if {@code bFromIndex < 0 or bToIndex > b.length} 6347 * @throws NullPointerException 6348 * if either array is {@code null} 6349 * @since 9 6350 */ 6351 public static int compare(char[] a, int aFromIndex, int aToIndex, 6352 char[] b, int bFromIndex, int bToIndex) { 6353 rangeCheck(a.length, aFromIndex, aToIndex); 6354 rangeCheck(b.length, bFromIndex, bToIndex); 6355 6356 int aLength = aToIndex - aFromIndex; 6357 int bLength = bToIndex - bFromIndex; 6358 int i = ArraysSupport.mismatch(a, aFromIndex, 6359 b, bFromIndex, 6360 Math.min(aLength, bLength)); 6361 if (i >= 0) { 6362 return Character.compare(a[aFromIndex + i], b[bFromIndex + i]); 6363 } 6364 6365 return aLength - bLength; 6366 } 6367 6368 // Compare int 6369 6370 /** 6371 * Compares two {@code int} arrays lexicographically. 6372 * 6373 * <p>If the two arrays share a common prefix then the lexicographic 6374 * comparison is the result of comparing two elements, as if by 6375 * {@link Integer#compare(int, int)}, at an index within the respective 6376 * arrays that is the prefix length. 6377 * Otherwise, one array is a proper prefix of the other and, lexicographic 6378 * comparison is the result of comparing the two array lengths. 6379 * (See {@link #mismatch(int[], int[])} for the definition of a common and 6380 * proper prefix.) 6381 * 6382 * <p>A {@code null} array reference is considered lexicographically less 6383 * than a non-{@code null} array reference. Two {@code null} array 6384 * references are considered equal. 6385 * 6386 * <p>The comparison is consistent with {@link #equals(int[], int[]) equals}, 6387 * more specifically the following holds for arrays {@code a} and {@code b}: 6388 * <pre>{@code 6389 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 6390 * }</pre> 6391 * 6392 * @apiNote 6393 * <p>This method behaves as if (for non-{@code null} array references): 6394 * <pre>{@code 6395 * int i = Arrays.mismatch(a, b); 6396 * if (i >= 0 && i < Math.min(a.length, b.length)) 6397 * return Integer.compare(a[i], b[i]); 6398 * return a.length - b.length; 6399 * }</pre> 6400 * 6401 * @param a the first array to compare 6402 * @param b the second array to compare 6403 * @return the value {@code 0} if the first and second array are equal and 6404 * contain the same elements in the same order; 6405 * a value less than {@code 0} if the first array is 6406 * lexicographically less than the second array; and 6407 * a value greater than {@code 0} if the first array is 6408 * lexicographically greater than the second array 6409 * @since 9 6410 */ 6411 public static int compare(int[] a, int[] b) { 6412 if (a == b) 6413 return 0; 6414 if (a == null || b == null) 6415 return a == null ? -1 : 1; 6416 6417 int i = ArraysSupport.mismatch(a, b, 6418 Math.min(a.length, b.length)); 6419 if (i >= 0) { 6420 return Integer.compare(a[i], b[i]); 6421 } 6422 6423 return a.length - b.length; 6424 } 6425 6426 /** 6427 * Compares two {@code int} arrays lexicographically over the specified 6428 * ranges. 6429 * 6430 * <p>If the two arrays, over the specified ranges, share a common prefix 6431 * then the lexicographic comparison is the result of comparing two 6432 * elements, as if by {@link Integer#compare(int, int)}, at a relative index 6433 * within the respective arrays that is the length of the prefix. 6434 * Otherwise, one array is a proper prefix of the other and, lexicographic 6435 * comparison is the result of comparing the two range lengths. 6436 * (See {@link #mismatch(int[], int, int, int[], int, int)} for the 6437 * definition of a common and proper prefix.) 6438 * 6439 * <p>The comparison is consistent with 6440 * {@link #equals(int[], int, int, int[], int, int) equals}, more 6441 * specifically the following holds for arrays {@code a} and {@code b} with 6442 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 6443 * [{@code bFromIndex}, {@code bToIndex}) respectively: 6444 * <pre>{@code 6445 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 6446 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 6447 * }</pre> 6448 * 6449 * @apiNote 6450 * <p>This method behaves as if: 6451 * <pre>{@code 6452 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 6453 * b, bFromIndex, bToIndex); 6454 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 6455 * return Integer.compare(a[aFromIndex + i], b[bFromIndex + i]); 6456 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 6457 * }</pre> 6458 * 6459 * @param a the first array to compare 6460 * @param aFromIndex the index (inclusive) of the first element in the 6461 * first array to be compared 6462 * @param aToIndex the index (exclusive) of the last element in the 6463 * first array to be compared 6464 * @param b the second array to compare 6465 * @param bFromIndex the index (inclusive) of the first element in the 6466 * second array to be compared 6467 * @param bToIndex the index (exclusive) of the last element in the 6468 * second array to be compared 6469 * @return the value {@code 0} if, over the specified ranges, the first and 6470 * second array are equal and contain the same elements in the same 6471 * order; 6472 * a value less than {@code 0} if, over the specified ranges, the 6473 * first array is lexicographically less than the second array; and 6474 * a value greater than {@code 0} if, over the specified ranges, the 6475 * first array is lexicographically greater than the second array 6476 * @throws IllegalArgumentException 6477 * if {@code aFromIndex > aToIndex} or 6478 * if {@code bFromIndex > bToIndex} 6479 * @throws ArrayIndexOutOfBoundsException 6480 * if {@code aFromIndex < 0 or aToIndex > a.length} or 6481 * if {@code bFromIndex < 0 or bToIndex > b.length} 6482 * @throws NullPointerException 6483 * if either array is {@code null} 6484 * @since 9 6485 */ 6486 public static int compare(int[] a, int aFromIndex, int aToIndex, 6487 int[] b, int bFromIndex, int bToIndex) { 6488 rangeCheck(a.length, aFromIndex, aToIndex); 6489 rangeCheck(b.length, bFromIndex, bToIndex); 6490 6491 int aLength = aToIndex - aFromIndex; 6492 int bLength = bToIndex - bFromIndex; 6493 int i = ArraysSupport.mismatch(a, aFromIndex, 6494 b, bFromIndex, 6495 Math.min(aLength, bLength)); 6496 if (i >= 0) { 6497 return Integer.compare(a[aFromIndex + i], b[bFromIndex + i]); 6498 } 6499 6500 return aLength - bLength; 6501 } 6502 6503 /** 6504 * Compares two {@code int} arrays lexicographically, numerically treating 6505 * elements as unsigned. 6506 * 6507 * <p>If the two arrays share a common prefix then the lexicographic 6508 * comparison is the result of comparing two elements, as if by 6509 * {@link Integer#compareUnsigned(int, int)}, at an index within the 6510 * respective arrays that is the prefix length. 6511 * Otherwise, one array is a proper prefix of the other and, lexicographic 6512 * comparison is the result of comparing the two array lengths. 6513 * (See {@link #mismatch(int[], int[])} for the definition of a common 6514 * and proper prefix.) 6515 * 6516 * <p>A {@code null} array reference is considered lexicographically less 6517 * than a non-{@code null} array reference. Two {@code null} array 6518 * references are considered equal. 6519 * 6520 * @apiNote 6521 * <p>This method behaves as if (for non-{@code null} array references): 6522 * <pre>{@code 6523 * int i = Arrays.mismatch(a, b); 6524 * if (i >= 0 && i < Math.min(a.length, b.length)) 6525 * return Integer.compareUnsigned(a[i], b[i]); 6526 * return a.length - b.length; 6527 * }</pre> 6528 * 6529 * @param a the first array to compare 6530 * @param b the second array to compare 6531 * @return the value {@code 0} if the first and second array are 6532 * equal and contain the same elements in the same order; 6533 * a value less than {@code 0} if the first array is 6534 * lexicographically less than the second array; and 6535 * a value greater than {@code 0} if the first array is 6536 * lexicographically greater than the second array 6537 * @since 9 6538 */ 6539 public static int compareUnsigned(int[] a, int[] b) { 6540 if (a == b) 6541 return 0; 6542 if (a == null || b == null) 6543 return a == null ? -1 : 1; 6544 6545 int i = ArraysSupport.mismatch(a, b, 6546 Math.min(a.length, b.length)); 6547 if (i >= 0) { 6548 return Integer.compareUnsigned(a[i], b[i]); 6549 } 6550 6551 return a.length - b.length; 6552 } 6553 6554 /** 6555 * Compares two {@code int} arrays lexicographically over the specified 6556 * ranges, numerically treating elements as unsigned. 6557 * 6558 * <p>If the two arrays, over the specified ranges, share a common prefix 6559 * then the lexicographic comparison is the result of comparing two 6560 * elements, as if by {@link Integer#compareUnsigned(int, int)}, at a 6561 * relative index within the respective arrays that is the length of the 6562 * prefix. 6563 * Otherwise, one array is a proper prefix of the other and, lexicographic 6564 * comparison is the result of comparing the two range lengths. 6565 * (See {@link #mismatch(int[], int, int, int[], int, int)} for the 6566 * definition of a common and proper prefix.) 6567 * 6568 * @apiNote 6569 * <p>This method behaves as if: 6570 * <pre>{@code 6571 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 6572 * b, bFromIndex, bToIndex); 6573 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 6574 * return Integer.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]); 6575 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 6576 * }</pre> 6577 * 6578 * @param a the first array to compare 6579 * @param aFromIndex the index (inclusive) of the first element in the 6580 * first array to be compared 6581 * @param aToIndex the index (exclusive) of the last element in the 6582 * first array to be compared 6583 * @param b the second array to compare 6584 * @param bFromIndex the index (inclusive) of the first element in the 6585 * second array to be compared 6586 * @param bToIndex the index (exclusive) of the last element in the 6587 * second array to be compared 6588 * @return the value {@code 0} if, over the specified ranges, the first and 6589 * second array are equal and contain the same elements in the same 6590 * order; 6591 * a value less than {@code 0} if, over the specified ranges, the 6592 * first array is lexicographically less than the second array; and 6593 * a value greater than {@code 0} if, over the specified ranges, the 6594 * first array is lexicographically greater than the second array 6595 * @throws IllegalArgumentException 6596 * if {@code aFromIndex > aToIndex} or 6597 * if {@code bFromIndex > bToIndex} 6598 * @throws ArrayIndexOutOfBoundsException 6599 * if {@code aFromIndex < 0 or aToIndex > a.length} or 6600 * if {@code bFromIndex < 0 or bToIndex > b.length} 6601 * @throws NullPointerException 6602 * if either array is null 6603 * @since 9 6604 */ 6605 public static int compareUnsigned(int[] a, int aFromIndex, int aToIndex, 6606 int[] b, int bFromIndex, int bToIndex) { 6607 rangeCheck(a.length, aFromIndex, aToIndex); 6608 rangeCheck(b.length, bFromIndex, bToIndex); 6609 6610 int aLength = aToIndex - aFromIndex; 6611 int bLength = bToIndex - bFromIndex; 6612 int i = ArraysSupport.mismatch(a, aFromIndex, 6613 b, bFromIndex, 6614 Math.min(aLength, bLength)); 6615 if (i >= 0) { 6616 return Integer.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]); 6617 } 6618 6619 return aLength - bLength; 6620 } 6621 6622 // Compare long 6623 6624 /** 6625 * Compares two {@code long} arrays lexicographically. 6626 * 6627 * <p>If the two arrays share a common prefix then the lexicographic 6628 * comparison is the result of comparing two elements, as if by 6629 * {@link Long#compare(long, long)}, at an index within the respective 6630 * arrays that is the prefix length. 6631 * Otherwise, one array is a proper prefix of the other and, lexicographic 6632 * comparison is the result of comparing the two array lengths. 6633 * (See {@link #mismatch(long[], long[])} for the definition of a common and 6634 * proper prefix.) 6635 * 6636 * <p>A {@code null} array reference is considered lexicographically less 6637 * than a non-{@code null} array reference. Two {@code null} array 6638 * references are considered equal. 6639 * 6640 * <p>The comparison is consistent with {@link #equals(long[], long[]) equals}, 6641 * more specifically the following holds for arrays {@code a} and {@code b}: 6642 * <pre>{@code 6643 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 6644 * }</pre> 6645 * 6646 * @apiNote 6647 * <p>This method behaves as if (for non-{@code null} array references): 6648 * <pre>{@code 6649 * int i = Arrays.mismatch(a, b); 6650 * if (i >= 0 && i < Math.min(a.length, b.length)) 6651 * return Long.compare(a[i], b[i]); 6652 * return a.length - b.length; 6653 * }</pre> 6654 * 6655 * @param a the first array to compare 6656 * @param b the second array to compare 6657 * @return the value {@code 0} if the first and second array are equal and 6658 * contain the same elements in the same order; 6659 * a value less than {@code 0} if the first array is 6660 * lexicographically less than the second array; and 6661 * a value greater than {@code 0} if the first array is 6662 * lexicographically greater than the second array 6663 * @since 9 6664 */ 6665 public static int compare(long[] a, long[] b) { 6666 if (a == b) 6667 return 0; 6668 if (a == null || b == null) 6669 return a == null ? -1 : 1; 6670 6671 int i = ArraysSupport.mismatch(a, b, 6672 Math.min(a.length, b.length)); 6673 if (i >= 0) { 6674 return Long.compare(a[i], b[i]); 6675 } 6676 6677 return a.length - b.length; 6678 } 6679 6680 /** 6681 * Compares two {@code long} arrays lexicographically over the specified 6682 * ranges. 6683 * 6684 * <p>If the two arrays, over the specified ranges, share a common prefix 6685 * then the lexicographic comparison is the result of comparing two 6686 * elements, as if by {@link Long#compare(long, long)}, at a relative index 6687 * within the respective arrays that is the length of the prefix. 6688 * Otherwise, one array is a proper prefix of the other and, lexicographic 6689 * comparison is the result of comparing the two range lengths. 6690 * (See {@link #mismatch(long[], int, int, long[], int, int)} for the 6691 * definition of a common and proper prefix.) 6692 * 6693 * <p>The comparison is consistent with 6694 * {@link #equals(long[], int, int, long[], int, int) equals}, more 6695 * specifically the following holds for arrays {@code a} and {@code b} with 6696 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 6697 * [{@code bFromIndex}, {@code bToIndex}) respectively: 6698 * <pre>{@code 6699 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 6700 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 6701 * }</pre> 6702 * 6703 * @apiNote 6704 * <p>This method behaves as if: 6705 * <pre>{@code 6706 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 6707 * b, bFromIndex, bToIndex); 6708 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 6709 * return Long.compare(a[aFromIndex + i], b[bFromIndex + i]); 6710 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 6711 * }</pre> 6712 * 6713 * @param a the first array to compare 6714 * @param aFromIndex the index (inclusive) of the first element in the 6715 * first array to be compared 6716 * @param aToIndex the index (exclusive) of the last element in the 6717 * first array to be compared 6718 * @param b the second array to compare 6719 * @param bFromIndex the index (inclusive) of the first element in the 6720 * second array to be compared 6721 * @param bToIndex the index (exclusive) of the last element in the 6722 * second array to be compared 6723 * @return the value {@code 0} if, over the specified ranges, the first and 6724 * second array are equal and contain the same elements in the same 6725 * order; 6726 * a value less than {@code 0} if, over the specified ranges, the 6727 * first array is lexicographically less than the second array; and 6728 * a value greater than {@code 0} if, over the specified ranges, the 6729 * first array is lexicographically greater than the second array 6730 * @throws IllegalArgumentException 6731 * if {@code aFromIndex > aToIndex} or 6732 * if {@code bFromIndex > bToIndex} 6733 * @throws ArrayIndexOutOfBoundsException 6734 * if {@code aFromIndex < 0 or aToIndex > a.length} or 6735 * if {@code bFromIndex < 0 or bToIndex > b.length} 6736 * @throws NullPointerException 6737 * if either array is {@code null} 6738 * @since 9 6739 */ 6740 public static int compare(long[] a, int aFromIndex, int aToIndex, 6741 long[] b, int bFromIndex, int bToIndex) { 6742 rangeCheck(a.length, aFromIndex, aToIndex); 6743 rangeCheck(b.length, bFromIndex, bToIndex); 6744 6745 int aLength = aToIndex - aFromIndex; 6746 int bLength = bToIndex - bFromIndex; 6747 int i = ArraysSupport.mismatch(a, aFromIndex, 6748 b, bFromIndex, 6749 Math.min(aLength, bLength)); 6750 if (i >= 0) { 6751 return Long.compare(a[aFromIndex + i], b[bFromIndex + i]); 6752 } 6753 6754 return aLength - bLength; 6755 } 6756 6757 /** 6758 * Compares two {@code long} arrays lexicographically, numerically treating 6759 * elements as unsigned. 6760 * 6761 * <p>If the two arrays share a common prefix then the lexicographic 6762 * comparison is the result of comparing two elements, as if by 6763 * {@link Long#compareUnsigned(long, long)}, at an index within the 6764 * respective arrays that is the prefix length. 6765 * Otherwise, one array is a proper prefix of the other and, lexicographic 6766 * comparison is the result of comparing the two array lengths. 6767 * (See {@link #mismatch(long[], long[])} for the definition of a common 6768 * and proper prefix.) 6769 * 6770 * <p>A {@code null} array reference is considered lexicographically less 6771 * than a non-{@code null} array reference. Two {@code null} array 6772 * references are considered equal. 6773 * 6774 * @apiNote 6775 * <p>This method behaves as if (for non-{@code null} array references): 6776 * <pre>{@code 6777 * int i = Arrays.mismatch(a, b); 6778 * if (i >= 0 && i < Math.min(a.length, b.length)) 6779 * return Long.compareUnsigned(a[i], b[i]); 6780 * return a.length - b.length; 6781 * }</pre> 6782 * 6783 * @param a the first array to compare 6784 * @param b the second array to compare 6785 * @return the value {@code 0} if the first and second array are 6786 * equal and contain the same elements in the same order; 6787 * a value less than {@code 0} if the first array is 6788 * lexicographically less than the second array; and 6789 * a value greater than {@code 0} if the first array is 6790 * lexicographically greater than the second array 6791 * @since 9 6792 */ 6793 public static int compareUnsigned(long[] a, long[] b) { 6794 if (a == b) 6795 return 0; 6796 if (a == null || b == null) 6797 return a == null ? -1 : 1; 6798 6799 int i = ArraysSupport.mismatch(a, b, 6800 Math.min(a.length, b.length)); 6801 if (i >= 0) { 6802 return Long.compareUnsigned(a[i], b[i]); 6803 } 6804 6805 return a.length - b.length; 6806 } 6807 6808 /** 6809 * Compares two {@code long} arrays lexicographically over the specified 6810 * ranges, numerically treating elements as unsigned. 6811 * 6812 * <p>If the two arrays, over the specified ranges, share a common prefix 6813 * then the lexicographic comparison is the result of comparing two 6814 * elements, as if by {@link Long#compareUnsigned(long, long)}, at a 6815 * relative index within the respective arrays that is the length of the 6816 * prefix. 6817 * Otherwise, one array is a proper prefix of the other and, lexicographic 6818 * comparison is the result of comparing the two range lengths. 6819 * (See {@link #mismatch(long[], int, int, long[], int, int)} for the 6820 * definition of a common and proper prefix.) 6821 * 6822 * @apiNote 6823 * <p>This method behaves as if: 6824 * <pre>{@code 6825 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 6826 * b, bFromIndex, bToIndex); 6827 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 6828 * return Long.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]); 6829 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 6830 * }</pre> 6831 * 6832 * @param a the first array to compare 6833 * @param aFromIndex the index (inclusive) of the first element in the 6834 * first array to be compared 6835 * @param aToIndex the index (exclusive) of the last element in the 6836 * first array to be compared 6837 * @param b the second array to compare 6838 * @param bFromIndex the index (inclusive) of the first element in the 6839 * second array to be compared 6840 * @param bToIndex the index (exclusive) of the last element in the 6841 * second array to be compared 6842 * @return the value {@code 0} if, over the specified ranges, the first and 6843 * second array are equal and contain the same elements in the same 6844 * order; 6845 * a value less than {@code 0} if, over the specified ranges, the 6846 * first array is lexicographically less than the second array; and 6847 * a value greater than {@code 0} if, over the specified ranges, the 6848 * first array is lexicographically greater than the second array 6849 * @throws IllegalArgumentException 6850 * if {@code aFromIndex > aToIndex} or 6851 * if {@code bFromIndex > bToIndex} 6852 * @throws ArrayIndexOutOfBoundsException 6853 * if {@code aFromIndex < 0 or aToIndex > a.length} or 6854 * if {@code bFromIndex < 0 or bToIndex > b.length} 6855 * @throws NullPointerException 6856 * if either array is null 6857 * @since 9 6858 */ 6859 public static int compareUnsigned(long[] a, int aFromIndex, int aToIndex, 6860 long[] b, int bFromIndex, int bToIndex) { 6861 rangeCheck(a.length, aFromIndex, aToIndex); 6862 rangeCheck(b.length, bFromIndex, bToIndex); 6863 6864 int aLength = aToIndex - aFromIndex; 6865 int bLength = bToIndex - bFromIndex; 6866 int i = ArraysSupport.mismatch(a, aFromIndex, 6867 b, bFromIndex, 6868 Math.min(aLength, bLength)); 6869 if (i >= 0) { 6870 return Long.compareUnsigned(a[aFromIndex + i], b[bFromIndex + i]); 6871 } 6872 6873 return aLength - bLength; 6874 } 6875 6876 // Compare float 6877 6878 /** 6879 * Compares two {@code float} arrays lexicographically. 6880 * 6881 * <p>If the two arrays share a common prefix then the lexicographic 6882 * comparison is the result of comparing two elements, as if by 6883 * {@link Float#compare(float, float)}, at an index within the respective 6884 * arrays that is the prefix length. 6885 * Otherwise, one array is a proper prefix of the other and, lexicographic 6886 * comparison is the result of comparing the two array lengths. 6887 * (See {@link #mismatch(float[], float[])} for the definition of a common 6888 * and proper prefix.) 6889 * 6890 * <p>A {@code null} array reference is considered lexicographically less 6891 * than a non-{@code null} array reference. Two {@code null} array 6892 * references are considered equal. 6893 * 6894 * <p>The comparison is consistent with {@link #equals(float[], float[]) equals}, 6895 * more specifically the following holds for arrays {@code a} and {@code b}: 6896 * <pre>{@code 6897 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 6898 * }</pre> 6899 * 6900 * @apiNote 6901 * <p>This method behaves as if (for non-{@code null} array references): 6902 * <pre>{@code 6903 * int i = Arrays.mismatch(a, b); 6904 * if (i >= 0 && i < Math.min(a.length, b.length)) 6905 * return Float.compare(a[i], b[i]); 6906 * return a.length - b.length; 6907 * }</pre> 6908 * 6909 * @param a the first array to compare 6910 * @param b the second array to compare 6911 * @return the value {@code 0} if the first and second array are equal and 6912 * contain the same elements in the same order; 6913 * a value less than {@code 0} if the first array is 6914 * lexicographically less than the second array; and 6915 * a value greater than {@code 0} if the first array is 6916 * lexicographically greater than the second array 6917 * @since 9 6918 */ 6919 public static int compare(float[] a, float[] b) { 6920 if (a == b) 6921 return 0; 6922 if (a == null || b == null) 6923 return a == null ? -1 : 1; 6924 6925 int i = ArraysSupport.mismatch(a, b, 6926 Math.min(a.length, b.length)); 6927 if (i >= 0) { 6928 return Float.compare(a[i], b[i]); 6929 } 6930 6931 return a.length - b.length; 6932 } 6933 6934 /** 6935 * Compares two {@code float} arrays lexicographically over the specified 6936 * ranges. 6937 * 6938 * <p>If the two arrays, over the specified ranges, share a common prefix 6939 * then the lexicographic comparison is the result of comparing two 6940 * elements, as if by {@link Float#compare(float, float)}, at a relative 6941 * index within the respective arrays that is the length of the prefix. 6942 * Otherwise, one array is a proper prefix of the other and, lexicographic 6943 * comparison is the result of comparing the two range lengths. 6944 * (See {@link #mismatch(float[], int, int, float[], int, int)} for the 6945 * definition of a common and proper prefix.) 6946 * 6947 * <p>The comparison is consistent with 6948 * {@link #equals(float[], int, int, float[], int, int) equals}, more 6949 * specifically the following holds for arrays {@code a} and {@code b} with 6950 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 6951 * [{@code bFromIndex}, {@code bToIndex}) respectively: 6952 * <pre>{@code 6953 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 6954 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 6955 * }</pre> 6956 * 6957 * @apiNote 6958 * <p>This method behaves as if: 6959 * <pre>{@code 6960 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 6961 * b, bFromIndex, bToIndex); 6962 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 6963 * return Float.compare(a[aFromIndex + i], b[bFromIndex + i]); 6964 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 6965 * }</pre> 6966 * 6967 * @param a the first array to compare 6968 * @param aFromIndex the index (inclusive) of the first element in the 6969 * first array to be compared 6970 * @param aToIndex the index (exclusive) of the last element in the 6971 * first array to be compared 6972 * @param b the second array to compare 6973 * @param bFromIndex the index (inclusive) of the first element in the 6974 * second array to be compared 6975 * @param bToIndex the index (exclusive) of the last element in the 6976 * second array to be compared 6977 * @return the value {@code 0} if, over the specified ranges, the first and 6978 * second array are equal and contain the same elements in the same 6979 * order; 6980 * a value less than {@code 0} if, over the specified ranges, the 6981 * first array is lexicographically less than the second array; and 6982 * a value greater than {@code 0} if, over the specified ranges, the 6983 * first array is lexicographically greater than the second array 6984 * @throws IllegalArgumentException 6985 * if {@code aFromIndex > aToIndex} or 6986 * if {@code bFromIndex > bToIndex} 6987 * @throws ArrayIndexOutOfBoundsException 6988 * if {@code aFromIndex < 0 or aToIndex > a.length} or 6989 * if {@code bFromIndex < 0 or bToIndex > b.length} 6990 * @throws NullPointerException 6991 * if either array is {@code null} 6992 * @since 9 6993 */ 6994 public static int compare(float[] a, int aFromIndex, int aToIndex, 6995 float[] b, int bFromIndex, int bToIndex) { 6996 rangeCheck(a.length, aFromIndex, aToIndex); 6997 rangeCheck(b.length, bFromIndex, bToIndex); 6998 6999 int aLength = aToIndex - aFromIndex; 7000 int bLength = bToIndex - bFromIndex; 7001 int i = ArraysSupport.mismatch(a, aFromIndex, 7002 b, bFromIndex, 7003 Math.min(aLength, bLength)); 7004 if (i >= 0) { 7005 return Float.compare(a[aFromIndex + i], b[bFromIndex + i]); 7006 } 7007 7008 return aLength - bLength; 7009 } 7010 7011 // Compare double 7012 7013 /** 7014 * Compares two {@code double} arrays lexicographically. 7015 * 7016 * <p>If the two arrays share a common prefix then the lexicographic 7017 * comparison is the result of comparing two elements, as if by 7018 * {@link Double#compare(double, double)}, at an index within the respective 7019 * arrays that is the prefix length. 7020 * Otherwise, one array is a proper prefix of the other and, lexicographic 7021 * comparison is the result of comparing the two array lengths. 7022 * (See {@link #mismatch(double[], double[])} for the definition of a common 7023 * and proper prefix.) 7024 * 7025 * <p>A {@code null} array reference is considered lexicographically less 7026 * than a non-{@code null} array reference. Two {@code null} array 7027 * references are considered equal. 7028 * 7029 * <p>The comparison is consistent with {@link #equals(double[], double[]) equals}, 7030 * more specifically the following holds for arrays {@code a} and {@code b}: 7031 * <pre>{@code 7032 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 7033 * }</pre> 7034 * 7035 * @apiNote 7036 * <p>This method behaves as if (for non-{@code null} array references): 7037 * <pre>{@code 7038 * int i = Arrays.mismatch(a, b); 7039 * if (i >= 0 && i < Math.min(a.length, b.length)) 7040 * return Double.compare(a[i], b[i]); 7041 * return a.length - b.length; 7042 * }</pre> 7043 * 7044 * @param a the first array to compare 7045 * @param b the second array to compare 7046 * @return the value {@code 0} if the first and second array are equal and 7047 * contain the same elements in the same order; 7048 * a value less than {@code 0} if the first array is 7049 * lexicographically less than the second array; and 7050 * a value greater than {@code 0} if the first array is 7051 * lexicographically greater than the second array 7052 * @since 9 7053 */ 7054 public static int compare(double[] a, double[] b) { 7055 if (a == b) 7056 return 0; 7057 if (a == null || b == null) 7058 return a == null ? -1 : 1; 7059 7060 int i = ArraysSupport.mismatch(a, b, 7061 Math.min(a.length, b.length)); 7062 if (i >= 0) { 7063 return Double.compare(a[i], b[i]); 7064 } 7065 7066 return a.length - b.length; 7067 } 7068 7069 /** 7070 * Compares two {@code double} arrays lexicographically over the specified 7071 * ranges. 7072 * 7073 * <p>If the two arrays, over the specified ranges, share a common prefix 7074 * then the lexicographic comparison is the result of comparing two 7075 * elements, as if by {@link Double#compare(double, double)}, at a relative 7076 * index within the respective arrays that is the length of the prefix. 7077 * Otherwise, one array is a proper prefix of the other and, lexicographic 7078 * comparison is the result of comparing the two range lengths. 7079 * (See {@link #mismatch(double[], int, int, double[], int, int)} for the 7080 * definition of a common and proper prefix.) 7081 * 7082 * <p>The comparison is consistent with 7083 * {@link #equals(double[], int, int, double[], int, int) equals}, more 7084 * specifically the following holds for arrays {@code a} and {@code b} with 7085 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 7086 * [{@code bFromIndex}, {@code bToIndex}) respectively: 7087 * <pre>{@code 7088 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 7089 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 7090 * }</pre> 7091 * 7092 * @apiNote 7093 * <p>This method behaves as if: 7094 * <pre>{@code 7095 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 7096 * b, bFromIndex, bToIndex); 7097 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 7098 * return Double.compare(a[aFromIndex + i], b[bFromIndex + i]); 7099 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 7100 * }</pre> 7101 * 7102 * @param a the first array to compare 7103 * @param aFromIndex the index (inclusive) of the first element in the 7104 * first array to be compared 7105 * @param aToIndex the index (exclusive) of the last element in the 7106 * first array to be compared 7107 * @param b the second array to compare 7108 * @param bFromIndex the index (inclusive) of the first element in the 7109 * second array to be compared 7110 * @param bToIndex the index (exclusive) of the last element in the 7111 * second array to be compared 7112 * @return the value {@code 0} if, over the specified ranges, the first and 7113 * second array are equal and contain the same elements in the same 7114 * order; 7115 * a value less than {@code 0} if, over the specified ranges, the 7116 * first array is lexicographically less than the second array; and 7117 * a value greater than {@code 0} if, over the specified ranges, the 7118 * first array is lexicographically greater than the second array 7119 * @throws IllegalArgumentException 7120 * if {@code aFromIndex > aToIndex} or 7121 * if {@code bFromIndex > bToIndex} 7122 * @throws ArrayIndexOutOfBoundsException 7123 * if {@code aFromIndex < 0 or aToIndex > a.length} or 7124 * if {@code bFromIndex < 0 or bToIndex > b.length} 7125 * @throws NullPointerException 7126 * if either array is {@code null} 7127 * @since 9 7128 */ 7129 public static int compare(double[] a, int aFromIndex, int aToIndex, 7130 double[] b, int bFromIndex, int bToIndex) { 7131 rangeCheck(a.length, aFromIndex, aToIndex); 7132 rangeCheck(b.length, bFromIndex, bToIndex); 7133 7134 int aLength = aToIndex - aFromIndex; 7135 int bLength = bToIndex - bFromIndex; 7136 int i = ArraysSupport.mismatch(a, aFromIndex, 7137 b, bFromIndex, 7138 Math.min(aLength, bLength)); 7139 if (i >= 0) { 7140 return Double.compare(a[aFromIndex + i], b[bFromIndex + i]); 7141 } 7142 7143 return aLength - bLength; 7144 } 7145 7146 // Compare objects 7147 7148 /** 7149 * Compares two {@code Object} arrays, within comparable elements, 7150 * lexicographically. 7151 * 7152 * <p>If the two arrays share a common prefix then the lexicographic 7153 * comparison is the result of comparing two elements of type {@code T} at 7154 * an index {@code i} within the respective arrays that is the prefix 7155 * length, as if by: 7156 * <pre>{@code 7157 * Comparator.nullsFirst(Comparator.<T>naturalOrder()). 7158 * compare(a[i], b[i]) 7159 * }</pre> 7160 * Otherwise, one array is a proper prefix of the other and, lexicographic 7161 * comparison is the result of comparing the two array lengths. 7162 * (See {@link #mismatch(Object[], Object[])} for the definition of a common 7163 * and proper prefix.) 7164 * 7165 * <p>A {@code null} array reference is considered lexicographically less 7166 * than a non-{@code null} array reference. Two {@code null} array 7167 * references are considered equal. 7168 * A {@code null} array element is considered lexicographically less than a 7169 * non-{@code null} array element. Two {@code null} array elements are 7170 * considered equal. 7171 * 7172 * <p>The comparison is consistent with {@link #equals(Object[], Object[]) equals}, 7173 * more specifically the following holds for arrays {@code a} and {@code b}: 7174 * <pre>{@code 7175 * Arrays.equals(a, b) == (Arrays.compare(a, b) == 0) 7176 * }</pre> 7177 * 7178 * @apiNote 7179 * <p>This method behaves as if (for non-{@code null} array references 7180 * and elements): 7181 * <pre>{@code 7182 * int i = Arrays.mismatch(a, b); 7183 * if (i >= 0 && i < Math.min(a.length, b.length)) 7184 * return a[i].compareTo(b[i]); 7185 * return a.length - b.length; 7186 * }</pre> 7187 * 7188 * @param a the first array to compare 7189 * @param b the second array to compare 7190 * @param <T> the type of comparable array elements 7191 * @return the value {@code 0} if the first and second array are equal and 7192 * contain the same elements in the same order; 7193 * a value less than {@code 0} if the first array is 7194 * lexicographically less than the second array; and 7195 * a value greater than {@code 0} if the first array is 7196 * lexicographically greater than the second array 7197 * @since 9 7198 */ 7199 public static <T extends Comparable<? super T>> int compare(T[] a, T[] b) { 7200 if (a == b) 7201 return 0; 7202 // A null array is less than a non-null array 7203 if (a == null || b == null) 7204 return a == null ? -1 : 1; 7205 7206 int length = Math.min(a.length, b.length); 7207 for (int i = 0; i < length; i++) { 7208 T oa = a[i]; 7209 T ob = b[i]; 7210 if (oa != ob) { 7211 // A null element is less than a non-null element 7212 if (oa == null || ob == null) 7213 return oa == null ? -1 : 1; 7214 int v = oa.compareTo(ob); 7215 if (v != 0) { 7216 return v; 7217 } 7218 } 7219 } 7220 7221 return a.length - b.length; 7222 } 7223 7224 /** 7225 * Compares two {@code Object} arrays lexicographically over the specified 7226 * ranges. 7227 * 7228 * <p>If the two arrays, over the specified ranges, share a common prefix 7229 * then the lexicographic comparison is the result of comparing two 7230 * elements of type {@code T} at a relative index {@code i} within the 7231 * respective arrays that is the prefix length, as if by: 7232 * <pre>{@code 7233 * Comparator.nullsFirst(Comparator.<T>naturalOrder()). 7234 * compare(a[aFromIndex + i, b[bFromIndex + i]) 7235 * }</pre> 7236 * Otherwise, one array is a proper prefix of the other and, lexicographic 7237 * comparison is the result of comparing the two range lengths. 7238 * (See {@link #mismatch(Object[], int, int, Object[], int, int)} for the 7239 * definition of a common and proper prefix.) 7240 * 7241 * <p>The comparison is consistent with 7242 * {@link #equals(Object[], int, int, Object[], int, int) equals}, more 7243 * specifically the following holds for arrays {@code a} and {@code b} with 7244 * specified ranges [{@code aFromIndex}, {@code aToIndex}) and 7245 * [{@code bFromIndex}, {@code bToIndex}) respectively: 7246 * <pre>{@code 7247 * Arrays.equals(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 7248 * (Arrays.compare(a, aFromIndex, aToIndex, b, bFromIndex, bToIndex) == 0) 7249 * }</pre> 7250 * 7251 * @apiNote 7252 * <p>This method behaves as if (for non-{@code null} array elements): 7253 * <pre>{@code 7254 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 7255 * b, bFromIndex, bToIndex); 7256 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 7257 * return a[aFromIndex + i].compareTo(b[bFromIndex + i]); 7258 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 7259 * }</pre> 7260 * 7261 * @param a the first array to compare 7262 * @param aFromIndex the index (inclusive) of the first element in the 7263 * first array to be compared 7264 * @param aToIndex the index (exclusive) of the last element in the 7265 * first array to be compared 7266 * @param b the second array to compare 7267 * @param bFromIndex the index (inclusive) of the first element in the 7268 * second array to be compared 7269 * @param bToIndex the index (exclusive) of the last element in the 7270 * second array to be compared 7271 * @param <T> the type of comparable array elements 7272 * @return the value {@code 0} if, over the specified ranges, the first and 7273 * second array are equal and contain the same elements in the same 7274 * order; 7275 * a value less than {@code 0} if, over the specified ranges, the 7276 * first array is lexicographically less than the second array; and 7277 * a value greater than {@code 0} if, over the specified ranges, the 7278 * first array is lexicographically greater than the second array 7279 * @throws IllegalArgumentException 7280 * if {@code aFromIndex > aToIndex} or 7281 * if {@code bFromIndex > bToIndex} 7282 * @throws ArrayIndexOutOfBoundsException 7283 * if {@code aFromIndex < 0 or aToIndex > a.length} or 7284 * if {@code bFromIndex < 0 or bToIndex > b.length} 7285 * @throws NullPointerException 7286 * if either array is {@code null} 7287 * @since 9 7288 */ 7289 public static <T extends Comparable<? super T>> int compare( 7290 T[] a, int aFromIndex, int aToIndex, 7291 T[] b, int bFromIndex, int bToIndex) { 7292 rangeCheck(a.length, aFromIndex, aToIndex); 7293 rangeCheck(b.length, bFromIndex, bToIndex); 7294 7295 int aLength = aToIndex - aFromIndex; 7296 int bLength = bToIndex - bFromIndex; 7297 int length = Math.min(aLength, bLength); 7298 for (int i = 0; i < length; i++) { 7299 T oa = a[aFromIndex++]; 7300 T ob = b[bFromIndex++]; 7301 if (oa != ob) { 7302 if (oa == null || ob == null) 7303 return oa == null ? -1 : 1; 7304 int v = oa.compareTo(ob); 7305 if (v != 0) { 7306 return v; 7307 } 7308 } 7309 } 7310 7311 return aLength - bLength; 7312 } 7313 7314 /** 7315 * Compares two {@code Object} arrays lexicographically using a specified 7316 * comparator. 7317 * 7318 * <p>If the two arrays share a common prefix then the lexicographic 7319 * comparison is the result of comparing with the specified comparator two 7320 * elements at an index within the respective arrays that is the prefix 7321 * length. 7322 * Otherwise, one array is a proper prefix of the other and, lexicographic 7323 * comparison is the result of comparing the two array lengths. 7324 * (See {@link #mismatch(Object[], Object[])} for the definition of a common 7325 * and proper prefix.) 7326 * 7327 * <p>A {@code null} array reference is considered lexicographically less 7328 * than a non-{@code null} array reference. Two {@code null} array 7329 * references are considered equal. 7330 * 7331 * @apiNote 7332 * <p>This method behaves as if (for non-{@code null} array references): 7333 * <pre>{@code 7334 * int i = Arrays.mismatch(a, b, cmp); 7335 * if (i >= 0 && i < Math.min(a.length, b.length)) 7336 * return cmp.compare(a[i], b[i]); 7337 * return a.length - b.length; 7338 * }</pre> 7339 * 7340 * @param a the first array to compare 7341 * @param b the second array to compare 7342 * @param cmp the comparator to compare array elements 7343 * @param <T> the type of array elements 7344 * @return the value {@code 0} if the first and second array are equal and 7345 * contain the same elements in the same order; 7346 * a value less than {@code 0} if the first array is 7347 * lexicographically less than the second array; and 7348 * a value greater than {@code 0} if the first array is 7349 * lexicographically greater than the second array 7350 * @throws NullPointerException if the comparator is {@code null} 7351 * @since 9 7352 */ 7353 public static <T> int compare(T[] a, T[] b, 7354 Comparator<? super T> cmp) { 7355 Objects.requireNonNull(cmp); 7356 if (a == b) 7357 return 0; 7358 if (a == null || b == null) 7359 return a == null ? -1 : 1; 7360 7361 int length = Math.min(a.length, b.length); 7362 for (int i = 0; i < length; i++) { 7363 T oa = a[i]; 7364 T ob = b[i]; 7365 if (oa != ob) { 7366 // Null-value comparison is deferred to the comparator 7367 int v = cmp.compare(oa, ob); 7368 if (v != 0) { 7369 return v; 7370 } 7371 } 7372 } 7373 7374 return a.length - b.length; 7375 } 7376 7377 /** 7378 * Compares two {@code Object} arrays lexicographically over the specified 7379 * ranges. 7380 * 7381 * <p>If the two arrays, over the specified ranges, share a common prefix 7382 * then the lexicographic comparison is the result of comparing with the 7383 * specified comparator two elements at a relative index within the 7384 * respective arrays that is the prefix length. 7385 * Otherwise, one array is a proper prefix of the other and, lexicographic 7386 * comparison is the result of comparing the two range lengths. 7387 * (See {@link #mismatch(Object[], int, int, Object[], int, int)} for the 7388 * definition of a common and proper prefix.) 7389 * 7390 * @apiNote 7391 * <p>This method behaves as if (for non-{@code null} array elements): 7392 * <pre>{@code 7393 * int i = Arrays.mismatch(a, aFromIndex, aToIndex, 7394 * b, bFromIndex, bToIndex, cmp); 7395 * if (i >= 0 && i < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 7396 * return cmp.compare(a[aFromIndex + i], b[bFromIndex + i]); 7397 * return (aToIndex - aFromIndex) - (bToIndex - bFromIndex); 7398 * }</pre> 7399 * 7400 * @param a the first array to compare 7401 * @param aFromIndex the index (inclusive) of the first element in the 7402 * first array to be compared 7403 * @param aToIndex the index (exclusive) of the last element in the 7404 * first array to be compared 7405 * @param b the second array to compare 7406 * @param bFromIndex the index (inclusive) of the first element in the 7407 * second array to be compared 7408 * @param bToIndex the index (exclusive) of the last element in the 7409 * second array to be compared 7410 * @param cmp the comparator to compare array elements 7411 * @param <T> the type of array elements 7412 * @return the value {@code 0} if, over the specified ranges, the first and 7413 * second array are equal and contain the same elements in the same 7414 * order; 7415 * a value less than {@code 0} if, over the specified ranges, the 7416 * first array is lexicographically less than the second array; and 7417 * a value greater than {@code 0} if, over the specified ranges, the 7418 * first array is lexicographically greater than the second array 7419 * @throws IllegalArgumentException 7420 * if {@code aFromIndex > aToIndex} or 7421 * if {@code bFromIndex > bToIndex} 7422 * @throws ArrayIndexOutOfBoundsException 7423 * if {@code aFromIndex < 0 or aToIndex > a.length} or 7424 * if {@code bFromIndex < 0 or bToIndex > b.length} 7425 * @throws NullPointerException 7426 * if either array or the comparator is {@code null} 7427 * @since 9 7428 */ 7429 public static <T> int compare( 7430 T[] a, int aFromIndex, int aToIndex, 7431 T[] b, int bFromIndex, int bToIndex, 7432 Comparator<? super T> cmp) { 7433 Objects.requireNonNull(cmp); 7434 rangeCheck(a.length, aFromIndex, aToIndex); 7435 rangeCheck(b.length, bFromIndex, bToIndex); 7436 7437 int aLength = aToIndex - aFromIndex; 7438 int bLength = bToIndex - bFromIndex; 7439 int length = Math.min(aLength, bLength); 7440 for (int i = 0; i < length; i++) { 7441 T oa = a[aFromIndex++]; 7442 T ob = b[bFromIndex++]; 7443 if (oa != ob) { 7444 // Null-value comparison is deferred to the comparator 7445 int v = cmp.compare(oa, ob); 7446 if (v != 0) { 7447 return v; 7448 } 7449 } 7450 } 7451 7452 return aLength - bLength; 7453 } 7454 7455 7456 // Mismatch methods 7457 7458 // Mismatch boolean 7459 7460 /** 7461 * Finds and returns the index of the first mismatch between two 7462 * {@code boolean} arrays, otherwise return -1 if no mismatch is found. The 7463 * index will be in the range of 0 (inclusive) up to the length (inclusive) 7464 * of the smaller array. 7465 * 7466 * <p>If the two arrays share a common prefix then the returned index is the 7467 * length of the common prefix and it follows that there is a mismatch 7468 * between the two elements at that index within the respective arrays. 7469 * If one array is a proper prefix of the other then the returned index is 7470 * the length of the smaller array and it follows that the index is only 7471 * valid for the larger array. 7472 * Otherwise, there is no mismatch. 7473 * 7474 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 7475 * prefix of length {@code pl} if the following expression is true: 7476 * <pre>{@code 7477 * pl >= 0 && 7478 * pl < Math.min(a.length, b.length) && 7479 * Arrays.equals(a, 0, pl, b, 0, pl) && 7480 * a[pl] != b[pl] 7481 * }</pre> 7482 * Note that a common prefix length of {@code 0} indicates that the first 7483 * elements from each array mismatch. 7484 * 7485 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 7486 * prefix if the following expression is true: 7487 * <pre>{@code 7488 * a.length != b.length && 7489 * Arrays.equals(a, 0, Math.min(a.length, b.length), 7490 * b, 0, Math.min(a.length, b.length)) 7491 * }</pre> 7492 * 7493 * @param a the first array to be tested for a mismatch 7494 * @param b the second array to be tested for a mismatch 7495 * @return the index of the first mismatch between the two arrays, 7496 * otherwise {@code -1}. 7497 * @throws NullPointerException 7498 * if either array is {@code null} 7499 * @since 9 7500 */ 7501 public static int mismatch(boolean[] a, boolean[] b) { 7502 int length = Math.min(a.length, b.length); // Check null array refs 7503 if (a == b) 7504 return -1; 7505 7506 int i = ArraysSupport.mismatch(a, b, length); 7507 return (i < 0 && a.length != b.length) ? length : i; 7508 } 7509 7510 /** 7511 * Finds and returns the relative index of the first mismatch between two 7512 * {@code boolean} arrays over the specified ranges, otherwise return -1 if 7513 * no mismatch is found. The index will be in the range of 0 (inclusive) up 7514 * to the length (inclusive) of the smaller range. 7515 * 7516 * <p>If the two arrays, over the specified ranges, share a common prefix 7517 * then the returned relative index is the length of the common prefix and 7518 * it follows that there is a mismatch between the two elements at that 7519 * relative index within the respective arrays. 7520 * If one array is a proper prefix of the other, over the specified ranges, 7521 * then the returned relative index is the length of the smaller range and 7522 * it follows that the relative index is only valid for the array with the 7523 * larger range. 7524 * Otherwise, there is no mismatch. 7525 * 7526 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 7527 * ranges [{@code aFromIndex}, {@code aToIndex}) and 7528 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 7529 * prefix of length {@code pl} if the following expression is true: 7530 * <pre>{@code 7531 * pl >= 0 && 7532 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 7533 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 7534 * a[aFromIndex + pl] != b[bFromIndex + pl] 7535 * }</pre> 7536 * Note that a common prefix length of {@code 0} indicates that the first 7537 * elements from each array mismatch. 7538 * 7539 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 7540 * ranges [{@code aFromIndex}, {@code aToIndex}) and 7541 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 7542 * prefix if the following expression is true: 7543 * <pre>{@code 7544 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 7545 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 7546 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 7547 * }</pre> 7548 * 7549 * @param a the first array to be tested for a mismatch 7550 * @param aFromIndex the index (inclusive) of the first element in the 7551 * first array to be tested 7552 * @param aToIndex the index (exclusive) of the last element in the 7553 * first array to be tested 7554 * @param b the second array to be tested for a mismatch 7555 * @param bFromIndex the index (inclusive) of the first element in the 7556 * second array to be tested 7557 * @param bToIndex the index (exclusive) of the last element in the 7558 * second array to be tested 7559 * @return the relative index of the first mismatch between the two arrays 7560 * over the specified ranges, otherwise {@code -1}. 7561 * @throws IllegalArgumentException 7562 * if {@code aFromIndex > aToIndex} or 7563 * if {@code bFromIndex > bToIndex} 7564 * @throws ArrayIndexOutOfBoundsException 7565 * if {@code aFromIndex < 0 or aToIndex > a.length} or 7566 * if {@code bFromIndex < 0 or bToIndex > b.length} 7567 * @throws NullPointerException 7568 * if either array is {@code null} 7569 * @since 9 7570 */ 7571 public static int mismatch(boolean[] a, int aFromIndex, int aToIndex, 7572 boolean[] b, int bFromIndex, int bToIndex) { 7573 rangeCheck(a.length, aFromIndex, aToIndex); 7574 rangeCheck(b.length, bFromIndex, bToIndex); 7575 7576 int aLength = aToIndex - aFromIndex; 7577 int bLength = bToIndex - bFromIndex; 7578 int length = Math.min(aLength, bLength); 7579 int i = ArraysSupport.mismatch(a, aFromIndex, 7580 b, bFromIndex, 7581 length); 7582 return (i < 0 && aLength != bLength) ? length : i; 7583 } 7584 7585 // Mismatch byte 7586 7587 /** 7588 * Finds and returns the index of the first mismatch between two {@code byte} 7589 * arrays, otherwise return -1 if no mismatch is found. The index will be 7590 * in the range of 0 (inclusive) up to the length (inclusive) of the smaller 7591 * array. 7592 * 7593 * <p>If the two arrays share a common prefix then the returned index is the 7594 * length of the common prefix and it follows that there is a mismatch 7595 * between the two elements at that index within the respective arrays. 7596 * If one array is a proper prefix of the other then the returned index is 7597 * the length of the smaller array and it follows that the index is only 7598 * valid for the larger array. 7599 * Otherwise, there is no mismatch. 7600 * 7601 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 7602 * prefix of length {@code pl} if the following expression is true: 7603 * <pre>{@code 7604 * pl >= 0 && 7605 * pl < Math.min(a.length, b.length) && 7606 * Arrays.equals(a, 0, pl, b, 0, pl) && 7607 * a[pl] != b[pl] 7608 * }</pre> 7609 * Note that a common prefix length of {@code 0} indicates that the first 7610 * elements from each array mismatch. 7611 * 7612 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 7613 * prefix if the following expression is true: 7614 * <pre>{@code 7615 * a.length != b.length && 7616 * Arrays.equals(a, 0, Math.min(a.length, b.length), 7617 * b, 0, Math.min(a.length, b.length)) 7618 * }</pre> 7619 * 7620 * @param a the first array to be tested for a mismatch 7621 * @param b the second array to be tested for a mismatch 7622 * @return the index of the first mismatch between the two arrays, 7623 * otherwise {@code -1}. 7624 * @throws NullPointerException 7625 * if either array is {@code null} 7626 * @since 9 7627 */ 7628 public static int mismatch(byte[] a, byte[] b) { 7629 int length = Math.min(a.length, b.length); // Check null array refs 7630 if (a == b) 7631 return -1; 7632 7633 int i = ArraysSupport.mismatch(a, b, length); 7634 return (i < 0 && a.length != b.length) ? length : i; 7635 } 7636 7637 /** 7638 * Finds and returns the relative index of the first mismatch between two 7639 * {@code byte} arrays over the specified ranges, otherwise return -1 if no 7640 * mismatch is found. The index will be in the range of 0 (inclusive) up to 7641 * the length (inclusive) of the smaller range. 7642 * 7643 * <p>If the two arrays, over the specified ranges, share a common prefix 7644 * then the returned relative index is the length of the common prefix and 7645 * it follows that there is a mismatch between the two elements at that 7646 * relative index within the respective arrays. 7647 * If one array is a proper prefix of the other, over the specified ranges, 7648 * then the returned relative index is the length of the smaller range and 7649 * it follows that the relative index is only valid for the array with the 7650 * larger range. 7651 * Otherwise, there is no mismatch. 7652 * 7653 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 7654 * ranges [{@code aFromIndex}, {@code aToIndex}) and 7655 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 7656 * prefix of length {@code pl} if the following expression is true: 7657 * <pre>{@code 7658 * pl >= 0 && 7659 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 7660 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 7661 * a[aFromIndex + pl] != b[bFromIndex + pl] 7662 * }</pre> 7663 * Note that a common prefix length of {@code 0} indicates that the first 7664 * elements from each array mismatch. 7665 * 7666 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 7667 * ranges [{@code aFromIndex}, {@code aToIndex}) and 7668 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 7669 * prefix if the following expression is true: 7670 * <pre>{@code 7671 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 7672 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 7673 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 7674 * }</pre> 7675 * 7676 * @param a the first array to be tested for a mismatch 7677 * @param aFromIndex the index (inclusive) of the first element in the 7678 * first array to be tested 7679 * @param aToIndex the index (exclusive) of the last element in the 7680 * first array to be tested 7681 * @param b the second array to be tested for a mismatch 7682 * @param bFromIndex the index (inclusive) of the first element in the 7683 * second array to be tested 7684 * @param bToIndex the index (exclusive) of the last element in the 7685 * second array to be tested 7686 * @return the relative index of the first mismatch between the two arrays 7687 * over the specified ranges, otherwise {@code -1}. 7688 * @throws IllegalArgumentException 7689 * if {@code aFromIndex > aToIndex} or 7690 * if {@code bFromIndex > bToIndex} 7691 * @throws ArrayIndexOutOfBoundsException 7692 * if {@code aFromIndex < 0 or aToIndex > a.length} or 7693 * if {@code bFromIndex < 0 or bToIndex > b.length} 7694 * @throws NullPointerException 7695 * if either array is {@code null} 7696 * @since 9 7697 */ 7698 public static int mismatch(byte[] a, int aFromIndex, int aToIndex, 7699 byte[] b, int bFromIndex, int bToIndex) { 7700 rangeCheck(a.length, aFromIndex, aToIndex); 7701 rangeCheck(b.length, bFromIndex, bToIndex); 7702 7703 int aLength = aToIndex - aFromIndex; 7704 int bLength = bToIndex - bFromIndex; 7705 int length = Math.min(aLength, bLength); 7706 int i = ArraysSupport.mismatch(a, aFromIndex, 7707 b, bFromIndex, 7708 length); 7709 return (i < 0 && aLength != bLength) ? length : i; 7710 } 7711 7712 // Mismatch char 7713 7714 /** 7715 * Finds and returns the index of the first mismatch between two {@code char} 7716 * arrays, otherwise return -1 if no mismatch is found. The index will be 7717 * in the range of 0 (inclusive) up to the length (inclusive) of the smaller 7718 * array. 7719 * 7720 * <p>If the two arrays share a common prefix then the returned index is the 7721 * length of the common prefix and it follows that there is a mismatch 7722 * between the two elements at that index within the respective arrays. 7723 * If one array is a proper prefix of the other then the returned index is 7724 * the length of the smaller array and it follows that the index is only 7725 * valid for the larger array. 7726 * Otherwise, there is no mismatch. 7727 * 7728 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 7729 * prefix of length {@code pl} if the following expression is true: 7730 * <pre>{@code 7731 * pl >= 0 && 7732 * pl < Math.min(a.length, b.length) && 7733 * Arrays.equals(a, 0, pl, b, 0, pl) && 7734 * a[pl] != b[pl] 7735 * }</pre> 7736 * Note that a common prefix length of {@code 0} indicates that the first 7737 * elements from each array mismatch. 7738 * 7739 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 7740 * prefix if the following expression is true: 7741 * <pre>{@code 7742 * a.length != b.length && 7743 * Arrays.equals(a, 0, Math.min(a.length, b.length), 7744 * b, 0, Math.min(a.length, b.length)) 7745 * }</pre> 7746 * 7747 * @param a the first array to be tested for a mismatch 7748 * @param b the second array to be tested for a mismatch 7749 * @return the index of the first mismatch between the two arrays, 7750 * otherwise {@code -1}. 7751 * @throws NullPointerException 7752 * if either array is {@code null} 7753 * @since 9 7754 */ 7755 public static int mismatch(char[] a, char[] b) { 7756 int length = Math.min(a.length, b.length); // Check null array refs 7757 if (a == b) 7758 return -1; 7759 7760 int i = ArraysSupport.mismatch(a, b, length); 7761 return (i < 0 && a.length != b.length) ? length : i; 7762 } 7763 7764 /** 7765 * Finds and returns the relative index of the first mismatch between two 7766 * {@code char} arrays over the specified ranges, otherwise return -1 if no 7767 * mismatch is found. The index will be in the range of 0 (inclusive) up to 7768 * the length (inclusive) of the smaller range. 7769 * 7770 * <p>If the two arrays, over the specified ranges, share a common prefix 7771 * then the returned relative index is the length of the common prefix and 7772 * it follows that there is a mismatch between the two elements at that 7773 * relative index within the respective arrays. 7774 * If one array is a proper prefix of the other, over the specified ranges, 7775 * then the returned relative index is the length of the smaller range and 7776 * it follows that the relative index is only valid for the array with the 7777 * larger range. 7778 * Otherwise, there is no mismatch. 7779 * 7780 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 7781 * ranges [{@code aFromIndex}, {@code aToIndex}) and 7782 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 7783 * prefix of length {@code pl} if the following expression is true: 7784 * <pre>{@code 7785 * pl >= 0 && 7786 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 7787 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 7788 * a[aFromIndex + pl] != b[bFromIndex + pl] 7789 * }</pre> 7790 * Note that a common prefix length of {@code 0} indicates that the first 7791 * elements from each array mismatch. 7792 * 7793 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 7794 * ranges [{@code aFromIndex}, {@code aToIndex}) and 7795 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 7796 * prefix if the following expression is true: 7797 * <pre>{@code 7798 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 7799 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 7800 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 7801 * }</pre> 7802 * 7803 * @param a the first array to be tested for a mismatch 7804 * @param aFromIndex the index (inclusive) of the first element in the 7805 * first array to be tested 7806 * @param aToIndex the index (exclusive) of the last element in the 7807 * first array to be tested 7808 * @param b the second array to be tested for a mismatch 7809 * @param bFromIndex the index (inclusive) of the first element in the 7810 * second array to be tested 7811 * @param bToIndex the index (exclusive) of the last element in the 7812 * second array to be tested 7813 * @return the relative index of the first mismatch between the two arrays 7814 * over the specified ranges, otherwise {@code -1}. 7815 * @throws IllegalArgumentException 7816 * if {@code aFromIndex > aToIndex} or 7817 * if {@code bFromIndex > bToIndex} 7818 * @throws ArrayIndexOutOfBoundsException 7819 * if {@code aFromIndex < 0 or aToIndex > a.length} or 7820 * if {@code bFromIndex < 0 or bToIndex > b.length} 7821 * @throws NullPointerException 7822 * if either array is {@code null} 7823 * @since 9 7824 */ 7825 public static int mismatch(char[] a, int aFromIndex, int aToIndex, 7826 char[] b, int bFromIndex, int bToIndex) { 7827 rangeCheck(a.length, aFromIndex, aToIndex); 7828 rangeCheck(b.length, bFromIndex, bToIndex); 7829 7830 int aLength = aToIndex - aFromIndex; 7831 int bLength = bToIndex - bFromIndex; 7832 int length = Math.min(aLength, bLength); 7833 int i = ArraysSupport.mismatch(a, aFromIndex, 7834 b, bFromIndex, 7835 length); 7836 return (i < 0 && aLength != bLength) ? length : i; 7837 } 7838 7839 // Mismatch short 7840 7841 /** 7842 * Finds and returns the index of the first mismatch between two {@code short} 7843 * arrays, otherwise return -1 if no mismatch is found. The index will be 7844 * in the range of 0 (inclusive) up to the length (inclusive) of the smaller 7845 * array. 7846 * 7847 * <p>If the two arrays share a common prefix then the returned index is the 7848 * length of the common prefix and it follows that there is a mismatch 7849 * between the two elements at that index within the respective arrays. 7850 * If one array is a proper prefix of the other then the returned index is 7851 * the length of the smaller array and it follows that the index is only 7852 * valid for the larger array. 7853 * Otherwise, there is no mismatch. 7854 * 7855 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 7856 * prefix of length {@code pl} if the following expression is true: 7857 * <pre>{@code 7858 * pl >= 0 && 7859 * pl < Math.min(a.length, b.length) && 7860 * Arrays.equals(a, 0, pl, b, 0, pl) && 7861 * a[pl] != b[pl] 7862 * }</pre> 7863 * Note that a common prefix length of {@code 0} indicates that the first 7864 * elements from each array mismatch. 7865 * 7866 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 7867 * prefix if the following expression is true: 7868 * <pre>{@code 7869 * a.length != b.length && 7870 * Arrays.equals(a, 0, Math.min(a.length, b.length), 7871 * b, 0, Math.min(a.length, b.length)) 7872 * }</pre> 7873 * 7874 * @param a the first array to be tested for a mismatch 7875 * @param b the second array to be tested for a mismatch 7876 * @return the index of the first mismatch between the two arrays, 7877 * otherwise {@code -1}. 7878 * @throws NullPointerException 7879 * if either array is {@code null} 7880 * @since 9 7881 */ 7882 public static int mismatch(short[] a, short[] b) { 7883 int length = Math.min(a.length, b.length); // Check null array refs 7884 if (a == b) 7885 return -1; 7886 7887 int i = ArraysSupport.mismatch(a, b, length); 7888 return (i < 0 && a.length != b.length) ? length : i; 7889 } 7890 7891 /** 7892 * Finds and returns the relative index of the first mismatch between two 7893 * {@code short} arrays over the specified ranges, otherwise return -1 if no 7894 * mismatch is found. The index will be in the range of 0 (inclusive) up to 7895 * the length (inclusive) of the smaller range. 7896 * 7897 * <p>If the two arrays, over the specified ranges, share a common prefix 7898 * then the returned relative index is the length of the common prefix and 7899 * it follows that there is a mismatch between the two elements at that 7900 * relative index within the respective arrays. 7901 * If one array is a proper prefix of the other, over the specified ranges, 7902 * then the returned relative index is the length of the smaller range and 7903 * it follows that the relative index is only valid for the array with the 7904 * larger range. 7905 * Otherwise, there is no mismatch. 7906 * 7907 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 7908 * ranges [{@code aFromIndex}, {@code aToIndex}) and 7909 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 7910 * prefix of length {@code pl} if the following expression is true: 7911 * <pre>{@code 7912 * pl >= 0 && 7913 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 7914 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 7915 * a[aFromIndex + pl] != b[bFromIndex + pl] 7916 * }</pre> 7917 * Note that a common prefix length of {@code 0} indicates that the first 7918 * elements from each array mismatch. 7919 * 7920 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 7921 * ranges [{@code aFromIndex}, {@code aToIndex}) and 7922 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 7923 * prefix if the following expression is true: 7924 * <pre>{@code 7925 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 7926 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 7927 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 7928 * }</pre> 7929 * 7930 * @param a the first array to be tested for a mismatch 7931 * @param aFromIndex the index (inclusive) of the first element in the 7932 * first array to be tested 7933 * @param aToIndex the index (exclusive) of the last element in the 7934 * first array to be tested 7935 * @param b the second array to be tested for a mismatch 7936 * @param bFromIndex the index (inclusive) of the first element in the 7937 * second array to be tested 7938 * @param bToIndex the index (exclusive) of the last element in the 7939 * second array to be tested 7940 * @return the relative index of the first mismatch between the two arrays 7941 * over the specified ranges, otherwise {@code -1}. 7942 * @throws IllegalArgumentException 7943 * if {@code aFromIndex > aToIndex} or 7944 * if {@code bFromIndex > bToIndex} 7945 * @throws ArrayIndexOutOfBoundsException 7946 * if {@code aFromIndex < 0 or aToIndex > a.length} or 7947 * if {@code bFromIndex < 0 or bToIndex > b.length} 7948 * @throws NullPointerException 7949 * if either array is {@code null} 7950 * @since 9 7951 */ 7952 public static int mismatch(short[] a, int aFromIndex, int aToIndex, 7953 short[] b, int bFromIndex, int bToIndex) { 7954 rangeCheck(a.length, aFromIndex, aToIndex); 7955 rangeCheck(b.length, bFromIndex, bToIndex); 7956 7957 int aLength = aToIndex - aFromIndex; 7958 int bLength = bToIndex - bFromIndex; 7959 int length = Math.min(aLength, bLength); 7960 int i = ArraysSupport.mismatch(a, aFromIndex, 7961 b, bFromIndex, 7962 length); 7963 return (i < 0 && aLength != bLength) ? length : i; 7964 } 7965 7966 // Mismatch int 7967 7968 /** 7969 * Finds and returns the index of the first mismatch between two {@code int} 7970 * arrays, otherwise return -1 if no mismatch is found. The index will be 7971 * in the range of 0 (inclusive) up to the length (inclusive) of the smaller 7972 * array. 7973 * 7974 * <p>If the two arrays share a common prefix then the returned index is the 7975 * length of the common prefix and it follows that there is a mismatch 7976 * between the two elements at that index within the respective arrays. 7977 * If one array is a proper prefix of the other then the returned index is 7978 * the length of the smaller array and it follows that the index is only 7979 * valid for the larger array. 7980 * Otherwise, there is no mismatch. 7981 * 7982 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 7983 * prefix of length {@code pl} if the following expression is true: 7984 * <pre>{@code 7985 * pl >= 0 && 7986 * pl < Math.min(a.length, b.length) && 7987 * Arrays.equals(a, 0, pl, b, 0, pl) && 7988 * a[pl] != b[pl] 7989 * }</pre> 7990 * Note that a common prefix length of {@code 0} indicates that the first 7991 * elements from each array mismatch. 7992 * 7993 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 7994 * prefix if the following expression is true: 7995 * <pre>{@code 7996 * a.length != b.length && 7997 * Arrays.equals(a, 0, Math.min(a.length, b.length), 7998 * b, 0, Math.min(a.length, b.length)) 7999 * }</pre> 8000 * 8001 * @param a the first array to be tested for a mismatch 8002 * @param b the second array to be tested for a mismatch 8003 * @return the index of the first mismatch between the two arrays, 8004 * otherwise {@code -1}. 8005 * @throws NullPointerException 8006 * if either array is {@code null} 8007 * @since 9 8008 */ 8009 public static int mismatch(int[] a, int[] b) { 8010 int length = Math.min(a.length, b.length); // Check null array refs 8011 if (a == b) 8012 return -1; 8013 8014 int i = ArraysSupport.mismatch(a, b, length); 8015 return (i < 0 && a.length != b.length) ? length : i; 8016 } 8017 8018 /** 8019 * Finds and returns the relative index of the first mismatch between two 8020 * {@code int} arrays over the specified ranges, otherwise return -1 if no 8021 * mismatch is found. The index will be in the range of 0 (inclusive) up to 8022 * the length (inclusive) of the smaller range. 8023 * 8024 * <p>If the two arrays, over the specified ranges, share a common prefix 8025 * then the returned relative index is the length of the common prefix and 8026 * it follows that there is a mismatch between the two elements at that 8027 * relative index within the respective arrays. 8028 * If one array is a proper prefix of the other, over the specified ranges, 8029 * then the returned relative index is the length of the smaller range and 8030 * it follows that the relative index is only valid for the array with the 8031 * larger range. 8032 * Otherwise, there is no mismatch. 8033 * 8034 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8035 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8036 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 8037 * prefix of length {@code pl} if the following expression is true: 8038 * <pre>{@code 8039 * pl >= 0 && 8040 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 8041 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 8042 * a[aFromIndex + pl] != b[bFromIndex + pl] 8043 * }</pre> 8044 * Note that a common prefix length of {@code 0} indicates that the first 8045 * elements from each array mismatch. 8046 * 8047 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8048 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8049 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 8050 * prefix if the following expression is true: 8051 * <pre>{@code 8052 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 8053 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 8054 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 8055 * }</pre> 8056 * 8057 * @param a the first array to be tested for a mismatch 8058 * @param aFromIndex the index (inclusive) of the first element in the 8059 * first array to be tested 8060 * @param aToIndex the index (exclusive) of the last element in the 8061 * first array to be tested 8062 * @param b the second array to be tested for a mismatch 8063 * @param bFromIndex the index (inclusive) of the first element in the 8064 * second array to be tested 8065 * @param bToIndex the index (exclusive) of the last element in the 8066 * second array to be tested 8067 * @return the relative index of the first mismatch between the two arrays 8068 * over the specified ranges, otherwise {@code -1}. 8069 * @throws IllegalArgumentException 8070 * if {@code aFromIndex > aToIndex} or 8071 * if {@code bFromIndex > bToIndex} 8072 * @throws ArrayIndexOutOfBoundsException 8073 * if {@code aFromIndex < 0 or aToIndex > a.length} or 8074 * if {@code bFromIndex < 0 or bToIndex > b.length} 8075 * @throws NullPointerException 8076 * if either array is {@code null} 8077 * @since 9 8078 */ 8079 public static int mismatch(int[] a, int aFromIndex, int aToIndex, 8080 int[] b, int bFromIndex, int bToIndex) { 8081 rangeCheck(a.length, aFromIndex, aToIndex); 8082 rangeCheck(b.length, bFromIndex, bToIndex); 8083 8084 int aLength = aToIndex - aFromIndex; 8085 int bLength = bToIndex - bFromIndex; 8086 int length = Math.min(aLength, bLength); 8087 int i = ArraysSupport.mismatch(a, aFromIndex, 8088 b, bFromIndex, 8089 length); 8090 return (i < 0 && aLength != bLength) ? length : i; 8091 } 8092 8093 // Mismatch long 8094 8095 /** 8096 * Finds and returns the index of the first mismatch between two {@code long} 8097 * arrays, otherwise return -1 if no mismatch is found. The index will be 8098 * in the range of 0 (inclusive) up to the length (inclusive) of the smaller 8099 * array. 8100 * 8101 * <p>If the two arrays share a common prefix then the returned index is the 8102 * length of the common prefix and it follows that there is a mismatch 8103 * between the two elements at that index within the respective arrays. 8104 * If one array is a proper prefix of the other then the returned index is 8105 * the length of the smaller array and it follows that the index is only 8106 * valid for the larger array. 8107 * Otherwise, there is no mismatch. 8108 * 8109 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 8110 * prefix of length {@code pl} if the following expression is true: 8111 * <pre>{@code 8112 * pl >= 0 && 8113 * pl < Math.min(a.length, b.length) && 8114 * Arrays.equals(a, 0, pl, b, 0, pl) && 8115 * a[pl] != b[pl] 8116 * }</pre> 8117 * Note that a common prefix length of {@code 0} indicates that the first 8118 * elements from each array mismatch. 8119 * 8120 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 8121 * prefix if the following expression is true: 8122 * <pre>{@code 8123 * a.length != b.length && 8124 * Arrays.equals(a, 0, Math.min(a.length, b.length), 8125 * b, 0, Math.min(a.length, b.length)) 8126 * }</pre> 8127 * 8128 * @param a the first array to be tested for a mismatch 8129 * @param b the second array to be tested for a mismatch 8130 * @return the index of the first mismatch between the two arrays, 8131 * otherwise {@code -1}. 8132 * @throws NullPointerException 8133 * if either array is {@code null} 8134 * @since 9 8135 */ 8136 public static int mismatch(long[] a, long[] b) { 8137 int length = Math.min(a.length, b.length); // Check null array refs 8138 if (a == b) 8139 return -1; 8140 8141 int i = ArraysSupport.mismatch(a, b, length); 8142 return (i < 0 && a.length != b.length) ? length : i; 8143 } 8144 8145 /** 8146 * Finds and returns the relative index of the first mismatch between two 8147 * {@code long} arrays over the specified ranges, otherwise return -1 if no 8148 * mismatch is found. The index will be in the range of 0 (inclusive) up to 8149 * the length (inclusive) of the smaller range. 8150 * 8151 * <p>If the two arrays, over the specified ranges, share a common prefix 8152 * then the returned relative index is the length of the common prefix and 8153 * it follows that there is a mismatch between the two elements at that 8154 * relative index within the respective arrays. 8155 * If one array is a proper prefix of the other, over the specified ranges, 8156 * then the returned relative index is the length of the smaller range and 8157 * it follows that the relative index is only valid for the array with the 8158 * larger range. 8159 * Otherwise, there is no mismatch. 8160 * 8161 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8162 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8163 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 8164 * prefix of length {@code pl} if the following expression is true: 8165 * <pre>{@code 8166 * pl >= 0 && 8167 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 8168 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 8169 * a[aFromIndex + pl] != b[bFromIndex + pl] 8170 * }</pre> 8171 * Note that a common prefix length of {@code 0} indicates that the first 8172 * elements from each array mismatch. 8173 * 8174 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8175 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8176 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 8177 * prefix if the following expression is true: 8178 * <pre>{@code 8179 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 8180 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 8181 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 8182 * }</pre> 8183 * 8184 * @param a the first array to be tested for a mismatch 8185 * @param aFromIndex the index (inclusive) of the first element in the 8186 * first array to be tested 8187 * @param aToIndex the index (exclusive) of the last element in the 8188 * first array to be tested 8189 * @param b the second array to be tested for a mismatch 8190 * @param bFromIndex the index (inclusive) of the first element in the 8191 * second array to be tested 8192 * @param bToIndex the index (exclusive) of the last element in the 8193 * second array to be tested 8194 * @return the relative index of the first mismatch between the two arrays 8195 * over the specified ranges, otherwise {@code -1}. 8196 * @throws IllegalArgumentException 8197 * if {@code aFromIndex > aToIndex} or 8198 * if {@code bFromIndex > bToIndex} 8199 * @throws ArrayIndexOutOfBoundsException 8200 * if {@code aFromIndex < 0 or aToIndex > a.length} or 8201 * if {@code bFromIndex < 0 or bToIndex > b.length} 8202 * @throws NullPointerException 8203 * if either array is {@code null} 8204 * @since 9 8205 */ 8206 public static int mismatch(long[] a, int aFromIndex, int aToIndex, 8207 long[] b, int bFromIndex, int bToIndex) { 8208 rangeCheck(a.length, aFromIndex, aToIndex); 8209 rangeCheck(b.length, bFromIndex, bToIndex); 8210 8211 int aLength = aToIndex - aFromIndex; 8212 int bLength = bToIndex - bFromIndex; 8213 int length = Math.min(aLength, bLength); 8214 int i = ArraysSupport.mismatch(a, aFromIndex, 8215 b, bFromIndex, 8216 length); 8217 return (i < 0 && aLength != bLength) ? length : i; 8218 } 8219 8220 // Mismatch float 8221 8222 /** 8223 * Finds and returns the index of the first mismatch between two {@code float} 8224 * arrays, otherwise return -1 if no mismatch is found. The index will be 8225 * in the range of 0 (inclusive) up to the length (inclusive) of the smaller 8226 * array. 8227 * 8228 * <p>If the two arrays share a common prefix then the returned index is the 8229 * length of the common prefix and it follows that there is a mismatch 8230 * between the two elements at that index within the respective arrays. 8231 * If one array is a proper prefix of the other then the returned index is 8232 * the length of the smaller array and it follows that the index is only 8233 * valid for the larger array. 8234 * Otherwise, there is no mismatch. 8235 * 8236 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 8237 * prefix of length {@code pl} if the following expression is true: 8238 * <pre>{@code 8239 * pl >= 0 && 8240 * pl < Math.min(a.length, b.length) && 8241 * Arrays.equals(a, 0, pl, b, 0, pl) && 8242 * Float.compare(a[pl], b[pl]) != 0 8243 * }</pre> 8244 * Note that a common prefix length of {@code 0} indicates that the first 8245 * elements from each array mismatch. 8246 * 8247 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 8248 * prefix if the following expression is true: 8249 * <pre>{@code 8250 * a.length != b.length && 8251 * Arrays.equals(a, 0, Math.min(a.length, b.length), 8252 * b, 0, Math.min(a.length, b.length)) 8253 * }</pre> 8254 * 8255 * @param a the first array to be tested for a mismatch 8256 * @param b the second array to be tested for a mismatch 8257 * @return the index of the first mismatch between the two arrays, 8258 * otherwise {@code -1}. 8259 * @throws NullPointerException 8260 * if either array is {@code null} 8261 * @since 9 8262 */ 8263 public static int mismatch(float[] a, float[] b) { 8264 int length = Math.min(a.length, b.length); // Check null array refs 8265 if (a == b) 8266 return -1; 8267 8268 int i = ArraysSupport.mismatch(a, b, length); 8269 return (i < 0 && a.length != b.length) ? length : i; 8270 } 8271 8272 /** 8273 * Finds and returns the relative index of the first mismatch between two 8274 * {@code float} arrays over the specified ranges, otherwise return -1 if no 8275 * mismatch is found. The index will be in the range of 0 (inclusive) up to 8276 * the length (inclusive) of the smaller range. 8277 * 8278 * <p>If the two arrays, over the specified ranges, share a common prefix 8279 * then the returned relative index is the length of the common prefix and 8280 * it follows that there is a mismatch between the two elements at that 8281 * relative index within the respective arrays. 8282 * If one array is a proper prefix of the other, over the specified ranges, 8283 * then the returned relative index is the length of the smaller range and 8284 * it follows that the relative index is only valid for the array with the 8285 * larger range. 8286 * Otherwise, there is no mismatch. 8287 * 8288 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8289 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8290 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 8291 * prefix of length {@code pl} if the following expression is true: 8292 * <pre>{@code 8293 * pl >= 0 && 8294 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 8295 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 8296 * Float.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0 8297 * }</pre> 8298 * Note that a common prefix length of {@code 0} indicates that the first 8299 * elements from each array mismatch. 8300 * 8301 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8302 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8303 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 8304 * prefix if the following expression is true: 8305 * <pre>{@code 8306 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 8307 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 8308 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 8309 * }</pre> 8310 * 8311 * @param a the first array to be tested for a mismatch 8312 * @param aFromIndex the index (inclusive) of the first element in the 8313 * first array to be tested 8314 * @param aToIndex the index (exclusive) of the last element in the 8315 * first array to be tested 8316 * @param b the second array to be tested for a mismatch 8317 * @param bFromIndex the index (inclusive) of the first element in the 8318 * second array to be tested 8319 * @param bToIndex the index (exclusive) of the last element in the 8320 * second array to be tested 8321 * @return the relative index of the first mismatch between the two arrays 8322 * over the specified ranges, otherwise {@code -1}. 8323 * @throws IllegalArgumentException 8324 * if {@code aFromIndex > aToIndex} or 8325 * if {@code bFromIndex > bToIndex} 8326 * @throws ArrayIndexOutOfBoundsException 8327 * if {@code aFromIndex < 0 or aToIndex > a.length} or 8328 * if {@code bFromIndex < 0 or bToIndex > b.length} 8329 * @throws NullPointerException 8330 * if either array is {@code null} 8331 * @since 9 8332 */ 8333 public static int mismatch(float[] a, int aFromIndex, int aToIndex, 8334 float[] b, int bFromIndex, int bToIndex) { 8335 rangeCheck(a.length, aFromIndex, aToIndex); 8336 rangeCheck(b.length, bFromIndex, bToIndex); 8337 8338 int aLength = aToIndex - aFromIndex; 8339 int bLength = bToIndex - bFromIndex; 8340 int length = Math.min(aLength, bLength); 8341 int i = ArraysSupport.mismatch(a, aFromIndex, 8342 b, bFromIndex, 8343 length); 8344 return (i < 0 && aLength != bLength) ? length : i; 8345 } 8346 8347 // Mismatch double 8348 8349 /** 8350 * Finds and returns the index of the first mismatch between two 8351 * {@code double} arrays, otherwise return -1 if no mismatch is found. The 8352 * index will be in the range of 0 (inclusive) up to the length (inclusive) 8353 * of the smaller array. 8354 * 8355 * <p>If the two arrays share a common prefix then the returned index is the 8356 * length of the common prefix and it follows that there is a mismatch 8357 * between the two elements at that index within the respective arrays. 8358 * If one array is a proper prefix of the other then the returned index is 8359 * the length of the smaller array and it follows that the index is only 8360 * valid for the larger array. 8361 * Otherwise, there is no mismatch. 8362 * 8363 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 8364 * prefix of length {@code pl} if the following expression is true: 8365 * <pre>{@code 8366 * pl >= 0 && 8367 * pl < Math.min(a.length, b.length) && 8368 * Arrays.equals(a, 0, pl, b, 0, pl) && 8369 * Double.compare(a[pl], b[pl]) != 0 8370 * }</pre> 8371 * Note that a common prefix length of {@code 0} indicates that the first 8372 * elements from each array mismatch. 8373 * 8374 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 8375 * prefix if the following expression is true: 8376 * <pre>{@code 8377 * a.length != b.length && 8378 * Arrays.equals(a, 0, Math.min(a.length, b.length), 8379 * b, 0, Math.min(a.length, b.length)) 8380 * }</pre> 8381 * 8382 * @param a the first array to be tested for a mismatch 8383 * @param b the second array to be tested for a mismatch 8384 * @return the index of the first mismatch between the two arrays, 8385 * otherwise {@code -1}. 8386 * @throws NullPointerException 8387 * if either array is {@code null} 8388 * @since 9 8389 */ 8390 public static int mismatch(double[] a, double[] b) { 8391 int length = Math.min(a.length, b.length); // Check null array refs 8392 if (a == b) 8393 return -1; 8394 8395 int i = ArraysSupport.mismatch(a, b, length); 8396 return (i < 0 && a.length != b.length) ? length : i; 8397 } 8398 8399 /** 8400 * Finds and returns the relative index of the first mismatch between two 8401 * {@code double} arrays over the specified ranges, otherwise return -1 if 8402 * no mismatch is found. The index will be in the range of 0 (inclusive) up 8403 * to the length (inclusive) of the smaller range. 8404 * 8405 * <p>If the two arrays, over the specified ranges, share a common prefix 8406 * then the returned relative index is the length of the common prefix and 8407 * it follows that there is a mismatch between the two elements at that 8408 * relative index within the respective arrays. 8409 * If one array is a proper prefix of the other, over the specified ranges, 8410 * then the returned relative index is the length of the smaller range and 8411 * it follows that the relative index is only valid for the array with the 8412 * larger range. 8413 * Otherwise, there is no mismatch. 8414 * 8415 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8416 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8417 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 8418 * prefix of length {@code pl} if the following expression is true: 8419 * <pre>{@code 8420 * pl >= 0 && 8421 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 8422 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 8423 * Double.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0 8424 * }</pre> 8425 * Note that a common prefix length of {@code 0} indicates that the first 8426 * elements from each array mismatch. 8427 * 8428 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8429 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8430 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 8431 * prefix if the following expression is true: 8432 * <pre>{@code 8433 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 8434 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 8435 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 8436 * }</pre> 8437 * 8438 * @param a the first array to be tested for a mismatch 8439 * @param aFromIndex the index (inclusive) of the first element in the 8440 * first array to be tested 8441 * @param aToIndex the index (exclusive) of the last element in the 8442 * first array to be tested 8443 * @param b the second array to be tested for a mismatch 8444 * @param bFromIndex the index (inclusive) of the first element in the 8445 * second array to be tested 8446 * @param bToIndex the index (exclusive) of the last element in the 8447 * second array to be tested 8448 * @return the relative index of the first mismatch between the two arrays 8449 * over the specified ranges, otherwise {@code -1}. 8450 * @throws IllegalArgumentException 8451 * if {@code aFromIndex > aToIndex} or 8452 * if {@code bFromIndex > bToIndex} 8453 * @throws ArrayIndexOutOfBoundsException 8454 * if {@code aFromIndex < 0 or aToIndex > a.length} or 8455 * if {@code bFromIndex < 0 or bToIndex > b.length} 8456 * @throws NullPointerException 8457 * if either array is {@code null} 8458 * @since 9 8459 */ 8460 public static int mismatch(double[] a, int aFromIndex, int aToIndex, 8461 double[] b, int bFromIndex, int bToIndex) { 8462 rangeCheck(a.length, aFromIndex, aToIndex); 8463 rangeCheck(b.length, bFromIndex, bToIndex); 8464 8465 int aLength = aToIndex - aFromIndex; 8466 int bLength = bToIndex - bFromIndex; 8467 int length = Math.min(aLength, bLength); 8468 int i = ArraysSupport.mismatch(a, aFromIndex, 8469 b, bFromIndex, 8470 length); 8471 return (i < 0 && aLength != bLength) ? length : i; 8472 } 8473 8474 // Mismatch objects 8475 8476 /** 8477 * Finds and returns the index of the first mismatch between two 8478 * {@code Object} arrays, otherwise return -1 if no mismatch is found. The 8479 * index will be in the range of 0 (inclusive) up to the length (inclusive) 8480 * of the smaller array. 8481 * 8482 * <p>If the two arrays share a common prefix then the returned index is the 8483 * length of the common prefix and it follows that there is a mismatch 8484 * between the two elements at that index within the respective arrays. 8485 * If one array is a proper prefix of the other then the returned index is 8486 * the length of the smaller array and it follows that the index is only 8487 * valid for the larger array. 8488 * Otherwise, there is no mismatch. 8489 * 8490 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 8491 * prefix of length {@code pl} if the following expression is true: 8492 * <pre>{@code 8493 * pl >= 0 && 8494 * pl < Math.min(a.length, b.length) && 8495 * Arrays.equals(a, 0, pl, b, 0, pl) && 8496 * !Objects.equals(a[pl], b[pl]) 8497 * }</pre> 8498 * Note that a common prefix length of {@code 0} indicates that the first 8499 * elements from each array mismatch. 8500 * 8501 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 8502 * prefix if the following expression is true: 8503 * <pre>{@code 8504 * a.length != b.length && 8505 * Arrays.equals(a, 0, Math.min(a.length, b.length), 8506 * b, 0, Math.min(a.length, b.length)) 8507 * }</pre> 8508 * 8509 * @param a the first array to be tested for a mismatch 8510 * @param b the second array to be tested for a mismatch 8511 * @return the index of the first mismatch between the two arrays, 8512 * otherwise {@code -1}. 8513 * @throws NullPointerException 8514 * if either array is {@code null} 8515 * @since 9 8516 */ 8517 public static int mismatch(Object[] a, Object[] b) { 8518 int length = Math.min(a.length, b.length); // Check null array refs 8519 if (a == b) 8520 return -1; 8521 8522 for (int i = 0; i < length; i++) { 8523 if (!Objects.equals(a[i], b[i])) 8524 return i; 8525 } 8526 8527 return a.length != b.length ? length : -1; 8528 } 8529 8530 /** 8531 * Finds and returns the relative index of the first mismatch between two 8532 * {@code Object} arrays over the specified ranges, otherwise return -1 if 8533 * no mismatch is found. The index will be in the range of 0 (inclusive) up 8534 * to the length (inclusive) of the smaller range. 8535 * 8536 * <p>If the two arrays, over the specified ranges, share a common prefix 8537 * then the returned relative index is the length of the common prefix and 8538 * it follows that there is a mismatch between the two elements at that 8539 * relative index within the respective arrays. 8540 * If one array is a proper prefix of the other, over the specified ranges, 8541 * then the returned relative index is the length of the smaller range and 8542 * it follows that the relative index is only valid for the array with the 8543 * larger range. 8544 * Otherwise, there is no mismatch. 8545 * 8546 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8547 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8548 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 8549 * prefix of length {@code pl} if the following expression is true: 8550 * <pre>{@code 8551 * pl >= 0 && 8552 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 8553 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl) && 8554 * !Objects.equals(a[aFromIndex + pl], b[bFromIndex + pl]) 8555 * }</pre> 8556 * Note that a common prefix length of {@code 0} indicates that the first 8557 * elements from each array mismatch. 8558 * 8559 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8560 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8561 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 8562 * prefix if the following expression is true: 8563 * <pre>{@code 8564 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 8565 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 8566 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex)) 8567 * }</pre> 8568 * 8569 * @param a the first array to be tested for a mismatch 8570 * @param aFromIndex the index (inclusive) of the first element in the 8571 * first array to be tested 8572 * @param aToIndex the index (exclusive) of the last element in the 8573 * first array to be tested 8574 * @param b the second array to be tested for a mismatch 8575 * @param bFromIndex the index (inclusive) of the first element in the 8576 * second array to be tested 8577 * @param bToIndex the index (exclusive) of the last element in the 8578 * second array to be tested 8579 * @return the relative index of the first mismatch between the two arrays 8580 * over the specified ranges, otherwise {@code -1}. 8581 * @throws IllegalArgumentException 8582 * if {@code aFromIndex > aToIndex} or 8583 * if {@code bFromIndex > bToIndex} 8584 * @throws ArrayIndexOutOfBoundsException 8585 * if {@code aFromIndex < 0 or aToIndex > a.length} or 8586 * if {@code bFromIndex < 0 or bToIndex > b.length} 8587 * @throws NullPointerException 8588 * if either array is {@code null} 8589 * @since 9 8590 */ 8591 public static int mismatch( 8592 Object[] a, int aFromIndex, int aToIndex, 8593 Object[] b, int bFromIndex, int bToIndex) { 8594 rangeCheck(a.length, aFromIndex, aToIndex); 8595 rangeCheck(b.length, bFromIndex, bToIndex); 8596 8597 int aLength = aToIndex - aFromIndex; 8598 int bLength = bToIndex - bFromIndex; 8599 int length = Math.min(aLength, bLength); 8600 for (int i = 0; i < length; i++) { 8601 if (!Objects.equals(a[aFromIndex++], b[bFromIndex++])) 8602 return i; 8603 } 8604 8605 return aLength != bLength ? length : -1; 8606 } 8607 8608 /** 8609 * Finds and returns the index of the first mismatch between two 8610 * {@code Object} arrays, otherwise return -1 if no mismatch is found. 8611 * The index will be in the range of 0 (inclusive) up to the length 8612 * (inclusive) of the smaller array. 8613 * 8614 * <p>The specified comparator is used to determine if two array elements 8615 * from the each array are not equal. 8616 * 8617 * <p>If the two arrays share a common prefix then the returned index is the 8618 * length of the common prefix and it follows that there is a mismatch 8619 * between the two elements at that index within the respective arrays. 8620 * If one array is a proper prefix of the other then the returned index is 8621 * the length of the smaller array and it follows that the index is only 8622 * valid for the larger array. 8623 * Otherwise, there is no mismatch. 8624 * 8625 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a common 8626 * prefix of length {@code pl} if the following expression is true: 8627 * <pre>{@code 8628 * pl >= 0 && 8629 * pl < Math.min(a.length, b.length) && 8630 * Arrays.equals(a, 0, pl, b, 0, pl, cmp) 8631 * cmp.compare(a[pl], b[pl]) != 0 8632 * }</pre> 8633 * Note that a common prefix length of {@code 0} indicates that the first 8634 * elements from each array mismatch. 8635 * 8636 * <p>Two non-{@code null} arrays, {@code a} and {@code b}, share a proper 8637 * prefix if the following expression is true: 8638 * <pre>{@code 8639 * a.length != b.length && 8640 * Arrays.equals(a, 0, Math.min(a.length, b.length), 8641 * b, 0, Math.min(a.length, b.length), 8642 * cmp) 8643 * }</pre> 8644 * 8645 * @param a the first array to be tested for a mismatch 8646 * @param b the second array to be tested for a mismatch 8647 * @param cmp the comparator to compare array elements 8648 * @param <T> the type of array elements 8649 * @return the index of the first mismatch between the two arrays, 8650 * otherwise {@code -1}. 8651 * @throws NullPointerException 8652 * if either array or the comparator is {@code null} 8653 * @since 9 8654 */ 8655 public static <T> int mismatch(T[] a, T[] b, Comparator<? super T> cmp) { 8656 Objects.requireNonNull(cmp); 8657 int length = Math.min(a.length, b.length); // Check null array refs 8658 if (a == b) 8659 return -1; 8660 8661 for (int i = 0; i < length; i++) { 8662 T oa = a[i]; 8663 T ob = b[i]; 8664 if (oa != ob) { 8665 // Null-value comparison is deferred to the comparator 8666 int v = cmp.compare(oa, ob); 8667 if (v != 0) { 8668 return i; 8669 } 8670 } 8671 } 8672 8673 return a.length != b.length ? length : -1; 8674 } 8675 8676 /** 8677 * Finds and returns the relative index of the first mismatch between two 8678 * {@code Object} arrays over the specified ranges, otherwise return -1 if 8679 * no mismatch is found. The index will be in the range of 0 (inclusive) up 8680 * to the length (inclusive) of the smaller range. 8681 * 8682 * <p>If the two arrays, over the specified ranges, share a common prefix 8683 * then the returned relative index is the length of the common prefix and 8684 * it follows that there is a mismatch between the two elements at that 8685 * relative index within the respective arrays. 8686 * If one array is a proper prefix of the other, over the specified ranges, 8687 * then the returned relative index is the length of the smaller range and 8688 * it follows that the relative index is only valid for the array with the 8689 * larger range. 8690 * Otherwise, there is no mismatch. 8691 * 8692 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8693 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8694 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a common 8695 * prefix of length {@code pl} if the following expression is true: 8696 * <pre>{@code 8697 * pl >= 0 && 8698 * pl < Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex) && 8699 * Arrays.equals(a, aFromIndex, aFromIndex + pl, b, bFromIndex, bFromIndex + pl, cmp) && 8700 * cmp.compare(a[aFromIndex + pl], b[bFromIndex + pl]) != 0 8701 * }</pre> 8702 * Note that a common prefix length of {@code 0} indicates that the first 8703 * elements from each array mismatch. 8704 * 8705 * <p>Two non-{@code null} arrays, {@code a} and {@code b} with specified 8706 * ranges [{@code aFromIndex}, {@code aToIndex}) and 8707 * [{@code bFromIndex}, {@code bToIndex}) respectively, share a proper 8708 * prefix if the following expression is true: 8709 * <pre>{@code 8710 * (aToIndex - aFromIndex) != (bToIndex - bFromIndex) && 8711 * Arrays.equals(a, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 8712 * b, 0, Math.min(aToIndex - aFromIndex, bToIndex - bFromIndex), 8713 * cmp) 8714 * }</pre> 8715 * 8716 * @param a the first array to be tested for a mismatch 8717 * @param aFromIndex the index (inclusive) of the first element in the 8718 * first array to be tested 8719 * @param aToIndex the index (exclusive) of the last element in the 8720 * first array to be tested 8721 * @param b the second array to be tested for a mismatch 8722 * @param bFromIndex the index (inclusive) of the first element in the 8723 * second array to be tested 8724 * @param bToIndex the index (exclusive) of the last element in the 8725 * second array to be tested 8726 * @param cmp the comparator to compare array elements 8727 * @param <T> the type of array elements 8728 * @return the relative index of the first mismatch between the two arrays 8729 * over the specified ranges, otherwise {@code -1}. 8730 * @throws IllegalArgumentException 8731 * if {@code aFromIndex > aToIndex} or 8732 * if {@code bFromIndex > bToIndex} 8733 * @throws ArrayIndexOutOfBoundsException 8734 * if {@code aFromIndex < 0 or aToIndex > a.length} or 8735 * if {@code bFromIndex < 0 or bToIndex > b.length} 8736 * @throws NullPointerException 8737 * if either array or the comparator is {@code null} 8738 * @since 9 8739 */ 8740 public static <T> int mismatch( 8741 T[] a, int aFromIndex, int aToIndex, 8742 T[] b, int bFromIndex, int bToIndex, 8743 Comparator<? super T> cmp) { 8744 Objects.requireNonNull(cmp); 8745 rangeCheck(a.length, aFromIndex, aToIndex); 8746 rangeCheck(b.length, bFromIndex, bToIndex); 8747 8748 int aLength = aToIndex - aFromIndex; 8749 int bLength = bToIndex - bFromIndex; 8750 int length = Math.min(aLength, bLength); 8751 for (int i = 0; i < length; i++) { 8752 T oa = a[aFromIndex++]; 8753 T ob = b[bFromIndex++]; 8754 if (oa != ob) { 8755 // Null-value comparison is deferred to the comparator 8756 int v = cmp.compare(oa, ob); 8757 if (v != 0) { 8758 return i; 8759 } 8760 } 8761 } 8762 8763 return aLength != bLength ? length : -1; 8764 } 8765 } --- EOF ---