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