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