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