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