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