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