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