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