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