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