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