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