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