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