001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one
003 * or more contributor license agreements. See the NOTICE file
004 * distributed with this work for additional information
005 * regarding copyright ownership. The ASF licenses this file
006 * to you under the Apache License, Version 2.0 (the
007 * "License"); you may not use this file except in compliance
008 * with the License. You may obtain a copy of the License at
009 *
010 * http://www.apache.org/licenses/LICENSE-2.0
011 *
012 * Unless required by applicable law or agreed to in writing,
013 * software distributed under the License is distributed on an
014 * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
015 * KIND, either express or implied. See the License for the
016 * specific language governing permissions and limitations
017 * under the License.
018 *
019 */
020 package org.apache.directory.shared.ldap.util;
021
022
023 import java.lang.reflect.Array;
024
025 import org.apache.directory.shared.i18n.I18n;
026
027
028 /**
029 * <p>
030 * Operations on arrays, primitive arrays (like <code>int[]</code>) and
031 * primitive wrapper arrays (like <code>Integer[]</code>).
032 * </p>
033 * <p>
034 * This class tries to handle <code>null</code> input gracefully. An exception
035 * will not be thrown for a <code>null</code> array input. However, an Object
036 * array that contains a <code>null</code> element may throw an exception.
037 * Each method documents its behaviour.
038 * </p>
039 *
040 * @author <a href="mailto:dev@directory.apache.org">Apache Directory Project</a>
041 * @since 2.0
042 */
043 public class ArrayUtils
044 {
045
046 /**
047 * An empty immutable <code>Object</code> array.
048 */
049 public static final Object[] EMPTY_OBJECT_ARRAY = new Object[0];
050
051 /**
052 * An empty immutable <code>Class</code> array.
053 */
054 public static final Class<?>[] EMPTY_CLASS_ARRAY = new Class<?>[0];
055
056 /**
057 * An empty immutable <code>String</code> array.
058 */
059 public static final String[] EMPTY_STRING_ARRAY = new String[0];
060
061 /**
062 * An empty immutable <code>long</code> array.
063 */
064 public static final long[] EMPTY_LONG_ARRAY = new long[0];
065
066 /**
067 * An empty immutable <code>Long</code> array.
068 */
069 public static final Long[] EMPTY_LONG_OBJECT_ARRAY = new Long[0];
070
071 /**
072 * An empty immutable <code>int</code> array.
073 */
074 public static final int[] EMPTY_INT_ARRAY = new int[0];
075
076 /**
077 * An empty immutable <code>Integer</code> array.
078 */
079 public static final Integer[] EMPTY_INTEGER_OBJECT_ARRAY = new Integer[0];
080
081 /**
082 * An empty immutable <code>short</code> array.
083 */
084 public static final short[] EMPTY_SHORT_ARRAY = new short[0];
085
086 /**
087 * An empty immutable <code>Short</code> array.
088 */
089 public static final Short[] EMPTY_SHORT_OBJECT_ARRAY = new Short[0];
090
091 /**
092 * An empty immutable <code>byte</code> array.
093 */
094 public static final byte[] EMPTY_BYTE_ARRAY = new byte[0];
095
096 /**
097 * An empty immutable <code>Byte</code> array.
098 */
099 public static final Byte[] EMPTY_BYTE_OBJECT_ARRAY = new Byte[0];
100
101 /**
102 * An empty immutable <code>double</code> array.
103 */
104 public static final double[] EMPTY_DOUBLE_ARRAY = new double[0];
105
106 /**
107 * An empty immutable <code>Double</code> array.
108 */
109 public static final Double[] EMPTY_DOUBLE_OBJECT_ARRAY = new Double[0];
110
111 /**
112 * An empty immutable <code>float</code> array.
113 */
114 public static final float[] EMPTY_FLOAT_ARRAY = new float[0];
115
116 /**
117 * An empty immutable <code>Float</code> array.
118 */
119 public static final Float[] EMPTY_FLOAT_OBJECT_ARRAY = new Float[0];
120
121 /**
122 * An empty immutable <code>boolean</code> array.
123 */
124 public static final boolean[] EMPTY_BOOLEAN_ARRAY = new boolean[0];
125
126 /**
127 * An empty immutable <code>Boolean</code> array.
128 */
129 public static final Boolean[] EMPTY_BOOLEAN_OBJECT_ARRAY = new Boolean[0];
130
131 /**
132 * An empty immutable <code>char</code> array.
133 */
134 public static final char[] EMPTY_CHAR_ARRAY = new char[0];
135
136 /**
137 * An empty immutable <code>Character</code> array.
138 */
139 public static final Character[] EMPTY_CHARACTER_OBJECT_ARRAY = new Character[0];
140
141
142 /**
143 * <p>
144 * ArrayUtils instances should NOT be constructed in standard programming.
145 * Instead, the class should be used as
146 * <code>ArrayUtils.clone(new int[] {2})</code>.
147 * </p>
148 * <p>
149 * This constructor is public to permit tools that require a JavaBean
150 * instance to operate.
151 * </p>
152 */
153 public ArrayUtils()
154 {
155 }
156
157
158 // Basic methods handling multi-dimensional arrays
159 // -----------------------------------------------------------------------
160 /**
161 * <p>
162 * Outputs an array as a String, treating <code>null</code> as an empty
163 * array.
164 * </p>
165 * <p>
166 * Multi-dimensional arrays are handled correctly, including
167 * multi-dimensional primitive arrays.
168 * </p>
169 * <p>
170 * The format is that of Java source code, for example <code>{a,b}</code>.
171 * </p>
172 *
173 * @param array
174 * the array to get a toString for, may be <code>null</code>
175 * @return a String representation of the array, '{}' if null array input
176 */
177 public static String toString( Object array )
178 {
179 return toString( array, "{}" );
180 }
181
182
183 /**
184 * <p>
185 * Outputs an array as a String handling <code>null</code>s.
186 * </p>
187 * <p>
188 * Multi-dimensional arrays are handled correctly, including
189 * multi-dimensional primitive arrays.
190 * </p>
191 * <p>
192 * The format is that of Java source code, for example <code>{a,b}</code>.
193 * </p>
194 *
195 * @param array
196 * the array to get a toString for, may be <code>null</code>
197 * @param stringIfNull
198 * the String to return if the array is <code>null</code>
199 * @return a String representation of the array
200 */
201 public static String toString( Object array, String stringIfNull )
202 {
203 if ( array == null )
204 {
205 return stringIfNull;
206 }
207
208 return new ToStringBuilder( array, ToStringStyle.SIMPLE_STYLE ).append( array ).toString();
209 }
210
211
212 /**
213 * <p>
214 * Get a hashCode for an array handling multi-dimensional arrays correctly.
215 * </p>
216 * <p>
217 * Multi-dimensional primitive arrays are also handled correctly by this
218 * method.
219 * </p>
220 *
221 * @param array
222 * the array to get a hashCode for, may be <code>null</code>
223 * @return a hashCode for the array, zero if null array input
224 */
225 public static int hashCode( Object array )
226 {
227 return new HashCodeBuilder().append( array ).toHashCode();
228 }
229
230
231 /**
232 * <p>
233 * Compares two arrays, using equals(), handling multi-dimensional arrays
234 * correctly.
235 * </p>
236 * <p>
237 * Multi-dimensional primitive arrays are also handled correctly by this
238 * method.
239 * </p>
240 *
241 * @param array1
242 * the left hand array to compare, may be <code>null</code>
243 * @param array2
244 * the right hand array to compare, may be <code>null</code>
245 * @return <code>true</code> if the arrays are equal
246 */
247 public static boolean isEquals( Object array1, Object array2 )
248 {
249 return new EqualsBuilder().append( array1, array2 ).isEquals();
250 }
251
252 // Clone
253 // -----------------------------------------------------------------------
254 /**
255 * <p>
256 * Shallow clones an array returning a typecast result and handling
257 * <code>null</code>.
258 * </p>
259 * <p>
260 * The objects in the array are not cloned, thus there is no special
261 * handling for multi-dimensional arrays.
262 * </p>
263 * <p>
264 * This method returns <code>null</code> if <code>null</code> array
265 * input.
266 * </p>
267 *
268 * @param array
269 * the array to shallow clone, may be <code>null</code>
270 * @return the cloned array, <code>null</code> if <code>null</code>
271 * input
272 */
273 public static Object[] clone( Object[] array )
274 {
275 if ( array == null )
276 {
277 return null;
278 }
279 return array.clone();
280 }
281
282
283 /**
284 * <p>
285 * Clones an array returning a typecast result and handling
286 * <code>null</code>.
287 * </p>
288 * <p>
289 * This method returns <code>null</code> if <code>null</code> array
290 * input.
291 * </p>
292 *
293 * @param array
294 * the array to clone, may be <code>null</code>
295 * @return the cloned array, <code>null</code> if <code>null</code>
296 * input
297 */
298 public static long[] clone( long[] array )
299 {
300 if ( array == null )
301 {
302 return null;
303 }
304 return array.clone();
305 }
306
307
308 /**
309 * <p>
310 * Clones an array returning a typecast result and handling
311 * <code>null</code>.
312 * </p>
313 * <p>
314 * This method returns <code>null</code> if <code>null</code> array
315 * input.
316 * </p>
317 *
318 * @param array
319 * the array to clone, may be <code>null</code>
320 * @return the cloned array, <code>null</code> if <code>null</code>
321 * input
322 */
323 public static int[] clone( int[] array )
324 {
325 if ( array == null )
326 {
327 return null;
328 }
329 return array.clone();
330 }
331
332
333 /**
334 * <p>
335 * Clones an array returning a typecast result and handling
336 * <code>null</code>.
337 * </p>
338 * <p>
339 * This method returns <code>null</code> if <code>null</code> array
340 * input.
341 * </p>
342 *
343 * @param array
344 * the array to clone, may be <code>null</code>
345 * @return the cloned array, <code>null</code> if <code>null</code>
346 * input
347 */
348 public static short[] clone( short[] array )
349 {
350 if ( array == null )
351 {
352 return null;
353 }
354 return array.clone();
355 }
356
357
358 /**
359 * <p>
360 * Clones an array returning a typecast result and handling
361 * <code>null</code>.
362 * </p>
363 * <p>
364 * This method returns <code>null</code> if <code>null</code> array
365 * input.
366 * </p>
367 *
368 * @param array
369 * the array to clone, may be <code>null</code>
370 * @return the cloned array, <code>null</code> if <code>null</code>
371 * input
372 */
373 public static char[] clone( char[] array )
374 {
375 if ( array == null )
376 {
377 return null;
378 }
379 return array.clone();
380 }
381
382
383 /**
384 * <p>
385 * Clones an array returning a typecast result and handling
386 * <code>null</code>.
387 * </p>
388 * <p>
389 * This method returns <code>null</code> if <code>null</code> array
390 * input.
391 * </p>
392 *
393 * @param array
394 * the array to clone, may be <code>null</code>
395 * @return the cloned array, <code>null</code> if <code>null</code>
396 * input
397 */
398 public static byte[] clone( byte[] array )
399 {
400 if ( array == null )
401 {
402 return null;
403 }
404 return array.clone();
405 }
406
407
408 /**
409 * <p>
410 * Clones an array returning a typecast result and handling
411 * <code>null</code>.
412 * </p>
413 * <p>
414 * This method returns <code>null</code> if <code>null</code> array
415 * input.
416 * </p>
417 *
418 * @param array
419 * the array to clone, may be <code>null</code>
420 * @return the cloned array, <code>null</code> if <code>null</code>
421 * input
422 */
423 public static double[] clone( double[] array )
424 {
425 if ( array == null )
426 {
427 return null;
428 }
429 return array.clone();
430 }
431
432
433 /**
434 * <p>
435 * Clones an array returning a typecast result and handling
436 * <code>null</code>.
437 * </p>
438 * <p>
439 * This method returns <code>null</code> if <code>null</code> array
440 * input.
441 * </p>
442 *
443 * @param array
444 * the array to clone, may be <code>null</code>
445 * @return the cloned array, <code>null</code> if <code>null</code>
446 * input
447 */
448 public static float[] clone( float[] array )
449 {
450 if ( array == null )
451 {
452 return null;
453 }
454 return array.clone();
455 }
456
457
458 /**
459 * <p>
460 * Clones an array returning a typecast result and handling
461 * <code>null</code>.
462 * </p>
463 * <p>
464 * This method returns <code>null</code> if <code>null</code> array
465 * input.
466 * </p>
467 *
468 * @param array
469 * the array to clone, may be <code>null</code>
470 * @return the cloned array, <code>null</code> if <code>null</code>
471 * input
472 */
473 public static boolean[] clone( boolean[] array )
474 {
475 if ( array == null )
476 {
477 return null;
478 }
479 return array.clone();
480 }
481
482
483 // Subarrays
484 // -----------------------------------------------------------------------
485 /**
486 * <p>
487 * Produces a new array containing the elements between the start and end
488 * indices.
489 * </p>
490 * <p>
491 * The start index is inclusive, the end index exclusive. Null array input
492 * produces null output.
493 * </p>
494 * <p>
495 * The component type of the subarray is always the same as that of the
496 * input array. Thus, if the input is an array of type <code>Date</code>,
497 * the following usage is envisaged:
498 * </p>
499 *
500 * <pre>
501 * Date[] someDates = ( Date[] ) ArrayUtils.subarray( allDates, 2, 5 );
502 * </pre>
503 *
504 * @param array
505 * the array
506 * @param startIndexInclusive
507 * the starting index. Undervalue (<0) is promoted to 0,
508 * overvalue (>array.length) results in an empty array.
509 * @param endIndexExclusive
510 * elements up to endIndex-1 are present in the returned
511 * subarray. Undervalue (< startIndex) produces empty array,
512 * overvalue (>array.length) is demoted to array length.
513 * @return a new array containing the elements between the start and end
514 * indices.
515 */
516 public static Object[] subarray( Object[] array, int startIndexInclusive, int endIndexExclusive )
517 {
518 if ( array == null )
519 {
520 return null;
521 }
522 if ( startIndexInclusive < 0 )
523 {
524 startIndexInclusive = 0;
525 }
526 if ( endIndexExclusive > array.length )
527 {
528 endIndexExclusive = array.length;
529 }
530 int newSize = endIndexExclusive - startIndexInclusive;
531 Class<?> type = array.getClass().getComponentType();
532 if ( newSize <= 0 )
533 {
534 return ( Object[] ) Array.newInstance( type, 0 );
535 }
536 Object[] subarray = ( Object[] ) Array.newInstance( type, newSize );
537 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
538 return subarray;
539 }
540
541
542 /**
543 * <p>
544 * Produces a new <code>long</code> array containing the elements between
545 * the start and end indices.
546 * </p>
547 * <p>
548 * The start index is inclusive, the end index exclusive. Null array input
549 * produces null output.
550 * </p>
551 *
552 * @param array
553 * the array
554 * @param startIndexInclusive
555 * the starting index. Undervalue (<0) is promoted to 0,
556 * overvalue (>array.length) results in an empty array.
557 * @param endIndexExclusive
558 * elements up to endIndex-1 are present in the returned
559 * subarray. Undervalue (< startIndex) produces empty array,
560 * overvalue (>array.length) is demoted to array length.
561 * @return a new array containing the elements between the start and end
562 * indices.
563 */
564 public static long[] subarray( long[] array, int startIndexInclusive, int endIndexExclusive )
565 {
566 if ( array == null )
567 {
568 return null;
569 }
570 if ( startIndexInclusive < 0 )
571 {
572 startIndexInclusive = 0;
573 }
574 if ( endIndexExclusive > array.length )
575 {
576 endIndexExclusive = array.length;
577 }
578 int newSize = endIndexExclusive - startIndexInclusive;
579 if ( newSize <= 0 )
580 {
581 return EMPTY_LONG_ARRAY;
582 }
583
584 long[] subarray = new long[newSize];
585 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
586 return subarray;
587 }
588
589
590 /**
591 * <p>
592 * Produces a new <code>int</code> array containing the elements between
593 * the start and end indices.
594 * </p>
595 * <p>
596 * The start index is inclusive, the end index exclusive. Null array input
597 * produces null output.
598 * </p>
599 *
600 * @param array
601 * the array
602 * @param startIndexInclusive
603 * the starting index. Undervalue (<0) is promoted to 0,
604 * overvalue (>array.length) results in an empty array.
605 * @param endIndexExclusive
606 * elements up to endIndex-1 are present in the returned
607 * subarray. Undervalue (< startIndex) produces empty array,
608 * overvalue (>array.length) is demoted to array length.
609 * @return a new array containing the elements between the start and end
610 * indices.
611 */
612 public static int[] subarray( int[] array, int startIndexInclusive, int endIndexExclusive )
613 {
614 if ( array == null )
615 {
616 return null;
617 }
618 if ( startIndexInclusive < 0 )
619 {
620 startIndexInclusive = 0;
621 }
622 if ( endIndexExclusive > array.length )
623 {
624 endIndexExclusive = array.length;
625 }
626 int newSize = endIndexExclusive - startIndexInclusive;
627 if ( newSize <= 0 )
628 {
629 return EMPTY_INT_ARRAY;
630 }
631
632 int[] subarray = new int[newSize];
633 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
634 return subarray;
635 }
636
637
638 /**
639 * <p>
640 * Produces a new <code>short</code> array containing the elements between
641 * the start and end indices.
642 * </p>
643 * <p>
644 * The start index is inclusive, the end index exclusive. Null array input
645 * produces null output.
646 * </p>
647 *
648 * @param array
649 * the array
650 * @param startIndexInclusive
651 * the starting index. Undervalue (<0) is promoted to 0,
652 * overvalue (>array.length) results in an empty array.
653 * @param endIndexExclusive
654 * elements up to endIndex-1 are present in the returned
655 * subarray. Undervalue (< startIndex) produces empty array,
656 * overvalue (>array.length) is demoted to array length.
657 * @return a new array containing the elements between the start and end
658 * indices.
659 */
660 public static short[] subarray( short[] array, int startIndexInclusive, int endIndexExclusive )
661 {
662 if ( array == null )
663 {
664 return null;
665 }
666 if ( startIndexInclusive < 0 )
667 {
668 startIndexInclusive = 0;
669 }
670 if ( endIndexExclusive > array.length )
671 {
672 endIndexExclusive = array.length;
673 }
674 int newSize = endIndexExclusive - startIndexInclusive;
675 if ( newSize <= 0 )
676 {
677 return EMPTY_SHORT_ARRAY;
678 }
679
680 short[] subarray = new short[newSize];
681 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
682 return subarray;
683 }
684
685
686 /**
687 * <p>
688 * Produces a new <code>char</code> array containing the elements between
689 * the start and end indices.
690 * </p>
691 * <p>
692 * The start index is inclusive, the end index exclusive. Null array input
693 * produces null output.
694 * </p>
695 *
696 * @param array
697 * the array
698 * @param startIndexInclusive
699 * the starting index. Undervalue (<0) is promoted to 0,
700 * overvalue (>array.length) results in an empty array.
701 * @param endIndexExclusive
702 * elements up to endIndex-1 are present in the returned
703 * subarray. Undervalue (< startIndex) produces empty array,
704 * overvalue (>array.length) is demoted to array length.
705 * @return a new array containing the elements between the start and end
706 * indices.
707 */
708 public static char[] subarray( char[] array, int startIndexInclusive, int endIndexExclusive )
709 {
710 if ( array == null )
711 {
712 return null;
713 }
714 if ( startIndexInclusive < 0 )
715 {
716 startIndexInclusive = 0;
717 }
718 if ( endIndexExclusive > array.length )
719 {
720 endIndexExclusive = array.length;
721 }
722 int newSize = endIndexExclusive - startIndexInclusive;
723 if ( newSize <= 0 )
724 {
725 return EMPTY_CHAR_ARRAY;
726 }
727
728 char[] subarray = new char[newSize];
729 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
730 return subarray;
731 }
732
733
734 /**
735 * <p>
736 * Produces a new <code>byte</code> array containing the elements between
737 * the start and end indices.
738 * </p>
739 * <p>
740 * The start index is inclusive, the end index exclusive. Null array input
741 * produces null output.
742 * </p>
743 *
744 * @param array
745 * the array
746 * @param startIndexInclusive
747 * the starting index. Undervalue (<0) is promoted to 0,
748 * overvalue (>array.length) results in an empty array.
749 * @param endIndexExclusive
750 * elements up to endIndex-1 are present in the returned
751 * subarray. Undervalue (< startIndex) produces empty array,
752 * overvalue (>array.length) is demoted to array length.
753 * @return a new array containing the elements between the start and end
754 * indices.
755 */
756 public static byte[] subarray( byte[] array, int startIndexInclusive, int endIndexExclusive )
757 {
758 if ( array == null )
759 {
760 return null;
761 }
762 if ( startIndexInclusive < 0 )
763 {
764 startIndexInclusive = 0;
765 }
766 if ( endIndexExclusive > array.length )
767 {
768 endIndexExclusive = array.length;
769 }
770 int newSize = endIndexExclusive - startIndexInclusive;
771 if ( newSize <= 0 )
772 {
773 return EMPTY_BYTE_ARRAY;
774 }
775
776 byte[] subarray = new byte[newSize];
777 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
778 return subarray;
779 }
780
781
782 /**
783 * <p>
784 * Produces a new <code>double</code> array containing the elements
785 * between the start and end indices.
786 * </p>
787 * <p>
788 * The start index is inclusive, the end index exclusive. Null array input
789 * produces null output.
790 * </p>
791 *
792 * @param array
793 * the array
794 * @param startIndexInclusive
795 * the starting index. Undervalue (<0) is promoted to 0,
796 * overvalue (>array.length) results in an empty array.
797 * @param endIndexExclusive
798 * elements up to endIndex-1 are present in the returned
799 * subarray. Undervalue (< startIndex) produces empty array,
800 * overvalue (>array.length) is demoted to array length.
801 * @return a new array containing the elements between the start and end
802 * indices.
803 */
804 public static double[] subarray( double[] array, int startIndexInclusive, int endIndexExclusive )
805 {
806 if ( array == null )
807 {
808 return null;
809 }
810 if ( startIndexInclusive < 0 )
811 {
812 startIndexInclusive = 0;
813 }
814 if ( endIndexExclusive > array.length )
815 {
816 endIndexExclusive = array.length;
817 }
818 int newSize = endIndexExclusive - startIndexInclusive;
819 if ( newSize <= 0 )
820 {
821 return EMPTY_DOUBLE_ARRAY;
822 }
823
824 double[] subarray = new double[newSize];
825 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
826 return subarray;
827 }
828
829
830 /**
831 * <p>
832 * Produces a new <code>float</code> array containing the elements between
833 * the start and end indices.
834 * </p>
835 * <p>
836 * The start index is inclusive, the end index exclusive. Null array input
837 * produces null output.
838 * </p>
839 *
840 * @param array
841 * the array
842 * @param startIndexInclusive
843 * the starting index. Undervalue (<0) is promoted to 0,
844 * overvalue (>array.length) results in an empty array.
845 * @param endIndexExclusive
846 * elements up to endIndex-1 are present in the returned
847 * subarray. Undervalue (< startIndex) produces empty array,
848 * overvalue (>array.length) is demoted to array length.
849 * @return a new array containing the elements between the start and end
850 * indices.
851 */
852 public static float[] subarray( float[] array, int startIndexInclusive, int endIndexExclusive )
853 {
854 if ( array == null )
855 {
856 return null;
857 }
858 if ( startIndexInclusive < 0 )
859 {
860 startIndexInclusive = 0;
861 }
862 if ( endIndexExclusive > array.length )
863 {
864 endIndexExclusive = array.length;
865 }
866 int newSize = endIndexExclusive - startIndexInclusive;
867 if ( newSize <= 0 )
868 {
869 return EMPTY_FLOAT_ARRAY;
870 }
871
872 float[] subarray = new float[newSize];
873 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
874 return subarray;
875 }
876
877
878 /**
879 * <p>
880 * Produces a new <code>boolean</code> array containing the elements
881 * between the start and end indices.
882 * </p>
883 * <p>
884 * The start index is inclusive, the end index exclusive. Null array input
885 * produces null output.
886 * </p>
887 *
888 * @param array
889 * the array
890 * @param startIndexInclusive
891 * the starting index. Undervalue (<0) is promoted to 0,
892 * overvalue (>array.length) results in an empty array.
893 * @param endIndexExclusive
894 * elements up to endIndex-1 are present in the returned
895 * subarray. Undervalue (< startIndex) produces empty array,
896 * overvalue (>array.length) is demoted to array length.
897 * @return a new array containing the elements between the start and end
898 * indices.
899 */
900 public static boolean[] subarray( boolean[] array, int startIndexInclusive, int endIndexExclusive )
901 {
902 if ( array == null )
903 {
904 return null;
905 }
906 if ( startIndexInclusive < 0 )
907 {
908 startIndexInclusive = 0;
909 }
910 if ( endIndexExclusive > array.length )
911 {
912 endIndexExclusive = array.length;
913 }
914 int newSize = endIndexExclusive - startIndexInclusive;
915 if ( newSize <= 0 )
916 {
917 return EMPTY_BOOLEAN_ARRAY;
918 }
919
920 boolean[] subarray = new boolean[newSize];
921 System.arraycopy( array, startIndexInclusive, subarray, 0, newSize );
922 return subarray;
923 }
924
925
926 // Is same length
927 // -----------------------------------------------------------------------
928 /**
929 * <p>
930 * Checks whether two arrays are the same length, treating <code>null</code>
931 * arrays as length <code>0</code>.
932 * <p>
933 * Any multi-dimensional aspects of the arrays are ignored.
934 * </p>
935 *
936 * @param array1
937 * the first array, may be <code>null</code>
938 * @param array2
939 * the second array, may be <code>null</code>
940 * @return <code>true</code> if length of arrays matches, treating
941 * <code>null</code> as an empty array
942 */
943 public static boolean isSameLength( Object[] array1, Object[] array2 )
944 {
945 if ( ( array1 == null && array2 != null && array2.length > 0 )
946 || ( array2 == null && array1 != null && array1.length > 0 )
947 || ( array1 != null && array2 != null && array1.length != array2.length ) )
948 {
949 return false;
950 }
951 return true;
952 }
953
954
955 /**
956 * <p>
957 * Checks whether two arrays are the same length, treating <code>null</code>
958 * arrays as length <code>0</code>.
959 * </p>
960 *
961 * @param array1
962 * the first array, may be <code>null</code>
963 * @param array2
964 * the second array, may be <code>null</code>
965 * @return <code>true</code> if length of arrays matches, treating
966 * <code>null</code> as an empty array
967 */
968 public static boolean isSameLength( long[] array1, long[] array2 )
969 {
970 if ( ( array1 == null && array2 != null && array2.length > 0 )
971 || ( array2 == null && array1 != null && array1.length > 0 )
972 || ( array1 != null && array2 != null && array1.length != array2.length ) )
973 {
974 return false;
975 }
976 return true;
977 }
978
979
980 /**
981 * <p>
982 * Checks whether two arrays are the same length, treating <code>null</code>
983 * arrays as length <code>0</code>.
984 * </p>
985 *
986 * @param array1
987 * the first array, may be <code>null</code>
988 * @param array2
989 * the second array, may be <code>null</code>
990 * @return <code>true</code> if length of arrays matches, treating
991 * <code>null</code> as an empty array
992 */
993 public static boolean isSameLength( int[] array1, int[] array2 )
994 {
995 if ( ( array1 == null && array2 != null && array2.length > 0 )
996 || ( array2 == null && array1 != null && array1.length > 0 )
997 || ( array1 != null && array2 != null && array1.length != array2.length ) )
998 {
999 return false;
1000 }
1001 return true;
1002 }
1003
1004
1005 /**
1006 * <p>
1007 * Checks whether two arrays are the same length, treating <code>null</code>
1008 * arrays as length <code>0</code>.
1009 * </p>
1010 *
1011 * @param array1
1012 * the first array, may be <code>null</code>
1013 * @param array2
1014 * the second array, may be <code>null</code>
1015 * @return <code>true</code> if length of arrays matches, treating
1016 * <code>null</code> as an empty array
1017 */
1018 public static boolean isSameLength( short[] array1, short[] array2 )
1019 {
1020 if ( ( array1 == null && array2 != null && array2.length > 0 )
1021 || ( array2 == null && array1 != null && array1.length > 0 )
1022 || ( array1 != null && array2 != null && array1.length != array2.length ) )
1023 {
1024 return false;
1025 }
1026 return true;
1027 }
1028
1029
1030 /**
1031 * <p>
1032 * Checks whether two arrays are the same length, treating <code>null</code>
1033 * arrays as length <code>0</code>.
1034 * </p>
1035 *
1036 * @param array1
1037 * the first array, may be <code>null</code>
1038 * @param array2
1039 * the second array, may be <code>null</code>
1040 * @return <code>true</code> if length of arrays matches, treating
1041 * <code>null</code> as an empty array
1042 */
1043 public static boolean isSameLength( char[] array1, char[] array2 )
1044 {
1045 if ( ( array1 == null && array2 != null && array2.length > 0 )
1046 || ( array2 == null && array1 != null && array1.length > 0 )
1047 || ( array1 != null && array2 != null && array1.length != array2.length ) )
1048 {
1049 return false;
1050 }
1051 return true;
1052 }
1053
1054
1055 /**
1056 * <p>
1057 * Checks whether two arrays are the same length, treating <code>null</code>
1058 * arrays as length <code>0</code>.
1059 * </p>
1060 *
1061 * @param array1
1062 * the first array, may be <code>null</code>
1063 * @param array2
1064 * the second array, may be <code>null</code>
1065 * @return <code>true</code> if length of arrays matches, treating
1066 * <code>null</code> as an empty array
1067 */
1068 public static boolean isSameLength( byte[] array1, byte[] array2 )
1069 {
1070 if ( ( array1 == null && array2 != null && array2.length > 0 )
1071 || ( array2 == null && array1 != null && array1.length > 0 )
1072 || ( array1 != null && array2 != null && array1.length != array2.length ) )
1073 {
1074 return false;
1075 }
1076 return true;
1077 }
1078
1079
1080 /**
1081 * <p>
1082 * Checks whether two arrays are the same length, treating <code>null</code>
1083 * arrays as length <code>0</code>.
1084 * </p>
1085 *
1086 * @param array1
1087 * the first array, may be <code>null</code>
1088 * @param array2
1089 * the second array, may be <code>null</code>
1090 * @return <code>true</code> if length of arrays matches, treating
1091 * <code>null</code> as an empty array
1092 */
1093 public static boolean isSameLength( double[] array1, double[] array2 )
1094 {
1095 if ( ( array1 == null && array2 != null && array2.length > 0 )
1096 || ( array2 == null && array1 != null && array1.length > 0 )
1097 || ( array1 != null && array2 != null && array1.length != array2.length ) )
1098 {
1099 return false;
1100 }
1101 return true;
1102 }
1103
1104
1105 /**
1106 * <p>
1107 * Checks whether two arrays are the same length, treating <code>null</code>
1108 * arrays as length <code>0</code>.
1109 * </p>
1110 *
1111 * @param array1
1112 * the first array, may be <code>null</code>
1113 * @param array2
1114 * the second array, may be <code>null</code>
1115 * @return <code>true</code> if length of arrays matches, treating
1116 * <code>null</code> as an empty array
1117 */
1118 public static boolean isSameLength( float[] array1, float[] array2 )
1119 {
1120 if ( ( array1 == null && array2 != null && array2.length > 0 )
1121 || ( array2 == null && array1 != null && array1.length > 0 )
1122 || ( array1 != null && array2 != null && array1.length != array2.length ) )
1123 {
1124 return false;
1125 }
1126 return true;
1127 }
1128
1129
1130 /**
1131 * <p>
1132 * Checks whether two arrays are the same length, treating <code>null</code>
1133 * arrays as length <code>0</code>.
1134 * </p>
1135 *
1136 * @param array1
1137 * the first array, may be <code>null</code>
1138 * @param array2
1139 * the second array, may be <code>null</code>
1140 * @return <code>true</code> if length of arrays matches, treating
1141 * <code>null</code> as an empty array
1142 */
1143 public static boolean isSameLength( boolean[] array1, boolean[] array2 )
1144 {
1145 if ( ( array1 == null && array2 != null && array2.length > 0 )
1146 || ( array2 == null && array1 != null && array1.length > 0 )
1147 || ( array1 != null && array2 != null && array1.length != array2.length ) )
1148 {
1149 return false;
1150 }
1151 return true;
1152 }
1153
1154
1155 // -----------------------------------------------------------------------
1156 /**
1157 * <p>
1158 * Returns the length of the specified array. This method can deal with
1159 * <code>Object</code> arrays and with primitive arrays.
1160 * </p>
1161 * <p>
1162 * If the input array is <code>null</code>, <code>0</code> is returned.
1163 * </p>
1164 *
1165 * <pre>
1166 * ArrayUtils.getLength(null) = 0
1167 * ArrayUtils.getLength([]) = 0
1168 * ArrayUtils.getLength([null]) = 1
1169 * ArrayUtils.getLength([true, false]) = 2
1170 * ArrayUtils.getLength([1, 2, 3]) = 3
1171 * ArrayUtils.getLength(["a", "b", "c"]) = 3
1172 * </pre>
1173 *
1174 * @param array
1175 * the array to retrieve the length from, may be null
1176 * @return The length of the array, or <code>0</code> if the array is
1177 * <code>null</code>
1178 * @throws IllegalArgumentException
1179 * if the object arguement is not an array.
1180 */
1181 public static int getLength( Object array )
1182 {
1183 if ( array == null )
1184 {
1185 return 0;
1186 }
1187 else
1188 {
1189 return Array.getLength( array );
1190 }
1191 }
1192
1193
1194 /**
1195 * Returns the last index of the given array or -1 if empty or null. This
1196 * method can deal with <code>Object</code> arrays and with primitive
1197 * arrays. This value is one less than the size since arrays indices are
1198 * 0-based.
1199 * </p>
1200 *
1201 * <pre>
1202 * ArrayUtils.lastIndex(null) = -1
1203 * ArrayUtils.lastIndex([]) = -1
1204 * ArrayUtils.lastIndex([null]) = 0
1205 * ArrayUtils.lastIndex([true, false]) = 1
1206 * ArrayUtils.lastIndex([1, 2, 3]) = 2
1207 * ArrayUtils.lastIndex(["a", "b", "c"]) = 2
1208 * </pre>
1209 *
1210 * @param array
1211 * the array to return the last index for, may be null
1212 * @return the last index, -1 if empty or null
1213 * @throws IllegalArgumentException
1214 * if the object arguement is not an array.
1215 */
1216 public static int lastIndex( Object array )
1217 {
1218 return ArrayUtils.getLength( array ) - 1;
1219 }
1220
1221
1222 /**
1223 * <p>
1224 * Checks whether two arrays are the same type taking into account
1225 * multi-dimensional arrays.
1226 * </p>
1227 *
1228 * @param array1
1229 * the first array, must not be <code>null</code>
1230 * @param array2
1231 * the second array, must not be <code>null</code>
1232 * @return <code>true</code> if type of arrays matches
1233 * @throws IllegalArgumentException
1234 * if either array is <code>null</code>
1235 */
1236 public static boolean isSameType( Object array1, Object array2 )
1237 {
1238 if ( array1 == null || array2 == null )
1239 {
1240 throw new IllegalArgumentException( I18n.err( I18n.ERR_04337 ) );
1241 }
1242 return array1.getClass().getName().equals( array2.getClass().getName() );
1243 }
1244
1245
1246 // Reverse
1247 // -----------------------------------------------------------------------
1248 /**
1249 * <p>
1250 * Reverses the order of the given array.
1251 * </p>
1252 * <p>
1253 * There is no special handling for multi-dimensional arrays.
1254 * </p>
1255 * <p>
1256 * This method does nothing if <code>null</code> array input.
1257 * </p>
1258 *
1259 * @param array
1260 * the array to reverse, may be <code>null</code>
1261 */
1262 public static void reverse( Object[] array )
1263 {
1264 if ( array == null )
1265 {
1266 return;
1267 }
1268 int i = 0;
1269 int j = array.length - 1;
1270 Object tmp;
1271 while ( j > i )
1272 {
1273 tmp = array[j];
1274 array[j] = array[i];
1275 array[i] = tmp;
1276 j--;
1277 i++;
1278 }
1279 }
1280
1281
1282 /**
1283 * <p>
1284 * Reverses the order of the given array.
1285 * </p>
1286 * <p>
1287 * This method does nothing if <code>null</code> array input.
1288 * </p>
1289 *
1290 * @param array
1291 * the array to reverse, may be <code>null</code>
1292 */
1293 public static void reverse( long[] array )
1294 {
1295 if ( array == null )
1296 {
1297 return;
1298 }
1299 int i = 0;
1300 int j = array.length - 1;
1301 long tmp;
1302 while ( j > i )
1303 {
1304 tmp = array[j];
1305 array[j] = array[i];
1306 array[i] = tmp;
1307 j--;
1308 i++;
1309 }
1310 }
1311
1312
1313 /**
1314 * <p>
1315 * Reverses the order of the given array.
1316 * </p>
1317 * <p>
1318 * This method does nothing if <code>null</code> array input.
1319 * </p>
1320 *
1321 * @param array
1322 * the array to reverse, may be <code>null</code>
1323 */
1324 public static void reverse( int[] array )
1325 {
1326 if ( array == null )
1327 {
1328 return;
1329 }
1330 int i = 0;
1331 int j = array.length - 1;
1332 int tmp;
1333 while ( j > i )
1334 {
1335 tmp = array[j];
1336 array[j] = array[i];
1337 array[i] = tmp;
1338 j--;
1339 i++;
1340 }
1341 }
1342
1343
1344 /**
1345 * <p>
1346 * Reverses the order of the given array.
1347 * </p>
1348 * <p>
1349 * This method does nothing if <code>null</code> array input.
1350 * </p>
1351 *
1352 * @param array
1353 * the array to reverse, may be <code>null</code>
1354 */
1355 public static void reverse( short[] array )
1356 {
1357 if ( array == null )
1358 {
1359 return;
1360 }
1361 int i = 0;
1362 int j = array.length - 1;
1363 short tmp;
1364 while ( j > i )
1365 {
1366 tmp = array[j];
1367 array[j] = array[i];
1368 array[i] = tmp;
1369 j--;
1370 i++;
1371 }
1372 }
1373
1374
1375 /**
1376 * <p>
1377 * Reverses the order of the given array.
1378 * </p>
1379 * <p>
1380 * This method does nothing if <code>null</code> array input.
1381 * </p>
1382 *
1383 * @param array
1384 * the array to reverse, may be <code>null</code>
1385 */
1386 public static void reverse( char[] array )
1387 {
1388 if ( array == null )
1389 {
1390 return;
1391 }
1392 int i = 0;
1393 int j = array.length - 1;
1394 char tmp;
1395 while ( j > i )
1396 {
1397 tmp = array[j];
1398 array[j] = array[i];
1399 array[i] = tmp;
1400 j--;
1401 i++;
1402 }
1403 }
1404
1405
1406 /**
1407 * <p>
1408 * Reverses the order of the given array.
1409 * </p>
1410 * <p>
1411 * This method does nothing if <code>null</code> array input.
1412 * </p>
1413 *
1414 * @param array
1415 * the array to reverse, may be <code>null</code>
1416 */
1417 public static void reverse( byte[] array )
1418 {
1419 if ( array == null )
1420 {
1421 return;
1422 }
1423 int i = 0;
1424 int j = array.length - 1;
1425 byte tmp;
1426 while ( j > i )
1427 {
1428 tmp = array[j];
1429 array[j] = array[i];
1430 array[i] = tmp;
1431 j--;
1432 i++;
1433 }
1434 }
1435
1436
1437 /**
1438 * <p>
1439 * Reverses the order of the given array.
1440 * </p>
1441 * <p>
1442 * This method does nothing if <code>null</code> array input.
1443 * </p>
1444 *
1445 * @param array
1446 * the array to reverse, may be <code>null</code>
1447 */
1448 public static void reverse( double[] array )
1449 {
1450 if ( array == null )
1451 {
1452 return;
1453 }
1454 int i = 0;
1455 int j = array.length - 1;
1456 double tmp;
1457 while ( j > i )
1458 {
1459 tmp = array[j];
1460 array[j] = array[i];
1461 array[i] = tmp;
1462 j--;
1463 i++;
1464 }
1465 }
1466
1467
1468 /**
1469 * <p>
1470 * Reverses the order of the given array.
1471 * </p>
1472 * <p>
1473 * This method does nothing if <code>null</code> array input.
1474 * </p>
1475 *
1476 * @param array
1477 * the array to reverse, may be <code>null</code>
1478 */
1479 public static void reverse( float[] array )
1480 {
1481 if ( array == null )
1482 {
1483 return;
1484 }
1485 int i = 0;
1486 int j = array.length - 1;
1487 float tmp;
1488 while ( j > i )
1489 {
1490 tmp = array[j];
1491 array[j] = array[i];
1492 array[i] = tmp;
1493 j--;
1494 i++;
1495 }
1496 }
1497
1498
1499 /**
1500 * <p>
1501 * Reverses the order of the given array.
1502 * </p>
1503 * <p>
1504 * This method does nothing if <code>null</code> array input.
1505 * </p>
1506 *
1507 * @param array
1508 * the array to reverse, may be <code>null</code>
1509 */
1510 public static void reverse( boolean[] array )
1511 {
1512 if ( array == null )
1513 {
1514 return;
1515 }
1516 int i = 0;
1517 int j = array.length - 1;
1518 boolean tmp;
1519 while ( j > i )
1520 {
1521 tmp = array[j];
1522 array[j] = array[i];
1523 array[i] = tmp;
1524 j--;
1525 i++;
1526 }
1527 }
1528
1529
1530 // IndexOf search
1531 // ----------------------------------------------------------------------
1532
1533 // Object IndexOf
1534 // -----------------------------------------------------------------------
1535 /**
1536 * <p>
1537 * Find the index of the given object in the array.
1538 * </p>
1539 * <p>
1540 * This method returns <code>-1</code> if <code>null</code> array input.
1541 * </p>
1542 *
1543 * @param array
1544 * the array to search through for the object, may be
1545 * <code>null</code>
1546 * @param objectToFind
1547 * the object to find, may be <code>null</code>
1548 * @return the index of the object within the array, <code>-1</code> if
1549 * not found or <code>null</code> array input
1550 */
1551 public static int indexOf( Object[] array, Object objectToFind )
1552 {
1553 return indexOf( array, objectToFind, 0 );
1554 }
1555
1556
1557 /**
1558 * <p>
1559 * Find the index of the given object in the array starting at the given
1560 * index.
1561 * </p>
1562 * <p>
1563 * This method returns <code>-1</code> if <code>null</code> array input.
1564 * </p>
1565 * <p>
1566 * A negative startIndex is treated as zero. A startIndex larger than the
1567 * array length will return <code>-1</code>.
1568 * </p>
1569 *
1570 * @param array
1571 * the array to search through for the object, may be
1572 * <code>null</code>
1573 * @param objectToFind
1574 * the object to find, may be <code>null</code>
1575 * @param startIndex
1576 * the index to start searching at
1577 * @return the index of the object within the array starting at the index,
1578 * <code>-1</code> if not found or <code>null</code> array input
1579 */
1580 public static int indexOf( Object[] array, Object objectToFind, int startIndex )
1581 {
1582 if ( array == null )
1583 {
1584 return -1;
1585 }
1586 if ( startIndex < 0 )
1587 {
1588 startIndex = 0;
1589 }
1590 if ( objectToFind == null )
1591 {
1592 for ( int i = startIndex; i < array.length; i++ )
1593 {
1594 if ( array[i] == null )
1595 {
1596 return i;
1597 }
1598 }
1599 }
1600 else
1601 {
1602 for ( int i = startIndex; i < array.length; i++ )
1603 {
1604 if ( objectToFind.equals( array[i] ) )
1605 {
1606 return i;
1607 }
1608 }
1609 }
1610 return -1;
1611 }
1612
1613
1614 /**
1615 * <p>
1616 * Find the last index of the given object within the array.
1617 * </p>
1618 * <p>
1619 * This method returns <code>-1</code> if <code>null</code> array input.
1620 * </p>
1621 *
1622 * @param array
1623 * the array to travers backwords looking for the object, may be
1624 * <code>null</code>
1625 * @param objectToFind
1626 * the object to find, may be <code>null</code>
1627 * @return the last index of the object within the array, <code>-1</code>
1628 * if not found or <code>null</code> array input
1629 */
1630 public static int lastIndexOf( Object[] array, Object objectToFind )
1631 {
1632 return lastIndexOf( array, objectToFind, Integer.MAX_VALUE );
1633 }
1634
1635
1636 /**
1637 * <p>
1638 * Find the last index of the given object in the array starting at the
1639 * given index.
1640 * </p>
1641 * <p>
1642 * This method returns <code>-1</code> if <code>null</code> array input.
1643 * </p>
1644 * <p>
1645 * A negative startIndex will return <code>-1</code>. A startIndex larger
1646 * than the array length will search from the end of the array.
1647 * </p>
1648 *
1649 * @param array
1650 * the array to traverse for looking for the object, may be
1651 * <code>null</code>
1652 * @param objectToFind
1653 * the object to find, may be <code>null</code>
1654 * @param startIndex
1655 * the start index to travers backwards from
1656 * @return the last index of the object within the array, <code>-1</code>
1657 * if not found or <code>null</code> array input
1658 */
1659 public static int lastIndexOf( Object[] array, Object objectToFind, int startIndex )
1660 {
1661 if ( array == null )
1662 {
1663 return -1;
1664 }
1665 if ( startIndex < 0 )
1666 {
1667 return -1;
1668 }
1669 else if ( startIndex >= array.length )
1670 {
1671 startIndex = array.length - 1;
1672 }
1673 if ( objectToFind == null )
1674 {
1675 for ( int i = startIndex; i >= 0; i-- )
1676 {
1677 if ( array[i] == null )
1678 {
1679 return i;
1680 }
1681 }
1682 }
1683 else
1684 {
1685 for ( int i = startIndex; i >= 0; i-- )
1686 {
1687 if ( objectToFind.equals( array[i] ) )
1688 {
1689 return i;
1690 }
1691 }
1692 }
1693 return -1;
1694 }
1695
1696
1697 /**
1698 * <p>
1699 * Checks if the object is in the given array.
1700 * </p>
1701 * <p>
1702 * The method returns <code>false</code> if a <code>null</code> array is
1703 * passed in.
1704 * </p>
1705 *
1706 * @param array
1707 * the array to search through
1708 * @param objectToFind
1709 * the object to find
1710 * @return <code>true</code> if the array contains the object
1711 */
1712 public static boolean contains( Object[] array, Object objectToFind )
1713 {
1714 return ( indexOf( array, objectToFind ) != -1 );
1715 }
1716
1717
1718 // long IndexOf
1719 // -----------------------------------------------------------------------
1720 /**
1721 * <p>
1722 * Find the index of the given value in the array.
1723 * </p>
1724 * <p>
1725 * This method returns <code>-1</code> if <code>null</code> array input.
1726 * </p>
1727 *
1728 * @param array
1729 * the array to search through for the object, may be
1730 * <code>null</code>
1731 * @param valueToFind
1732 * the value to find
1733 * @return the index of the value within the array, <code>-1</code> if not
1734 * found or <code>null</code> array input
1735 */
1736 public static int indexOf( long[] array, long valueToFind )
1737 {
1738 return indexOf( array, valueToFind, 0 );
1739 }
1740
1741
1742 /**
1743 * <p>
1744 * Find the index of the given value in the array starting at the given
1745 * index.
1746 * </p>
1747 * <p>
1748 * This method returns <code>-1</code> if <code>null</code> array input.
1749 * </p>
1750 * <p>
1751 * A negative startIndex is treated as zero. A startIndex larger than the
1752 * array length will return -1.
1753 * </p>
1754 *
1755 * @param array
1756 * the array to search through for the object, may be
1757 * <code>null</code>
1758 * @param valueToFind
1759 * the value to find
1760 * @param startIndex
1761 * the index to start searching at
1762 * @return the index of the value within the array, <code>-1</code> if not
1763 * found or <code>null</code> array input
1764 */
1765 public static int indexOf( long[] array, long valueToFind, int startIndex )
1766 {
1767 if ( array == null )
1768 {
1769 return -1;
1770 }
1771 if ( startIndex < 0 )
1772 {
1773 startIndex = 0;
1774 }
1775 for ( int i = startIndex; i < array.length; i++ )
1776 {
1777 if ( valueToFind == array[i] )
1778 {
1779 return i;
1780 }
1781 }
1782 return -1;
1783 }
1784
1785
1786 /**
1787 * <p>
1788 * Find the last index of the given value within the array.
1789 * </p>
1790 * <p>
1791 * This method returns <code>-1</code> if <code>null</code> array input.
1792 * </p>
1793 *
1794 * @param array
1795 * the array to travers backwords looking for the object, may be
1796 * <code>null</code>
1797 * @param valueToFind
1798 * the object to find
1799 * @return the last index of the value within the array, <code>-1</code>
1800 * if not found or <code>null</code> array input
1801 */
1802 public static int lastIndexOf( long[] array, long valueToFind )
1803 {
1804 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE );
1805 }
1806
1807
1808 /**
1809 * <p>
1810 * Find the last index of the given value in the array starting at the given
1811 * index.
1812 * </p>
1813 * <p>
1814 * This method returns <code>-1</code> if <code>null</code> array input.
1815 * </p>
1816 * <p>
1817 * A negative startIndex will return -1. A startIndex larger than the array
1818 * length will search from the end of the array.
1819 * </p>
1820 *
1821 * @param array
1822 * the array to traverse for looking for the object, may be
1823 * <code>null</code>
1824 * @param valueToFind
1825 * the value to find
1826 * @param startIndex
1827 * the start index to travers backwards from
1828 * @return the last index of the value within the array, <code>-1</code>
1829 * if not found or <code>null</code> array input
1830 */
1831 public static int lastIndexOf( long[] array, long valueToFind, int startIndex )
1832 {
1833 if ( array == null )
1834 {
1835 return -1;
1836 }
1837 if ( startIndex < 0 )
1838 {
1839 return -1;
1840 }
1841 else if ( startIndex >= array.length )
1842 {
1843 startIndex = array.length - 1;
1844 }
1845 for ( int i = startIndex; i >= 0; i-- )
1846 {
1847 if ( valueToFind == array[i] )
1848 {
1849 return i;
1850 }
1851 }
1852 return -1;
1853 }
1854
1855
1856 /**
1857 * <p>
1858 * Checks if the value is in the given array.
1859 * </p>
1860 * <p>
1861 * The method returns <code>false</code> if a <code>null</code> array is
1862 * passed in.
1863 * </p>
1864 *
1865 * @param array
1866 * the array to search through
1867 * @param valueToFind
1868 * the value to find
1869 * @return <code>true</code> if the array contains the object
1870 */
1871 public static boolean contains( long[] array, long valueToFind )
1872 {
1873 return ( indexOf( array, valueToFind ) != -1 );
1874 }
1875
1876
1877 // int IndexOf
1878 // -----------------------------------------------------------------------
1879 /**
1880 * <p>
1881 * Find the index of the given value in the array.
1882 * </p>
1883 * <p>
1884 * This method returns <code>-1</code> if <code>null</code> array input.
1885 * </p>
1886 *
1887 * @param array
1888 * the array to search through for the object, may be
1889 * <code>null</code>
1890 * @param valueToFind
1891 * the value to find
1892 * @return the index of the value within the array, <code>-1</code> if not
1893 * found or <code>null</code> array input
1894 */
1895 public static int indexOf( int[] array, int valueToFind )
1896 {
1897 return indexOf( array, valueToFind, 0 );
1898 }
1899
1900
1901 /**
1902 * <p>
1903 * Find the index of the given value in the array starting at the given
1904 * index.
1905 * </p>
1906 * <p>
1907 * This method returns <code>-1</code> if <code>null</code> array input.
1908 * </p>
1909 * <p>
1910 * A negative startIndex is treated as zero. A startIndex larger than the
1911 * array length will return -1.
1912 * </p>
1913 *
1914 * @param array
1915 * the array to search through for the object, may be
1916 * <code>null</code>
1917 * @param valueToFind
1918 * the value to find
1919 * @param startIndex
1920 * the index to start searching at
1921 * @return the index of the value within the array, <code>-1</code> if not
1922 * found or <code>null</code> array input
1923 */
1924 public static int indexOf( int[] array, int valueToFind, int startIndex )
1925 {
1926 if ( array == null )
1927 {
1928 return -1;
1929 }
1930 if ( startIndex < 0 )
1931 {
1932 startIndex = 0;
1933 }
1934 for ( int i = startIndex; i < array.length; i++ )
1935 {
1936 if ( valueToFind == array[i] )
1937 {
1938 return i;
1939 }
1940 }
1941 return -1;
1942 }
1943
1944
1945 /**
1946 * <p>
1947 * Find the last index of the given value within the array.
1948 * </p>
1949 * <p>
1950 * This method returns <code>-1</code> if <code>null</code> array input.
1951 * </p>
1952 *
1953 * @param array
1954 * the array to travers backwords looking for the object, may be
1955 * <code>null</code>
1956 * @param valueToFind
1957 * the object to find
1958 * @return the last index of the value within the array, <code>-1</code>
1959 * if not found or <code>null</code> array input
1960 */
1961 public static int lastIndexOf( int[] array, int valueToFind )
1962 {
1963 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE );
1964 }
1965
1966
1967 /**
1968 * <p>
1969 * Find the last index of the given value in the array starting at the given
1970 * index.
1971 * </p>
1972 * <p>
1973 * This method returns <code>-1</code> if <code>null</code> array input.
1974 * </p>
1975 * <p>
1976 * A negative startIndex will return -1. A startIndex larger than the array
1977 * length will search from the end of the array.
1978 * </p>
1979 *
1980 * @param array
1981 * the array to traverse for looking for the object, may be
1982 * <code>null</code>
1983 * @param valueToFind
1984 * the value to find
1985 * @param startIndex
1986 * the start index to travers backwards from
1987 * @return the last index of the value within the array, <code>-1</code>
1988 * if not found or <code>null</code> array input
1989 */
1990 public static int lastIndexOf( int[] array, int valueToFind, int startIndex )
1991 {
1992 if ( array == null )
1993 {
1994 return -1;
1995 }
1996 if ( startIndex < 0 )
1997 {
1998 return -1;
1999 }
2000 else if ( startIndex >= array.length )
2001 {
2002 startIndex = array.length - 1;
2003 }
2004 for ( int i = startIndex; i >= 0; i-- )
2005 {
2006 if ( valueToFind == array[i] )
2007 {
2008 return i;
2009 }
2010 }
2011 return -1;
2012 }
2013
2014
2015 /**
2016 * <p>
2017 * Checks if the value is in the given array.
2018 * </p>
2019 * <p>
2020 * The method returns <code>false</code> if a <code>null</code> array is
2021 * passed in.
2022 * </p>
2023 *
2024 * @param array
2025 * the array to search through
2026 * @param valueToFind
2027 * the value to find
2028 * @return <code>true</code> if the array contains the object
2029 */
2030 public static boolean contains( int[] array, int valueToFind )
2031 {
2032 return ( indexOf( array, valueToFind ) != -1 );
2033 }
2034
2035
2036 // short IndexOf
2037 // -----------------------------------------------------------------------
2038 /**
2039 * <p>
2040 * Find the index of the given value in the array.
2041 * </p>
2042 * <p>
2043 * This method returns <code>-1</code> if <code>null</code> array input.
2044 * </p>
2045 *
2046 * @param array
2047 * the array to search through for the object, may be
2048 * <code>null</code>
2049 * @param valueToFind
2050 * the value to find
2051 * @return the index of the value within the array, <code>-1</code> if not
2052 * found or <code>null</code> array input
2053 */
2054 public static int indexOf( short[] array, short valueToFind )
2055 {
2056 return indexOf( array, valueToFind, 0 );
2057 }
2058
2059
2060 /**
2061 * <p>
2062 * Find the index of the given value in the array starting at the given
2063 * index.
2064 * </p>
2065 * <p>
2066 * This method returns <code>-1</code> if <code>null</code> array input.
2067 * </p>
2068 * <p>
2069 * A negative startIndex is treated as zero. A startIndex larger than the
2070 * array length will return -1.
2071 * </p>
2072 *
2073 * @param array
2074 * the array to search through for the object, may be
2075 * <code>null</code>
2076 * @param valueToFind
2077 * the value to find
2078 * @param startIndex
2079 * the index to start searching at
2080 * @return the index of the value within the array, <code>-1</code> if not
2081 * found or <code>null</code> array input
2082 */
2083 public static int indexOf( short[] array, short valueToFind, int startIndex )
2084 {
2085 if ( array == null )
2086 {
2087 return -1;
2088 }
2089 if ( startIndex < 0 )
2090 {
2091 startIndex = 0;
2092 }
2093 for ( int i = startIndex; i < array.length; i++ )
2094 {
2095 if ( valueToFind == array[i] )
2096 {
2097 return i;
2098 }
2099 }
2100 return -1;
2101 }
2102
2103
2104 /**
2105 * <p>
2106 * Find the last index of the given value within the array.
2107 * </p>
2108 * <p>
2109 * This method returns <code>-1</code> if <code>null</code> array input.
2110 * </p>
2111 *
2112 * @param array
2113 * the array to travers backwords looking for the object, may be
2114 * <code>null</code>
2115 * @param valueToFind
2116 * the object to find
2117 * @return the last index of the value within the array, <code>-1</code>
2118 * if not found or <code>null</code> array input
2119 */
2120 public static int lastIndexOf( short[] array, short valueToFind )
2121 {
2122 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE );
2123 }
2124
2125
2126 /**
2127 * <p>
2128 * Find the last index of the given value in the array starting at the given
2129 * index.
2130 * </p>
2131 * <p>
2132 * This method returns <code>-1</code> if <code>null</code> array input.
2133 * </p>
2134 * <p>
2135 * A negative startIndex will return -1. A startIndex larger than the array
2136 * length will search from the end of the array.
2137 * </p>
2138 *
2139 * @param array
2140 * the array to traverse for looking for the object, may be
2141 * <code>null</code>
2142 * @param valueToFind
2143 * the value to find
2144 * @param startIndex
2145 * the start index to travers backwards from
2146 * @return the last index of the value within the array, <code>-1</code>
2147 * if not found or <code>null</code> array input
2148 */
2149 public static int lastIndexOf( short[] array, short valueToFind, int startIndex )
2150 {
2151 if ( array == null )
2152 {
2153 return -1;
2154 }
2155 if ( startIndex < 0 )
2156 {
2157 return -1;
2158 }
2159 else if ( startIndex >= array.length )
2160 {
2161 startIndex = array.length - 1;
2162 }
2163 for ( int i = startIndex; i >= 0; i-- )
2164 {
2165 if ( valueToFind == array[i] )
2166 {
2167 return i;
2168 }
2169 }
2170 return -1;
2171 }
2172
2173
2174 /**
2175 * <p>
2176 * Checks if the value is in the given array.
2177 * </p>
2178 * <p>
2179 * The method returns <code>false</code> if a <code>null</code> array is
2180 * passed in.
2181 * </p>
2182 *
2183 * @param array
2184 * the array to search through
2185 * @param valueToFind
2186 * the value to find
2187 * @return <code>true</code> if the array contains the object
2188 */
2189 public static boolean contains( short[] array, short valueToFind )
2190 {
2191 return ( indexOf( array, valueToFind ) != -1 );
2192 }
2193
2194
2195 // char IndexOf
2196 // -----------------------------------------------------------------------
2197 /**
2198 * <p>
2199 * Find the index of the given value in the array.
2200 * </p>
2201 * <p>
2202 * This method returns <code>-1</code> if <code>null</code> array input.
2203 * </p>
2204 *
2205 * @param array
2206 * the array to search through for the object, may be
2207 * <code>null</code>
2208 * @param valueToFind
2209 * the value to find
2210 * @return the index of the value within the array, <code>-1</code> if not
2211 * found or <code>null</code> array input
2212 */
2213 public static int indexOf( char[] array, char valueToFind )
2214 {
2215 return indexOf( array, valueToFind, 0 );
2216 }
2217
2218
2219 /**
2220 * <p>
2221 * Find the index of the given value in the array starting at the given
2222 * index.
2223 * </p>
2224 * <p>
2225 * This method returns <code>-1</code> if <code>null</code> array input.
2226 * </p>
2227 * <p>
2228 * A negative startIndex is treated as zero. A startIndex larger than the
2229 * array length will return -1.
2230 * </p>
2231 *
2232 * @param array
2233 * the array to search through for the object, may be
2234 * <code>null</code>
2235 * @param valueToFind
2236 * the value to find
2237 * @param startIndex
2238 * the index to start searching at
2239 * @return the index of the value within the array, <code>-1</code> if not
2240 * found or <code>null</code> array input
2241 */
2242 public static int indexOf( char[] array, char valueToFind, int startIndex )
2243 {
2244 if ( array == null )
2245 {
2246 return -1;
2247 }
2248 if ( startIndex < 0 )
2249 {
2250 startIndex = 0;
2251 }
2252 for ( int i = startIndex; i < array.length; i++ )
2253 {
2254 if ( valueToFind == array[i] )
2255 {
2256 return i;
2257 }
2258 }
2259 return -1;
2260 }
2261
2262
2263 /**
2264 * <p>
2265 * Find the last index of the given value within the array.
2266 * </p>
2267 * <p>
2268 * This method returns <code>-1</code> if <code>null</code> array input.
2269 * </p>
2270 *
2271 * @param array
2272 * the array to travers backwords looking for the object, may be
2273 * <code>null</code>
2274 * @param valueToFind
2275 * the object to find
2276 * @return the last index of the value within the array, <code>-1</code>
2277 * if not found or <code>null</code> array input
2278 */
2279 public static int lastIndexOf( char[] array, char valueToFind )
2280 {
2281 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE );
2282 }
2283
2284
2285 /**
2286 * <p>
2287 * Find the last index of the given value in the array starting at the given
2288 * index.
2289 * </p>
2290 * <p>
2291 * This method returns <code>-1</code> if <code>null</code> array input.
2292 * </p>
2293 * <p>
2294 * A negative startIndex will return -1. A startIndex larger than the array
2295 * length will search from the end of the array.
2296 * </p>
2297 *
2298 * @param array
2299 * the array to traverse for looking for the object, may be
2300 * <code>null</code>
2301 * @param valueToFind
2302 * the value to find
2303 * @param startIndex
2304 * the start index to travers backwards from
2305 * @return the last index of the value within the array, <code>-1</code>
2306 * if not found or <code>null</code> array input
2307 */
2308 public static int lastIndexOf( char[] array, char valueToFind, int startIndex )
2309 {
2310 if ( array == null )
2311 {
2312 return -1;
2313 }
2314 if ( startIndex < 0 )
2315 {
2316 return -1;
2317 }
2318 else if ( startIndex >= array.length )
2319 {
2320 startIndex = array.length - 1;
2321 }
2322 for ( int i = startIndex; i >= 0; i-- )
2323 {
2324 if ( valueToFind == array[i] )
2325 {
2326 return i;
2327 }
2328 }
2329 return -1;
2330 }
2331
2332
2333 /**
2334 * <p>
2335 * Checks if the value is in the given array.
2336 * </p>
2337 * <p>
2338 * The method returns <code>false</code> if a <code>null</code> array is
2339 * passed in.
2340 * </p>
2341 *
2342 * @param array
2343 * the array to search through
2344 * @param valueToFind
2345 * the value to find
2346 * @return <code>true</code> if the array contains the object
2347 */
2348 public static boolean contains( char[] array, char valueToFind )
2349 {
2350 return ( indexOf( array, valueToFind ) != -1 );
2351 }
2352
2353
2354 // byte IndexOf
2355 // -----------------------------------------------------------------------
2356 /**
2357 * <p>
2358 * Find the index of the given value in the array.
2359 * </p>
2360 * <p>
2361 * This method returns <code>-1</code> if <code>null</code> array input.
2362 * </p>
2363 *
2364 * @param array
2365 * the array to search through for the object, may be
2366 * <code>null</code>
2367 * @param valueToFind
2368 * the value to find
2369 * @return the index of the value within the array, <code>-1</code> if not
2370 * found or <code>null</code> array input
2371 */
2372 public static int indexOf( byte[] array, byte valueToFind )
2373 {
2374 return indexOf( array, valueToFind, 0 );
2375 }
2376
2377
2378 /**
2379 * <p>
2380 * Find the index of the given value in the array starting at the given
2381 * index.
2382 * </p>
2383 * <p>
2384 * This method returns <code>-1</code> if <code>null</code> array input.
2385 * </p>
2386 * <p>
2387 * A negative startIndex is treated as zero. A startIndex larger than the
2388 * array length will return -1.
2389 * </p>
2390 *
2391 * @param array
2392 * the array to search through for the object, may be
2393 * <code>null</code>
2394 * @param valueToFind
2395 * the value to find
2396 * @param startIndex
2397 * the index to start searching at
2398 * @return the index of the value within the array, <code>-1</code> if not
2399 * found or <code>null</code> array input
2400 */
2401 public static int indexOf( byte[] array, byte valueToFind, int startIndex )
2402 {
2403 if ( array == null )
2404 {
2405 return -1;
2406 }
2407 if ( startIndex < 0 )
2408 {
2409 startIndex = 0;
2410 }
2411 for ( int i = startIndex; i < array.length; i++ )
2412 {
2413 if ( valueToFind == array[i] )
2414 {
2415 return i;
2416 }
2417 }
2418 return -1;
2419 }
2420
2421
2422 /**
2423 * <p>
2424 * Find the last index of the given value within the array.
2425 * </p>
2426 * <p>
2427 * This method returns <code>-1</code> if <code>null</code> array input.
2428 * </p>
2429 *
2430 * @param array
2431 * the array to travers backwords looking for the object, may be
2432 * <code>null</code>
2433 * @param valueToFind
2434 * the object to find
2435 * @return the last index of the value within the array, <code>-1</code>
2436 * if not found or <code>null</code> array input
2437 */
2438 public static int lastIndexOf( byte[] array, byte valueToFind )
2439 {
2440 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE );
2441 }
2442
2443
2444 /**
2445 * <p>
2446 * Find the last index of the given value in the array starting at the given
2447 * index.
2448 * </p>
2449 * <p>
2450 * This method returns <code>-1</code> if <code>null</code> array input.
2451 * </p>
2452 * <p>
2453 * A negative startIndex will return -1. A startIndex larger than the array
2454 * length will search from the end of the array.
2455 * </p>
2456 *
2457 * @param array
2458 * the array to traverse for looking for the object, may be
2459 * <code>null</code>
2460 * @param valueToFind
2461 * the value to find
2462 * @param startIndex
2463 * the start index to travers backwards from
2464 * @return the last index of the value within the array, <code>-1</code>
2465 * if not found or <code>null</code> array input
2466 */
2467 public static int lastIndexOf( byte[] array, byte valueToFind, int startIndex )
2468 {
2469 if ( array == null )
2470 {
2471 return -1;
2472 }
2473 if ( startIndex < 0 )
2474 {
2475 return -1;
2476 }
2477 else if ( startIndex >= array.length )
2478 {
2479 startIndex = array.length - 1;
2480 }
2481 for ( int i = startIndex; i >= 0; i-- )
2482 {
2483 if ( valueToFind == array[i] )
2484 {
2485 return i;
2486 }
2487 }
2488 return -1;
2489 }
2490
2491
2492 /**
2493 * <p>
2494 * Checks if the value is in the given array.
2495 * </p>
2496 * <p>
2497 * The method returns <code>false</code> if a <code>null</code> array is
2498 * passed in.
2499 * </p>
2500 *
2501 * @param array
2502 * the array to search through
2503 * @param valueToFind
2504 * the value to find
2505 * @return <code>true</code> if the array contains the object
2506 */
2507 public static boolean contains( byte[] array, byte valueToFind )
2508 {
2509 return ( indexOf( array, valueToFind ) != -1 );
2510 }
2511
2512
2513 // double IndexOf
2514 // -----------------------------------------------------------------------
2515 /**
2516 * <p>
2517 * Find the index of the given value in the array.
2518 * </p>
2519 * <p>
2520 * This method returns <code>-1</code> if <code>null</code> array input.
2521 * </p>
2522 *
2523 * @param array
2524 * the array to search through for the object, may be
2525 * <code>null</code>
2526 * @param valueToFind
2527 * the value to find
2528 * @return the index of the value within the array, <code>-1</code> if not
2529 * found or <code>null</code> array input
2530 */
2531 public static int indexOf( double[] array, double valueToFind )
2532 {
2533 return indexOf( array, valueToFind, 0 );
2534 }
2535
2536
2537 /**
2538 * <p>
2539 * Find the index of the given value within a given tolerance in the array.
2540 * This method will return the index of the first value which falls between
2541 * the region defined by valueToFind - tolerance and valueToFind +
2542 * tolerance.
2543 * </p>
2544 * <p>
2545 * This method returns <code>-1</code> if <code>null</code> array input.
2546 * </p>
2547 *
2548 * @param array
2549 * the array to search through for the object, may be
2550 * <code>null</code>
2551 * @param valueToFind
2552 * the value to find
2553 * @param tolerance
2554 * tolerance of the search
2555 * @return the index of the value within the array, <code>-1</code> if not
2556 * found or <code>null</code> array input
2557 */
2558 public static int indexOf( double[] array, double valueToFind, double tolerance )
2559 {
2560 return indexOf( array, valueToFind, 0, tolerance );
2561 }
2562
2563
2564 /**
2565 * <p>
2566 * Find the index of the given value in the array starting at the given
2567 * index.
2568 * </p>
2569 * <p>
2570 * This method returns <code>-1</code> if <code>null</code> array input.
2571 * </p>
2572 * <p>
2573 * A negative startIndex is treated as zero. A startIndex larger than the
2574 * array length will return -1.
2575 * </p>
2576 *
2577 * @param array
2578 * the array to search through for the object, may be
2579 * <code>null</code>
2580 * @param valueToFind
2581 * the value to find
2582 * @param startIndex
2583 * the index to start searching at
2584 * @return the index of the value within the array, <code>-1</code> if not
2585 * found or <code>null</code> array input
2586 */
2587 public static int indexOf( double[] array, double valueToFind, int startIndex )
2588 {
2589 if ( ArrayUtils.isEmpty( array ) )
2590 {
2591 return -1;
2592 }
2593 if ( startIndex < 0 )
2594 {
2595 startIndex = 0;
2596 }
2597 for ( int i = startIndex; i < array.length; i++ )
2598 {
2599 if ( valueToFind == array[i] )
2600 {
2601 return i;
2602 }
2603 }
2604 return -1;
2605 }
2606
2607
2608 /**
2609 * <p>
2610 * Find the index of the given value in the array starting at the given
2611 * index. This method will return the index of the first value which falls
2612 * between the region defined by valueToFind - tolerance and valueToFind +
2613 * tolerance.
2614 * </p>
2615 * <p>
2616 * This method returns <code>-1</code> if <code>null</code> array input.
2617 * </p>
2618 * <p>
2619 * A negative startIndex is treated as zero. A startIndex larger than the
2620 * array length will return -1.
2621 * </p>
2622 *
2623 * @param array
2624 * the array to search through for the object, may be
2625 * <code>null</code>
2626 * @param valueToFind
2627 * the value to find
2628 * @param startIndex
2629 * the index to start searching at
2630 * @param tolerance
2631 * tolerance of the search
2632 * @return the index of the value within the array, <code>-1</code> if not
2633 * found or <code>null</code> array input
2634 */
2635 public static int indexOf( double[] array, double valueToFind, int startIndex, double tolerance )
2636 {
2637 if ( ArrayUtils.isEmpty( array ) )
2638 {
2639 return -1;
2640 }
2641 if ( startIndex < 0 )
2642 {
2643 startIndex = 0;
2644 }
2645 double min = valueToFind - tolerance;
2646 double max = valueToFind + tolerance;
2647 for ( int i = startIndex; i < array.length; i++ )
2648 {
2649 if ( array[i] >= min && array[i] <= max )
2650 {
2651 return i;
2652 }
2653 }
2654 return -1;
2655 }
2656
2657
2658 /**
2659 * <p>
2660 * Find the last index of the given value within the array.
2661 * </p>
2662 * <p>
2663 * This method returns <code>-1</code> if <code>null</code> array input.
2664 * </p>
2665 *
2666 * @param array
2667 * the array to travers backwords looking for the object, may be
2668 * <code>null</code>
2669 * @param valueToFind
2670 * the object to find
2671 * @return the last index of the value within the array, <code>-1</code>
2672 * if not found or <code>null</code> array input
2673 */
2674 public static int lastIndexOf( double[] array, double valueToFind )
2675 {
2676 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE );
2677 }
2678
2679
2680 /**
2681 * <p>
2682 * Find the last index of the given value within a given tolerance in the
2683 * array. This method will return the index of the last value which falls
2684 * between the region defined by valueToFind - tolerance and valueToFind +
2685 * tolerance.
2686 * </p>
2687 * <p>
2688 * This method returns <code>-1</code> if <code>null</code> array input.
2689 * </p>
2690 *
2691 * @param array
2692 * the array to search through for the object, may be
2693 * <code>null</code>
2694 * @param valueToFind
2695 * the value to find
2696 * @param tolerance
2697 * tolerance of the search
2698 * @return the index of the value within the array, <code>-1</code> if not
2699 * found or <code>null</code> array input
2700 */
2701 public static int lastIndexOf( double[] array, double valueToFind, double tolerance )
2702 {
2703 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE, tolerance );
2704 }
2705
2706
2707 /**
2708 * <p>
2709 * Find the last index of the given value in the array starting at the given
2710 * index.
2711 * </p>
2712 * <p>
2713 * This method returns <code>-1</code> if <code>null</code> array input.
2714 * </p>
2715 * <p>
2716 * A negative startIndex will return -1. A startIndex larger than the array
2717 * length will search from the end of the array.
2718 * </p>
2719 *
2720 * @param array
2721 * the array to traverse for looking for the object, may be
2722 * <code>null</code>
2723 * @param valueToFind
2724 * the value to find
2725 * @param startIndex
2726 * the start index to travers backwards from
2727 * @return the last index of the value within the array, <code>-1</code>
2728 * if not found or <code>null</code> array input
2729 */
2730 public static int lastIndexOf( double[] array, double valueToFind, int startIndex )
2731 {
2732 if ( ArrayUtils.isEmpty( array ) )
2733 {
2734 return -1;
2735 }
2736 if ( startIndex < 0 )
2737 {
2738 return -1;
2739 }
2740 else if ( startIndex >= array.length )
2741 {
2742 startIndex = array.length - 1;
2743 }
2744 for ( int i = startIndex; i >= 0; i-- )
2745 {
2746 if ( valueToFind == array[i] )
2747 {
2748 return i;
2749 }
2750 }
2751 return -1;
2752 }
2753
2754
2755 /**
2756 * <p>
2757 * Find the last index of the given value in the array starting at the given
2758 * index. This method will return the index of the last value which falls
2759 * between the region defined by valueToFind - tolerance and valueToFind +
2760 * tolerance.
2761 * </p>
2762 * <p>
2763 * This method returns <code>-1</code> if <code>null</code> array input.
2764 * </p>
2765 * <p>
2766 * A negative startIndex will return -1. A startIndex larger than the array
2767 * length will search from the end of the array.
2768 * </p>
2769 *
2770 * @param array
2771 * the array to traverse for looking for the object, may be
2772 * <code>null</code>
2773 * @param valueToFind
2774 * the value to find
2775 * @param startIndex
2776 * the start index to travers backwards from
2777 * @param tolerance
2778 * search for value within plus/minus this amount
2779 * @return the last index of the value within the array, <code>-1</code>
2780 * if not found or <code>null</code> array input
2781 */
2782 public static int lastIndexOf( double[] array, double valueToFind, int startIndex, double tolerance )
2783 {
2784 if ( ArrayUtils.isEmpty( array ) )
2785 {
2786 return -1;
2787 }
2788 if ( startIndex < 0 )
2789 {
2790 return -1;
2791 }
2792 else if ( startIndex >= array.length )
2793 {
2794 startIndex = array.length - 1;
2795 }
2796 double min = valueToFind - tolerance;
2797 double max = valueToFind + tolerance;
2798 for ( int i = startIndex; i >= 0; i-- )
2799 {
2800 if ( array[i] >= min && array[i] <= max )
2801 {
2802 return i;
2803 }
2804 }
2805 return -1;
2806 }
2807
2808
2809 /**
2810 * <p>
2811 * Checks if the value is in the given array.
2812 * </p>
2813 * <p>
2814 * The method returns <code>false</code> if a <code>null</code> array is
2815 * passed in.
2816 * </p>
2817 *
2818 * @param array
2819 * the array to search through
2820 * @param valueToFind
2821 * the value to find
2822 * @return <code>true</code> if the array contains the object
2823 */
2824 public static boolean contains( double[] array, double valueToFind )
2825 {
2826 return ( indexOf( array, valueToFind ) != -1 );
2827 }
2828
2829
2830 /**
2831 * <p>
2832 * Checks if a value falling within the given tolerance is in the given
2833 * array. If the array contains a value within the inclusive range defined
2834 * by (value - tolerance) to (value + tolerance).
2835 * </p>
2836 * <p>
2837 * The method returns <code>false</code> if a <code>null</code> array is
2838 * passed in.
2839 * </p>
2840 *
2841 * @param array
2842 * the array to search
2843 * @param valueToFind
2844 * the value to find
2845 * @param tolerance
2846 * the array contains the tolerance of the search
2847 * @return true if value falling within tolerance is in array
2848 */
2849 public static boolean contains( double[] array, double valueToFind, double tolerance )
2850 {
2851 return ( indexOf( array, valueToFind, 0, tolerance ) != -1 );
2852 }
2853
2854
2855 // float IndexOf
2856 // -----------------------------------------------------------------------
2857 /**
2858 * <p>
2859 * Find the index of the given value in the array.
2860 * </p>
2861 * <p>
2862 * This method returns <code>-1</code> if <code>null</code> array input.
2863 * </p>
2864 *
2865 * @param array
2866 * the array to search through for the object, may be
2867 * <code>null</code>
2868 * @param valueToFind
2869 * the value to find
2870 * @return the index of the value within the array, <code>-1</code> if not
2871 * found or <code>null</code> array input
2872 */
2873 public static int indexOf( float[] array, float valueToFind )
2874 {
2875 return indexOf( array, valueToFind, 0 );
2876 }
2877
2878
2879 /**
2880 * <p>
2881 * Find the index of the given value in the array starting at the given
2882 * index.
2883 * </p>
2884 * <p>
2885 * This method returns <code>-1</code> if <code>null</code> array input.
2886 * </p>
2887 * <p>
2888 * A negative startIndex is treated as zero. A startIndex larger than the
2889 * array length will return -1.
2890 * </p>
2891 *
2892 * @param array
2893 * the array to search through for the object, may be
2894 * <code>null</code>
2895 * @param valueToFind
2896 * the value to find
2897 * @param startIndex
2898 * the index to start searching at
2899 * @return the index of the value within the array, <code>-1</code> if not
2900 * found or <code>null</code> array input
2901 */
2902 public static int indexOf( float[] array, float valueToFind, int startIndex )
2903 {
2904 if ( ArrayUtils.isEmpty( array ) )
2905 {
2906 return -1;
2907 }
2908 if ( startIndex < 0 )
2909 {
2910 startIndex = 0;
2911 }
2912 for ( int i = startIndex; i < array.length; i++ )
2913 {
2914 if ( valueToFind == array[i] )
2915 {
2916 return i;
2917 }
2918 }
2919 return -1;
2920 }
2921
2922
2923 /**
2924 * <p>
2925 * Find the last index of the given value within the array.
2926 * </p>
2927 * <p>
2928 * This method returns <code>-1</code> if <code>null</code> array input.
2929 * </p>
2930 *
2931 * @param array
2932 * the array to travers backwords looking for the object, may be
2933 * <code>null</code>
2934 * @param valueToFind
2935 * the object to find
2936 * @return the last index of the value within the array, <code>-1</code>
2937 * if not found or <code>null</code> array input
2938 */
2939 public static int lastIndexOf( float[] array, float valueToFind )
2940 {
2941 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE );
2942 }
2943
2944
2945 /**
2946 * <p>
2947 * Find the last index of the given value in the array starting at the given
2948 * index.
2949 * </p>
2950 * <p>
2951 * This method returns <code>-1</code> if <code>null</code> array input.
2952 * </p>
2953 * <p>
2954 * A negative startIndex will return -1. A startIndex larger than the array
2955 * length will search from the end of the array.
2956 * </p>
2957 *
2958 * @param array
2959 * the array to traverse for looking for the object, may be
2960 * <code>null</code>
2961 * @param valueToFind
2962 * the value to find
2963 * @param startIndex
2964 * the start index to travers backwards from
2965 * @return the last index of the value within the array, <code>-1</code>
2966 * if not found or <code>null</code> array input
2967 */
2968 public static int lastIndexOf( float[] array, float valueToFind, int startIndex )
2969 {
2970 if ( ArrayUtils.isEmpty( array ) )
2971 {
2972 return -1;
2973 }
2974 if ( startIndex < 0 )
2975 {
2976 return -1;
2977 }
2978 else if ( startIndex >= array.length )
2979 {
2980 startIndex = array.length - 1;
2981 }
2982 for ( int i = startIndex; i >= 0; i-- )
2983 {
2984 if ( valueToFind == array[i] )
2985 {
2986 return i;
2987 }
2988 }
2989 return -1;
2990 }
2991
2992
2993 /**
2994 * <p>
2995 * Checks if the value is in the given array.
2996 * </p>
2997 * <p>
2998 * The method returns <code>false</code> if a <code>null</code> array is
2999 * passed in.
3000 * </p>
3001 *
3002 * @param array
3003 * the array to search through
3004 * @param valueToFind
3005 * the value to find
3006 * @return <code>true</code> if the array contains the object
3007 */
3008 public static boolean contains( float[] array, float valueToFind )
3009 {
3010 return ( indexOf( array, valueToFind ) != -1 );
3011 }
3012
3013
3014 // boolean IndexOf
3015 // -----------------------------------------------------------------------
3016 /**
3017 * <p>
3018 * Find the index of the given value in the array.
3019 * </p>
3020 * <p>
3021 * This method returns <code>-1</code> if <code>null</code> array input.
3022 * </p>
3023 *
3024 * @param array
3025 * the array to search through for the object, may be
3026 * <code>null</code>
3027 * @param valueToFind
3028 * the value to find
3029 * @return the index of the value within the array, <code>-1</code> if not
3030 * found or <code>null</code> array input
3031 */
3032 public static int indexOf( boolean[] array, boolean valueToFind )
3033 {
3034 return indexOf( array, valueToFind, 0 );
3035 }
3036
3037
3038 /**
3039 * <p>
3040 * Find the index of the given value in the array starting at the given
3041 * index.
3042 * </p>
3043 * <p>
3044 * This method returns <code>-1</code> if <code>null</code> array input.
3045 * </p>
3046 * <p>
3047 * A negative startIndex is treated as zero. A startIndex larger than the
3048 * array length will return -1.
3049 * </p>
3050 *
3051 * @param array
3052 * the array to search through for the object, may be
3053 * <code>null</code>
3054 * @param valueToFind
3055 * the value to find
3056 * @param startIndex
3057 * the index to start searching at
3058 * @return the index of the value within the array, <code>-1</code> if not
3059 * found or <code>null</code> array input
3060 */
3061 public static int indexOf( boolean[] array, boolean valueToFind, int startIndex )
3062 {
3063 if ( ArrayUtils.isEmpty( array ) )
3064 {
3065 return -1;
3066 }
3067 if ( startIndex < 0 )
3068 {
3069 startIndex = 0;
3070 }
3071 for ( int i = startIndex; i < array.length; i++ )
3072 {
3073 if ( valueToFind == array[i] )
3074 {
3075 return i;
3076 }
3077 }
3078 return -1;
3079 }
3080
3081
3082 /**
3083 * <p>
3084 * Find the last index of the given value within the array.
3085 * </p>
3086 * <p>
3087 * This method returns <code>-1</code> if <code>null</code> array input.
3088 * </p>
3089 *
3090 * @param array
3091 * the array to travers backwords looking for the object, may be
3092 * <code>null</code>
3093 * @param valueToFind
3094 * the object to find
3095 * @return the last index of the value within the array, <code>-1</code>
3096 * if not found or <code>null</code> array input
3097 */
3098 public static int lastIndexOf( boolean[] array, boolean valueToFind )
3099 {
3100 return lastIndexOf( array, valueToFind, Integer.MAX_VALUE );
3101 }
3102
3103
3104 /**
3105 * <p>
3106 * Find the last index of the given value in the array starting at the given
3107 * index.
3108 * </p>
3109 * <p>
3110 * This method returns <code>-1</code> if <code>null</code> array input.
3111 * </p>
3112 * <p>
3113 * A negative startIndex will return -1. A startIndex larger than the array
3114 * length will search from the end of the array.
3115 * </p>
3116 *
3117 * @param array
3118 * the array to traverse for looking for the object, may be
3119 * <code>null</code>
3120 * @param valueToFind
3121 * the value to find
3122 * @param startIndex
3123 * the start index to travers backwards from
3124 * @return the last index of the value within the array, <code>-1</code>
3125 * if not found or <code>null</code> array input
3126 */
3127 public static int lastIndexOf( boolean[] array, boolean valueToFind, int startIndex )
3128 {
3129 if ( ArrayUtils.isEmpty( array ) )
3130 {
3131 return -1;
3132 }
3133 if ( startIndex < 0 )
3134 {
3135 return -1;
3136 }
3137 else if ( startIndex >= array.length )
3138 {
3139 startIndex = array.length - 1;
3140 }
3141 for ( int i = startIndex; i >= 0; i-- )
3142 {
3143 if ( valueToFind == array[i] )
3144 {
3145 return i;
3146 }
3147 }
3148 return -1;
3149 }
3150
3151
3152 /**
3153 * <p>
3154 * Checks if the value is in the given array.
3155 * </p>
3156 * <p>
3157 * The method returns <code>false</code> if a <code>null</code> array is
3158 * passed in.
3159 * </p>
3160 *
3161 * @param array
3162 * the array to search through
3163 * @param valueToFind
3164 * the value to find
3165 * @return <code>true</code> if the array contains the object
3166 */
3167 public static boolean contains( boolean[] array, boolean valueToFind )
3168 {
3169 return ( indexOf( array, valueToFind ) != -1 );
3170 }
3171
3172
3173 // Primitive/Object array converters
3174 // ----------------------------------------------------------------------
3175
3176 // Long array converters
3177 // ----------------------------------------------------------------------
3178 /**
3179 * <p>
3180 * Converts an array of object Longs to primitives.
3181 * </p>
3182 * <p>
3183 * This method returns <code>null</code> if <code>null</code> array
3184 * input.
3185 * </p>
3186 *
3187 * @param array
3188 * a <code>Long</code> array, may be <code>null</code>
3189 * @return a <code>long</code> array, <code>null</code> if null array
3190 * input
3191 * @throws NullPointerException
3192 * if array content is <code>null</code>
3193 */
3194 public static long[] toPrimitive( Long[] array )
3195 {
3196 if ( array == null )
3197 {
3198 return null;
3199 }
3200 else if ( array.length == 0 )
3201 {
3202 return EMPTY_LONG_ARRAY;
3203 }
3204 final long[] result = new long[array.length];
3205 for ( int i = 0; i < array.length; i++ )
3206 {
3207 result[i] = array[i].longValue();
3208 }
3209 return result;
3210 }
3211
3212
3213 /**
3214 * <p>
3215 * Converts an array of object Long to primitives handling <code>null</code>.
3216 * </p>
3217 * <p>
3218 * This method returns <code>null</code> if <code>null</code> array
3219 * input.
3220 * </p>
3221 *
3222 * @param array
3223 * a <code>Long</code> array, may be <code>null</code>
3224 * @param valueForNull
3225 * the value to insert if <code>null</code> found
3226 * @return a <code>long</code> array, <code>null</code> if null array
3227 * input
3228 */
3229 public static long[] toPrimitive( Long[] array, long valueForNull )
3230 {
3231 if ( array == null )
3232 {
3233 return null;
3234 }
3235 else if ( array.length == 0 )
3236 {
3237 return EMPTY_LONG_ARRAY;
3238 }
3239 final long[] result = new long[array.length];
3240 for ( int i = 0; i < array.length; i++ )
3241 {
3242 Long b = array[i];
3243 result[i] = ( b == null ? valueForNull : b.longValue() );
3244 }
3245 return result;
3246 }
3247
3248
3249 /**
3250 * <p>
3251 * Converts an array of primitive longs to objects.
3252 * </p>
3253 * <p>
3254 * This method returns <code>null</code> if <code>null</code> array
3255 * input.
3256 * </p>
3257 *
3258 * @param array
3259 * a <code>long</code> array
3260 * @return a <code>Long</code> array, <code>null</code> if null array
3261 * input
3262 */
3263 public static Long[] toObject( long[] array )
3264 {
3265 if ( array == null )
3266 {
3267 return null;
3268 }
3269 else if ( array.length == 0 )
3270 {
3271 return EMPTY_LONG_OBJECT_ARRAY;
3272 }
3273 final Long[] result = new Long[array.length];
3274 for ( int i = 0; i < array.length; i++ )
3275 {
3276 result[i] = new Long( array[i] );
3277 }
3278 return result;
3279 }
3280
3281
3282 // Int array converters
3283 // ----------------------------------------------------------------------
3284 /**
3285 * <p>
3286 * Converts an array of object Integers to primitives.
3287 * </p>
3288 * <p>
3289 * This method returns <code>null</code> if <code>null</code> array
3290 * input.
3291 * </p>
3292 *
3293 * @param array
3294 * a <code>Integer</code> array, may be <code>null</code>
3295 * @return an <code>int</code> array, <code>null</code> if null array
3296 * input
3297 * @throws NullPointerException
3298 * if array content is <code>null</code>
3299 */
3300 public static int[] toPrimitive( Integer[] array )
3301 {
3302 if ( array == null )
3303 {
3304 return null;
3305 }
3306 else if ( array.length == 0 )
3307 {
3308 return EMPTY_INT_ARRAY;
3309 }
3310 final int[] result = new int[array.length];
3311 for ( int i = 0; i < array.length; i++ )
3312 {
3313 result[i] = array[i].intValue();
3314 }
3315 return result;
3316 }
3317
3318
3319 /**
3320 * <p>
3321 * Converts an array of object Integer to primitives handling
3322 * <code>null</code>.
3323 * </p>
3324 * <p>
3325 * This method returns <code>null</code> if <code>null</code> array
3326 * input.
3327 * </p>
3328 *
3329 * @param array
3330 * a <code>Integer</code> array, may be <code>null</code>
3331 * @param valueForNull
3332 * the value to insert if <code>null</code> found
3333 * @return an <code>int</code> array, <code>null</code> if null array
3334 * input
3335 */
3336 public static int[] toPrimitive( Integer[] array, int valueForNull )
3337 {
3338 if ( array == null )
3339 {
3340 return null;
3341 }
3342 else if ( array.length == 0 )
3343 {
3344 return EMPTY_INT_ARRAY;
3345 }
3346 final int[] result = new int[array.length];
3347 for ( int i = 0; i < array.length; i++ )
3348 {
3349 Integer b = array[i];
3350 result[i] = ( b == null ? valueForNull : b.intValue() );
3351 }
3352 return result;
3353 }
3354
3355
3356 /**
3357 * <p>
3358 * Converts an array of primitive ints to objects.
3359 * </p>
3360 * <p>
3361 * This method returns <code>null</code> if <code>null</code> array
3362 * input.
3363 * </p>
3364 *
3365 * @param array
3366 * an <code>int</code> array
3367 * @return an <code>Integer</code> array, <code>null</code> if null
3368 * array input
3369 */
3370 public static Integer[] toObject( int[] array )
3371 {
3372 if ( array == null )
3373 {
3374 return null;
3375 }
3376 else if ( array.length == 0 )
3377 {
3378 return EMPTY_INTEGER_OBJECT_ARRAY;
3379 }
3380 final Integer[] result = new Integer[array.length];
3381 for ( int i = 0; i < array.length; i++ )
3382 {
3383 result[i] = new Integer( array[i] );
3384 }
3385 return result;
3386 }
3387
3388
3389 // Short array converters
3390 // ----------------------------------------------------------------------
3391 /**
3392 * <p>
3393 * Converts an array of object Shorts to primitives.
3394 * </p>
3395 * <p>
3396 * This method returns <code>null</code> if <code>null</code> array
3397 * input.
3398 * </p>
3399 *
3400 * @param array
3401 * a <code>Short</code> array, may be <code>null</code>
3402 * @return a <code>byte</code> array, <code>null</code> if null array
3403 * input
3404 * @throws NullPointerException
3405 * if array content is <code>null</code>
3406 */
3407 public static short[] toPrimitive( Short[] array )
3408 {
3409 if ( array == null )
3410 {
3411 return null;
3412 }
3413 else if ( array.length == 0 )
3414 {
3415 return EMPTY_SHORT_ARRAY;
3416 }
3417 final short[] result = new short[array.length];
3418 for ( int i = 0; i < array.length; i++ )
3419 {
3420 result[i] = array[i].shortValue();
3421 }
3422 return result;
3423 }
3424
3425
3426 /**
3427 * <p>
3428 * Converts an array of object Short to primitives handling
3429 * <code>null</code>.
3430 * </p>
3431 * <p>
3432 * This method returns <code>null</code> if <code>null</code> array
3433 * input.
3434 * </p>
3435 *
3436 * @param array
3437 * a <code>Short</code> array, may be <code>null</code>
3438 * @param valueForNull
3439 * the value to insert if <code>null</code> found
3440 * @return a <code>byte</code> array, <code>null</code> if null array
3441 * input
3442 */
3443 public static short[] toPrimitive( Short[] array, short valueForNull )
3444 {
3445 if ( array == null )
3446 {
3447 return null;
3448 }
3449 else if ( array.length == 0 )
3450 {
3451 return EMPTY_SHORT_ARRAY;
3452 }
3453 final short[] result = new short[array.length];
3454 for ( int i = 0; i < array.length; i++ )
3455 {
3456 Short b = array[i];
3457 result[i] = ( b == null ? valueForNull : b.shortValue() );
3458 }
3459 return result;
3460 }
3461
3462
3463 /**
3464 * <p>
3465 * Converts an array of primitive shorts to objects.
3466 * </p>
3467 * <p>
3468 * This method returns <code>null</code> if <code>null</code> array
3469 * input.
3470 * </p>
3471 *
3472 * @param array
3473 * a <code>short</code> array
3474 * @return a <code>Short</code> array, <code>null</code> if null array
3475 * input
3476 */
3477 public static Short[] toObject( short[] array )
3478 {
3479 if ( array == null )
3480 {
3481 return null;
3482 }
3483 else if ( array.length == 0 )
3484 {
3485 return EMPTY_SHORT_OBJECT_ARRAY;
3486 }
3487 final Short[] result = new Short[array.length];
3488 for ( int i = 0; i < array.length; i++ )
3489 {
3490 result[i] = new Short( array[i] );
3491 }
3492 return result;
3493 }
3494
3495
3496 // Byte array converters
3497 // ----------------------------------------------------------------------
3498 /**
3499 * <p>
3500 * Converts an array of object Bytes to primitives.
3501 * </p>
3502 * <p>
3503 * This method returns <code>null</code> if <code>null</code> array
3504 * input.
3505 * </p>
3506 *
3507 * @param array
3508 * a <code>Byte</code> array, may be <code>null</code>
3509 * @return a <code>byte</code> array, <code>null</code> if null array
3510 * input
3511 * @throws NullPointerException
3512 * if array content is <code>null</code>
3513 */
3514 public static byte[] toPrimitive( Byte[] array )
3515 {
3516 if ( array == null )
3517 {
3518 return null;
3519 }
3520 else if ( array.length == 0 )
3521 {
3522 return EMPTY_BYTE_ARRAY;
3523 }
3524 final byte[] result = new byte[array.length];
3525 for ( int i = 0; i < array.length; i++ )
3526 {
3527 result[i] = array[i].byteValue();
3528 }
3529 return result;
3530 }
3531
3532
3533 /**
3534 * <p>
3535 * Converts an array of object Bytes to primitives handling
3536 * <code>null</code>.
3537 * </p>
3538 * <p>
3539 * This method returns <code>null</code> if <code>null</code> array
3540 * input.
3541 * </p>
3542 *
3543 * @param array
3544 * a <code>Byte</code> array, may be <code>null</code>
3545 * @param valueForNull
3546 * the value to insert if <code>null</code> found
3547 * @return a <code>byte</code> array, <code>null</code> if null array
3548 * input
3549 */
3550 public static byte[] toPrimitive( Byte[] array, byte valueForNull )
3551 {
3552 if ( array == null )
3553 {
3554 return null;
3555 }
3556 else if ( array.length == 0 )
3557 {
3558 return EMPTY_BYTE_ARRAY;
3559 }
3560 final byte[] result = new byte[array.length];
3561 for ( int i = 0; i < array.length; i++ )
3562 {
3563 Byte b = array[i];
3564 result[i] = ( b == null ? valueForNull : b.byteValue() );
3565 }
3566 return result;
3567 }
3568
3569
3570 /**
3571 * <p>
3572 * Converts an array of primitive bytes to objects.
3573 * </p>
3574 * <p>
3575 * This method returns <code>null</code> if <code>null</code> array
3576 * input.
3577 * </p>
3578 *
3579 * @param array
3580 * a <code>byte</code> array
3581 * @return a <code>Byte</code> array, <code>null</code> if null array
3582 * input
3583 */
3584 public static Byte[] toObject( byte[] array )
3585 {
3586 if ( array == null )
3587 {
3588 return null;
3589 }
3590 else if ( array.length == 0 )
3591 {
3592 return EMPTY_BYTE_OBJECT_ARRAY;
3593 }
3594 final Byte[] result = new Byte[array.length];
3595 for ( int i = 0; i < array.length; i++ )
3596 {
3597 result[i] = new Byte( array[i] );
3598 }
3599 return result;
3600 }
3601
3602
3603 // Double array converters
3604 // ----------------------------------------------------------------------
3605 /**
3606 * <p>
3607 * Converts an array of object Doubles to primitives.
3608 * </p>
3609 * <p>
3610 * This method returns <code>null</code> if <code>null</code> array
3611 * input.
3612 * </p>
3613 *
3614 * @param array
3615 * a <code>Double</code> array, may be <code>null</code>
3616 * @return a <code>double</code> array, <code>null</code> if null array
3617 * input
3618 * @throws NullPointerException
3619 * if array content is <code>null</code>
3620 */
3621 public static double[] toPrimitive( Double[] array )
3622 {
3623 if ( array == null )
3624 {
3625 return null;
3626 }
3627 else if ( array.length == 0 )
3628 {
3629 return EMPTY_DOUBLE_ARRAY;
3630 }
3631 final double[] result = new double[array.length];
3632 for ( int i = 0; i < array.length; i++ )
3633 {
3634 result[i] = array[i].doubleValue();
3635 }
3636 return result;
3637 }
3638
3639
3640 /**
3641 * <p>
3642 * Converts an array of object Doubles to primitives handling
3643 * <code>null</code>.
3644 * </p>
3645 * <p>
3646 * This method returns <code>null</code> if <code>null</code> array
3647 * input.
3648 * </p>
3649 *
3650 * @param array
3651 * a <code>Double</code> array, may be <code>null</code>
3652 * @param valueForNull
3653 * the value to insert if <code>null</code> found
3654 * @return a <code>double</code> array, <code>null</code> if null array
3655 * input
3656 */
3657 public static double[] toPrimitive( Double[] array, double valueForNull )
3658 {
3659 if ( array == null )
3660 {
3661 return null;
3662 }
3663 else if ( array.length == 0 )
3664 {
3665 return EMPTY_DOUBLE_ARRAY;
3666 }
3667 final double[] result = new double[array.length];
3668 for ( int i = 0; i < array.length; i++ )
3669 {
3670 Double b = array[i];
3671 result[i] = ( b == null ? valueForNull : b.doubleValue() );
3672 }
3673 return result;
3674 }
3675
3676
3677 /**
3678 * <p>
3679 * Converts an array of primitive doubles to objects.
3680 * </p>
3681 * <p>
3682 * This method returns <code>null</code> if <code>null</code> array
3683 * input.
3684 * </p>
3685 *
3686 * @param array
3687 * a <code>double</code> array
3688 * @return a <code>Double</code> array, <code>null</code> if null array
3689 * input
3690 */
3691 public static Double[] toObject( double[] array )
3692 {
3693 if ( array == null )
3694 {
3695 return null;
3696 }
3697 else if ( array.length == 0 )
3698 {
3699 return EMPTY_DOUBLE_OBJECT_ARRAY;
3700 }
3701 final Double[] result = new Double[array.length];
3702 for ( int i = 0; i < array.length; i++ )
3703 {
3704 result[i] = Double.valueOf( array[i] );
3705 }
3706 return result;
3707 }
3708
3709
3710 // Float array converters
3711 // ----------------------------------------------------------------------
3712 /**
3713 * <p>
3714 * Converts an array of object Floats to primitives.
3715 * </p>
3716 * <p>
3717 * This method returns <code>null</code> if <code>null</code> array
3718 * input.
3719 * </p>
3720 *
3721 * @param array
3722 * a <code>Float</code> array, may be <code>null</code>
3723 * @return a <code>float</code> array, <code>null</code> if null array
3724 * input
3725 * @throws NullPointerException
3726 * if array content is <code>null</code>
3727 */
3728 public static float[] toPrimitive( Float[] array )
3729 {
3730 if ( array == null )
3731 {
3732 return null;
3733 }
3734 else if ( array.length == 0 )
3735 {
3736 return EMPTY_FLOAT_ARRAY;
3737 }
3738 final float[] result = new float[array.length];
3739 for ( int i = 0; i < array.length; i++ )
3740 {
3741 result[i] = array[i].floatValue();
3742 }
3743 return result;
3744 }
3745
3746
3747 /**
3748 * <p>
3749 * Converts an array of object Floats to primitives handling
3750 * <code>null</code>.
3751 * </p>
3752 * <p>
3753 * This method returns <code>null</code> if <code>null</code> array
3754 * input.
3755 * </p>
3756 *
3757 * @param array
3758 * a <code>Float</code> array, may be <code>null</code>
3759 * @param valueForNull
3760 * the value to insert if <code>null</code> found
3761 * @return a <code>float</code> array, <code>null</code> if null array
3762 * input
3763 */
3764 public static float[] toPrimitive( Float[] array, float valueForNull )
3765 {
3766 if ( array == null )
3767 {
3768 return null;
3769 }
3770 else if ( array.length == 0 )
3771 {
3772 return EMPTY_FLOAT_ARRAY;
3773 }
3774 final float[] result = new float[array.length];
3775 for ( int i = 0; i < array.length; i++ )
3776 {
3777 Float b = array[i];
3778 result[i] = ( b == null ? valueForNull : b.floatValue() );
3779 }
3780 return result;
3781 }
3782
3783
3784 /**
3785 * <p>
3786 * Converts an array of primitive floats to objects.
3787 * </p>
3788 * <p>
3789 * This method returns <code>null</code> if <code>null</code> array
3790 * input.
3791 * </p>
3792 *
3793 * @param array
3794 * a <code>float</code> array
3795 * @return a <code>Float</code> array, <code>null</code> if null array
3796 * input
3797 */
3798 public static Float[] toObject( float[] array )
3799 {
3800 if ( array == null )
3801 {
3802 return null;
3803 }
3804 else if ( array.length == 0 )
3805 {
3806 return EMPTY_FLOAT_OBJECT_ARRAY;
3807 }
3808 final Float[] result = new Float[array.length];
3809 for ( int i = 0; i < array.length; i++ )
3810 {
3811 result[i] = Float.valueOf( array[i] );
3812 }
3813 return result;
3814 }
3815
3816
3817 // Boolean array converters
3818 // ----------------------------------------------------------------------
3819 /**
3820 * <p>
3821 * Converts an array of object Booleans to primitives.
3822 * </p>
3823 * <p>
3824 * This method returns <code>null</code> if <code>null</code> array
3825 * input.
3826 * </p>
3827 *
3828 * @param array
3829 * a <code>Boolean</code> array, may be <code>null</code>
3830 * @return a <code>boolean</code> array, <code>null</code> if null array
3831 * input
3832 * @throws NullPointerException
3833 * if array content is <code>null</code>
3834 */
3835 public static boolean[] toPrimitive( Boolean[] array )
3836 {
3837 if ( array == null )
3838 {
3839 return null;
3840 }
3841 else if ( array.length == 0 )
3842 {
3843 return EMPTY_BOOLEAN_ARRAY;
3844 }
3845 final boolean[] result = new boolean[array.length];
3846 for ( int i = 0; i < array.length; i++ )
3847 {
3848 result[i] = array[i].booleanValue();
3849 }
3850 return result;
3851 }
3852
3853
3854 /**
3855 * <p>
3856 * Converts an array of object Booleans to primitives handling
3857 * <code>null</code>.
3858 * </p>
3859 * <p>
3860 * This method returns <code>null</code> if <code>null</code> array
3861 * input.
3862 * </p>
3863 *
3864 * @param array
3865 * a <code>Boolean</code> array, may be <code>null</code>
3866 * @param valueForNull
3867 * the value to insert if <code>null</code> found
3868 * @return a <code>boolean</code> array, <code>null</code> if null array
3869 * input
3870 */
3871 public static boolean[] toPrimitive( Boolean[] array, boolean valueForNull )
3872 {
3873 if ( array == null )
3874 {
3875 return null;
3876 }
3877 else if ( array.length == 0 )
3878 {
3879 return EMPTY_BOOLEAN_ARRAY;
3880 }
3881 final boolean[] result = new boolean[array.length];
3882 for ( int i = 0; i < array.length; i++ )
3883 {
3884 Boolean b = array[i];
3885 result[i] = ( b == null ? valueForNull : b.booleanValue() );
3886 }
3887 return result;
3888 }
3889
3890
3891 /**
3892 * <p>
3893 * Converts an array of primitive booleans to objects.
3894 * </p>
3895 * <p>
3896 * This method returns <code>null</code> if <code>null</code> array
3897 * input.
3898 * </p>
3899 *
3900 * @param array
3901 * a <code>boolean</code> array
3902 * @return a <code>Boolean</code> array, <code>null</code> if null array
3903 * input
3904 */
3905 public static Boolean[] toObject( boolean[] array )
3906 {
3907 if ( array == null )
3908 {
3909 return null;
3910 }
3911 else if ( array.length == 0 )
3912 {
3913 return EMPTY_BOOLEAN_OBJECT_ARRAY;
3914 }
3915 final Boolean[] result = new Boolean[array.length];
3916 for ( int i = 0; i < array.length; i++ )
3917 {
3918 result[i] = ( array[i] ? Boolean.TRUE : Boolean.FALSE );
3919 }
3920 return result;
3921 }
3922
3923
3924 // ----------------------------------------------------------------------
3925 /**
3926 * <p>
3927 * Checks if an array of Objects is empty or <code>null</code>.
3928 * </p>
3929 *
3930 * @param array
3931 * the array to test
3932 * @return <code>true</code> if the array is empty or <code>null</code>
3933 * @since 2.1
3934 */
3935 public static boolean isEmpty( Object[] array )
3936 {
3937 if ( array == null || array.length == 0 )
3938 {
3939 return true;
3940 }
3941 return false;
3942 }
3943
3944
3945 /**
3946 * <p>
3947 * Checks if an array of primitive longs is empty or <code>null</code>.
3948 * </p>
3949 *
3950 * @param array
3951 * the array to test
3952 * @return <code>true</code> if the array is empty or <code>null</code>
3953 * @since 2.1
3954 */
3955 public static boolean isEmpty( long[] array )
3956 {
3957 if ( array == null || array.length == 0 )
3958 {
3959 return true;
3960 }
3961 return false;
3962 }
3963
3964
3965 /**
3966 * <p>
3967 * Checks if an array of primitive ints is empty or <code>null</code>.
3968 * </p>
3969 *
3970 * @param array
3971 * the array to test
3972 * @return <code>true</code> if the array is empty or <code>null</code>
3973 * @since 2.1
3974 */
3975 public static boolean isEmpty( int[] array )
3976 {
3977 if ( array == null || array.length == 0 )
3978 {
3979 return true;
3980 }
3981 return false;
3982 }
3983
3984
3985 /**
3986 * <p>
3987 * Checks if an array of primitive shorts is empty or <code>null</code>.
3988 * </p>
3989 *
3990 * @param array
3991 * the array to test
3992 * @return <code>true</code> if the array is empty or <code>null</code>
3993 * @since 2.1
3994 */
3995 public static boolean isEmpty( short[] array )
3996 {
3997 if ( array == null || array.length == 0 )
3998 {
3999 return true;
4000 }
4001 return false;
4002 }
4003
4004
4005 /**
4006 * <p>
4007 * Checks if an array of primitive chars is empty or <code>null</code>.
4008 * </p>
4009 *
4010 * @param array
4011 * the array to test
4012 * @return <code>true</code> if the array is empty or <code>null</code>
4013 * @since 2.1
4014 */
4015 public static boolean isEmpty( char[] array )
4016 {
4017 if ( array == null || array.length == 0 )
4018 {
4019 return true;
4020 }
4021 return false;
4022 }
4023
4024
4025 /**
4026 * <p>
4027 * Checks if an array of primitive bytes is empty or <code>null</code>.
4028 * </p>
4029 *
4030 * @param array
4031 * the array to test
4032 * @return <code>true</code> if the array is empty or <code>null</code>
4033 * @since 2.1
4034 */
4035 public static boolean isEmpty( byte[] array )
4036 {
4037 if ( array == null || array.length == 0 )
4038 {
4039 return true;
4040 }
4041 return false;
4042 }
4043
4044
4045 /**
4046 * <p>
4047 * Checks if an array of primitive doubles is empty or <code>null</code>.
4048 * </p>
4049 *
4050 * @param array
4051 * the array to test
4052 * @return <code>true</code> if the array is empty or <code>null</code>
4053 * @since 2.1
4054 */
4055 public static boolean isEmpty( double[] array )
4056 {
4057 if ( array == null || array.length == 0 )
4058 {
4059 return true;
4060 }
4061 return false;
4062 }
4063
4064
4065 /**
4066 * <p>
4067 * Checks if an array of primitive floats is empty or <code>null</code>.
4068 * </p>
4069 *
4070 * @param array
4071 * the array to test
4072 * @return <code>true</code> if the array is empty or <code>null</code>
4073 * @since 2.1
4074 */
4075 public static boolean isEmpty( float[] array )
4076 {
4077 if ( array == null || array.length == 0 )
4078 {
4079 return true;
4080 }
4081 return false;
4082 }
4083
4084
4085 /**
4086 * <p>
4087 * Checks if an array of primitive booleans is empty or <code>null</code>.
4088 * </p>
4089 *
4090 * @param array
4091 * the array to test
4092 * @return <code>true</code> if the array is empty or <code>null</code>
4093 * @since 2.1
4094 */
4095 public static boolean isEmpty( boolean[] array )
4096 {
4097 if ( array == null || array.length == 0 )
4098 {
4099 return true;
4100 }
4101 return false;
4102 }
4103
4104
4105 /**
4106 * <p>
4107 * Adds all the elements of the given arrays into a new array.
4108 * </p>
4109 * <p>
4110 * The new array contains all of the element of <code>array1</code>
4111 * followed by all of the elements <code>array2</code>. When an array is
4112 * returned, it is always a new array.
4113 * </p>
4114 *
4115 * <pre>
4116 * ArrayUtils.addAll(null, null) = null
4117 * ArrayUtils.addAll(array1, null) = cloned copy of array1
4118 * ArrayUtils.addAll(null, array2) = cloned copy of array2
4119 * ArrayUtils.addAll([], []) = []
4120 * ArrayUtils.addAll([null], [null]) = [null, null]
4121 * ArrayUtils.addAll(["a", "b", "c"], ["1", "2", "3"]) = ["a", "b", "c", "1", "2", "3"]
4122 * </pre>
4123 *
4124 * @param array1
4125 * the first array whose elements are added to the new array, may
4126 * be <code>null</code>
4127 * @param array2
4128 * the second array whose elements are added to the new array,
4129 * may be <code>null</code>
4130 * @return The new array, <code>null</code> if <code>null</code> array
4131 * inputs. The type of the new array is the type of the first array.
4132 * @since 2.1
4133 */
4134 public static Object[] addAll( Object[] array1, Object[] array2 )
4135 {
4136 if ( array1 == null )
4137 {
4138 return clone( array2 );
4139 }
4140 else if ( array2 == null )
4141 {
4142 return clone( array1 );
4143 }
4144 else
4145 {
4146 Object[] joinedArray = ( Object[] ) Array.newInstance( array1.getClass().getComponentType(), array1.length
4147 + array2.length );
4148 System.arraycopy( array1, 0, joinedArray, 0, array1.length );
4149 System.arraycopy( array2, 0, joinedArray, array1.length, array2.length );
4150 return joinedArray;
4151 }
4152 }
4153
4154
4155 /**
4156 * <p>
4157 * Copies the given array and adds the given element at the end of the new
4158 * array.
4159 * </p>
4160 * <p>
4161 * The new array contains the same elements of the input array plus the
4162 * given element in the last position. The component type of the new array
4163 * is the same as that of the input array.
4164 * </p>
4165 * <p>
4166 * If the input array is <code>null</code>, a new one element array is
4167 * returned whose component type is the same as the element.
4168 * </p>
4169 *
4170 * <pre>
4171 * ArrayUtils.add(null, null) = [null]
4172 * ArrayUtils.add(null, "a") = ["a"]
4173 * ArrayUtils.add(["a"], null) = ["a", null]
4174 * ArrayUtils.add(["a"], "b") = ["a", "b"]
4175 * ArrayUtils.add(["a", "b"], "c") = ["a", "b", "c"]
4176 * </pre>
4177 *
4178 * @param array
4179 * the array to "add" the element to, may be <code>null</code>
4180 * @param element
4181 * the object to add
4182 * @return A new array containing the existing elements plus the new element
4183 * @since 2.1
4184 */
4185 public static Object[] add( Object[] array, Object element )
4186 {
4187 Object newArray = copyArrayGrow1( array, element != null ? element.getClass() : Object.class );
4188 Array.set( newArray, lastIndex( newArray ), element );
4189 return ( Object[] ) newArray;
4190 }
4191
4192
4193 /**
4194 * <p>
4195 * Copies the given array and adds the given element at the end of the new
4196 * array.
4197 * </p>
4198 * <p>
4199 * The new array contains the same elements of the input array plus the
4200 * given element in the last position. The component type of the new array
4201 * is the same as that of the input array.
4202 * </p>
4203 * <p>
4204 * If the input array is <code>null</code>, a new one element array is
4205 * returned whose component type is the same as the element.
4206 * </p>
4207 *
4208 * <pre>
4209 * ArrayUtils.add(null, true) = [true]
4210 * ArrayUtils.add([true], false) = [true, false]
4211 * ArrayUtils.add([true, false], true) = [true, false, true]
4212 * </pre>
4213 *
4214 * @param array
4215 * the array to copy and add the element to, may be
4216 * <code>null</code>
4217 * @param element
4218 * the object to add at the last index of the new array
4219 * @return A new array containing the existing elements plus the new element
4220 * @since 2.1
4221 */
4222 public static boolean[] add( boolean[] array, boolean element )
4223 {
4224 boolean[] newArray = ( boolean[] ) copyArrayGrow1( array, Boolean.TYPE );
4225 newArray[lastIndex( newArray )] = element;
4226 return newArray;
4227 }
4228
4229
4230 /**
4231 * <p>
4232 * Copies the given array and adds the given element at the end of the new
4233 * array.
4234 * </p>
4235 * <p>
4236 * The new array contains the same elements of the input array plus the
4237 * given element in the last position. The component type of the new array
4238 * is the same as that of the input array.
4239 * </p>
4240 * <p>
4241 * If the input array is <code>null</code>, a new one element array is
4242 * returned whose component type is the same as the element.
4243 * </p>
4244 *
4245 * <pre>
4246 * ArrayUtils.add(null, 0) = [0]
4247 * ArrayUtils.add([1], 0) = [1, 0]
4248 * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
4249 * </pre>
4250 *
4251 * @param array
4252 * the array to copy and add the element to, may be
4253 * <code>null</code>
4254 * @param element
4255 * the object to add at the last index of the new array
4256 * @return A new array containing the existing elements plus the new element
4257 * @since 2.1
4258 */
4259 public static byte[] add( byte[] array, byte element )
4260 {
4261 byte[] newArray = ( byte[] ) copyArrayGrow1( array, Byte.TYPE );
4262 newArray[lastIndex( newArray )] = element;
4263 return newArray;
4264 }
4265
4266
4267 /**
4268 * <p>
4269 * Copies the given array and adds the given element at the end of the new
4270 * array.
4271 * </p>
4272 * <p>
4273 * The new array contains the same elements of the input array plus the
4274 * given element in the last position. The component type of the new array
4275 * is the same as that of the input array.
4276 * </p>
4277 * <p>
4278 * If the input array is <code>null</code>, a new one element array is
4279 * returned whose component type is the same as the element.
4280 * </p>
4281 *
4282 * <pre>
4283 * ArrayUtils.add(null, '0') = ['0']
4284 * ArrayUtils.add(['1'], '0') = ['1', '0']
4285 * ArrayUtils.add(['1', '0'], '1') = ['1', '0', '1']
4286 * </pre>
4287 *
4288 * @param array
4289 * the array to copy and add the element to, may be
4290 * <code>null</code>
4291 * @param element
4292 * the object to add at the last index of the new array
4293 * @return A new array containing the existing elements plus the new element
4294 * @since 2.1
4295 */
4296 public static char[] add( char[] array, char element )
4297 {
4298 char[] newArray = ( char[] ) copyArrayGrow1( array, Character.TYPE );
4299 newArray[lastIndex( newArray )] = element;
4300 return newArray;
4301 }
4302
4303
4304 /**
4305 * <p>
4306 * Copies the given array and adds the given element at the end of the new
4307 * array.
4308 * </p>
4309 * <p>
4310 * The new array contains the same elements of the input array plus the
4311 * given element in the last position. The component type of the new array
4312 * is the same as that of the input array.
4313 * </p>
4314 * <p>
4315 * If the input array is <code>null</code>, a new one element array is
4316 * returned whose component type is the same as the element.
4317 * </p>
4318 *
4319 * <pre>
4320 * ArrayUtils.add(null, 0) = [0]
4321 * ArrayUtils.add([1], 0) = [1, 0]
4322 * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
4323 * </pre>
4324 *
4325 * @param array
4326 * the array to copy and add the element to, may be
4327 * <code>null</code>
4328 * @param element
4329 * the object to add at the last index of the new array
4330 * @return A new array containing the existing elements plus the new element
4331 * @since 2.1
4332 */
4333 public static double[] add( double[] array, double element )
4334 {
4335 double[] newArray = ( double[] ) copyArrayGrow1( array, Double.TYPE );
4336 newArray[lastIndex( newArray )] = element;
4337 return newArray;
4338 }
4339
4340
4341 /**
4342 * <p>
4343 * Copies the given array and adds the given element at the end of the new
4344 * array.
4345 * </p>
4346 * <p>
4347 * The new array contains the same elements of the input array plus the
4348 * given element in the last position. The component type of the new array
4349 * is the same as that of the input array.
4350 * </p>
4351 * <p>
4352 * If the input array is <code>null</code>, a new one element array is
4353 * returned whose component type is the same as the element.
4354 * </p>
4355 *
4356 * <pre>
4357 * ArrayUtils.add(null, 0) = [0]
4358 * ArrayUtils.add([1], 0) = [1, 0]
4359 * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
4360 * </pre>
4361 *
4362 * @param array
4363 * the array to copy and add the element to, may be
4364 * <code>null</code>
4365 * @param element
4366 * the object to add at the last index of the new array
4367 * @return A new array containing the existing elements plus the new element
4368 * @since 2.1
4369 */
4370 public static float[] add( float[] array, float element )
4371 {
4372 float[] newArray = ( float[] ) copyArrayGrow1( array, Float.TYPE );
4373 newArray[lastIndex( newArray )] = element;
4374 return newArray;
4375 }
4376
4377
4378 /**
4379 * <p>
4380 * Copies the given array and adds the given element at the end of the new
4381 * array.
4382 * </p>
4383 * <p>
4384 * The new array contains the same elements of the input array plus the
4385 * given element in the last position. The component type of the new array
4386 * is the same as that of the input array.
4387 * </p>
4388 * <p>
4389 * If the input array is <code>null</code>, a new one element array is
4390 * returned whose component type is the same as the element.
4391 * </p>
4392 *
4393 * <pre>
4394 * ArrayUtils.add(null, 0) = [0]
4395 * ArrayUtils.add([1], 0) = [1, 0]
4396 * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
4397 * </pre>
4398 *
4399 * @param array
4400 * the array to copy and add the element to, may be
4401 * <code>null</code>
4402 * @param element
4403 * the object to add at the last index of the new array
4404 * @return A new array containing the existing elements plus the new element
4405 * @since 2.1
4406 */
4407 public static int[] add( int[] array, int element )
4408 {
4409 int[] newArray = ( int[] ) copyArrayGrow1( array, Integer.TYPE );
4410 newArray[lastIndex( newArray )] = element;
4411 return newArray;
4412 }
4413
4414
4415 /**
4416 * <p>
4417 * Copies the given array and adds the given element at the end of the new
4418 * array.
4419 * </p>
4420 * <p>
4421 * The new array contains the same elements of the input array plus the
4422 * given element in the last position. The component type of the new array
4423 * is the same as that of the input array.
4424 * </p>
4425 * <p>
4426 * If the input array is <code>null</code>, a new one element array is
4427 * returned whose component type is the same as the element.
4428 * </p>
4429 *
4430 * <pre>
4431 * ArrayUtils.add(null, 0) = [0]
4432 * ArrayUtils.add([1], 0) = [1, 0]
4433 * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
4434 * </pre>
4435 *
4436 * @param array
4437 * the array to copy and add the element to, may be
4438 * <code>null</code>
4439 * @param element
4440 * the object to add at the last index of the new array
4441 * @return A new array containing the existing elements plus the new element
4442 * @since 2.1
4443 */
4444 public static long[] add( long[] array, long element )
4445 {
4446 long[] newArray = ( long[] ) copyArrayGrow1( array, Long.TYPE );
4447 newArray[lastIndex( newArray )] = element;
4448 return newArray;
4449 }
4450
4451
4452 /**
4453 * <p>
4454 * Copies the given array and adds the given element at the end of the new
4455 * array.
4456 * </p>
4457 * <p>
4458 * The new array contains the same elements of the input array plus the
4459 * given element in the last position. The component type of the new array
4460 * is the same as that of the input array.
4461 * </p>
4462 * <p>
4463 * If the input array is <code>null</code>, a new one element array is
4464 * returned whose component type is the same as the element.
4465 * </p>
4466 *
4467 * <pre>
4468 * ArrayUtils.add(null, 0) = [0]
4469 * ArrayUtils.add([1], 0) = [1, 0]
4470 * ArrayUtils.add([1, 0], 1) = [1, 0, 1]
4471 * </pre>
4472 *
4473 * @param array
4474 * the array to copy and add the element to, may be
4475 * <code>null</code>
4476 * @param element
4477 * the object to add at the last index of the new array
4478 * @return A new array containing the existing elements plus the new element
4479 * @since 2.1
4480 */
4481 public static short[] add( short[] array, short element )
4482 {
4483 short[] newArray = ( short[] ) copyArrayGrow1( array, Short.TYPE );
4484 newArray[lastIndex( newArray )] = element;
4485 return newArray;
4486 }
4487
4488
4489 /**
4490 * Returns a copy of the given array of size 1 greater than the argument.
4491 * The last value of the array is left to the default value.
4492 *
4493 * @param array
4494 * The array to copy, must not be <code>null</code>.
4495 * @param newArrayComponentType
4496 * If <code>array</code> is <code>null</code>, create a size
4497 * 1 array of this type.
4498 * @return A new copy of the array of size 1 greater than the input.
4499 */
4500 private static Object copyArrayGrow1( Object array, Class<?> newArrayComponentType )
4501 {
4502 if ( array != null )
4503 {
4504 int arrayLength = Array.getLength( array );
4505 Object newArray = Array.newInstance( array.getClass().getComponentType(), arrayLength + 1 );
4506 System.arraycopy( array, 0, newArray, 0, arrayLength );
4507 return newArray;
4508 }
4509 else
4510 {
4511 return Array.newInstance( newArrayComponentType, 1 );
4512 }
4513 }
4514
4515
4516 /**
4517 * <p>
4518 * Inserts the specified element at the specified position in the array.
4519 * Shifts the element currently at that position (if any) and any subsequent
4520 * elements to the right (adds one to their indices).
4521 * </p>
4522 * <p>
4523 * This method returns a new array with the same elements of the input array
4524 * plus the given element on the specified position. The component type of
4525 * the returned array is always the same as that of the input array.
4526 * </p>
4527 * <p>
4528 * If the input array is <code>null</code>, a new one element array is
4529 * returned whose component type is the same as the element.
4530 * </p>
4531 *
4532 * <pre>
4533 * ArrayUtils.add(null, 0, null) = [null]
4534 * ArrayUtils.add(null, 0, "a") = ["a"]
4535 * ArrayUtils.add(["a"], 1, null) = ["a", null]
4536 * ArrayUtils.add(["a"], 1, "b") = ["a", "b"]
4537 * ArrayUtils.add(["a", "b"], 3, "c") = ["a", "b", "c"]
4538 * </pre>
4539 *
4540 * @param array
4541 * the array to add the element to, may be <code>null</code>
4542 * @param index
4543 * the position of the new object
4544 * @param element
4545 * the object to add
4546 * @return A new array containing the existing elements and the new element
4547 * @throws IndexOutOfBoundsException
4548 * if the index is out of range (index < 0 || index >
4549 * array.length).
4550 */
4551 public static Object[] add( Object[] array, int index, Object element )
4552 {
4553 if ( array == null )
4554 {
4555 if ( index != 0 )
4556 {
4557 throw new IndexOutOfBoundsException( I18n.err( I18n.ERR_04338, index ,0 ) );
4558 }
4559 Object joinedArray = Array.newInstance( element != null ? element.getClass() : Object.class, 1 );
4560 Array.set( joinedArray, 0, element );
4561 return ( Object[] ) joinedArray;
4562 }
4563 int length = array.length;
4564 if ( index > length || index < 0 )
4565 {
4566 throw new IndexOutOfBoundsException( I18n.err( I18n.ERR_04338, index, length ) );
4567 }
4568 Object result = Array.newInstance( array.getClass().getComponentType(), length + 1 );
4569 System.arraycopy( array, 0, result, 0, index );
4570 Array.set( result, index, element );
4571 if ( index < length )
4572 {
4573 System.arraycopy( array, index, result, index + 1, length - index );
4574 }
4575 return ( Object[] ) result;
4576 }
4577
4578
4579 /**
4580 * <p>
4581 * Removes the element at the specified position from the specified array.
4582 * All subsequent elements are shifted to the left (substracts one from
4583 * their indices).
4584 * </p>
4585 * <p>
4586 * This method returns a new array with the same elements of the input array
4587 * except the element on the specified position. The component type of the
4588 * returned array is always the same as that of the input array.
4589 * </p>
4590 * <p>
4591 * If the input array is <code>null</code>, an IndexOutOfBoundsException
4592 * will be thrown, because in that case no valid index can be specified.
4593 * </p>
4594 *
4595 * <pre>
4596 * ArrayUtils.remove(["a"], 0) = []
4597 * ArrayUtils.remove(["a", "b"], 0) = ["b"]
4598 * ArrayUtils.remove(["a", "b"], 1) = ["a"]
4599 * ArrayUtils.remove(["a", "b", "c"], 1) = ["a", "c"]
4600 * </pre>
4601 *
4602 * @param array
4603 * the array to remove the element from, may not be
4604 * <code>null</code>
4605 * @param index
4606 * the position of the element to be removed
4607 * @return A new array containing the existing elements except the element
4608 * at the specified position.
4609 * @throws IndexOutOfBoundsException
4610 * if the index is out of range (index < 0 || index >=
4611 * array.length), or if the array is <code>null</code>.
4612 * @since 2.1
4613 */
4614 public static Object[] remove( Object[] array, int index )
4615 {
4616 return ( Object[] ) remove( ( Object ) array, index );
4617 }
4618
4619
4620 /**
4621 * <p>
4622 * Removes the first occurrence of the specified element from the specified
4623 * array. All subsequent elements are shifted to the left (substracts one
4624 * from their indices). If the array doesn't contains such an element, no
4625 * elements are removed from the array.
4626 * </p>
4627 * <p>
4628 * This method returns a new array with the same elements of the input array
4629 * except the first occurrence of the specified element. The component type
4630 * of the returned array is always the same as that of the input array.
4631 * </p>
4632 *
4633 * <pre>
4634 * ArrayUtils.removeElement(null, "a") = null
4635 * ArrayUtils.removeElement([], "a") = []
4636 * ArrayUtils.removeElement(["a"], "b") = ["a"]
4637 * ArrayUtils.removeElement(["a", "b"], "a") = ["b"]
4638 * ArrayUtils.removeElement(["a", "b", "a"], "a") = ["b", "a"]
4639 * </pre>
4640 *
4641 * @param array
4642 * the array to remove the element from, may be <code>null</code>
4643 * @param element
4644 * the element to be removed
4645 * @return A new array containing the existing elements except the first
4646 * occurrence of the specified element.
4647 * @since 2.1
4648 */
4649 public static Object[] removeElement( Object[] array, Object element )
4650 {
4651 int index = indexOf( array, element );
4652 if ( index == -1 )
4653 {
4654 return clone( array );
4655 }
4656 return remove( array, index );
4657 }
4658
4659
4660 /**
4661 * <p>
4662 * Removes the element at the specified position from the specified array.
4663 * All subsequent elements are shifted to the left (substracts one from
4664 * their indices).
4665 * </p>
4666 * <p>
4667 * This method returns a new array with the same elements of the input array
4668 * except the element on the specified position. The component type of the
4669 * returned array is always the same as that of the input array.
4670 * </p>
4671 * <p>
4672 * If the input array is <code>null</code>, an IndexOutOfBoundsException
4673 * will be thrown, because in that case no valid index can be specified.
4674 * </p>
4675 *
4676 * <pre>
4677 * ArrayUtils.remove([true], 0) = []
4678 * ArrayUtils.remove([true, false], 0) = [false]
4679 * ArrayUtils.remove([true, false], 1) = [true]
4680 * ArrayUtils.remove([true, true, false], 1) = [true, false]
4681 * </pre>
4682 *
4683 * @param array
4684 * the array to remove the element from, may not be
4685 * <code>null</code>
4686 * @param index
4687 * the position of the element to be removed
4688 * @return A new array containing the existing elements except the element
4689 * at the specified position.
4690 * @throws IndexOutOfBoundsException
4691 * if the index is out of range (index < 0 || index >=
4692 * array.length), or if the array is <code>null</code>.
4693 * @since 2.1
4694 */
4695 public static boolean[] remove( boolean[] array, int index )
4696 {
4697 return ( boolean[] ) remove( ( Object ) array, index );
4698 }
4699
4700
4701 /**
4702 * <p>
4703 * Removes the first occurrence of the specified element from the specified
4704 * array. All subsequent elements are shifted to the left (substracts one
4705 * from their indices). If the array doesn't contains such an element, no
4706 * elements are removed from the array.
4707 * </p>
4708 * <p>
4709 * This method returns a new array with the same elements of the input array
4710 * except the first occurrence of the specified element. The component type
4711 * of the returned array is always the same as that of the input array.
4712 * </p>
4713 *
4714 * <pre>
4715 * ArrayUtils.removeElement(null, true) = null
4716 * ArrayUtils.removeElement([], true) = []
4717 * ArrayUtils.removeElement([true], false) = [true]
4718 * ArrayUtils.removeElement([true, false], false) = [true]
4719 * ArrayUtils.removeElement([true, false, true], true) = [false, true]
4720 * </pre>
4721 *
4722 * @param array
4723 * the array to remove the element from, may be <code>null</code>
4724 * @param element
4725 * the element to be removed
4726 * @return A new array containing the existing elements except the first
4727 * occurrence of the specified element.
4728 * @since 2.1
4729 */
4730 public static boolean[] removeElement( boolean[] array, boolean element )
4731 {
4732 int index = indexOf( array, element );
4733 if ( index == -1 )
4734 {
4735 return clone( array );
4736 }
4737 return remove( array, index );
4738 }
4739
4740
4741 /**
4742 * <p>
4743 * Removes the element at the specified position from the specified array.
4744 * All subsequent elements are shifted to the left (substracts one from
4745 * their indices).
4746 * </p>
4747 * <p>
4748 * This method returns a new array with the same elements of the input array
4749 * except the element on the specified position. The component type of the
4750 * returned array is always the same as that of the input array.
4751 * </p>
4752 * <p>
4753 * If the input array is <code>null</code>, an IndexOutOfBoundsException
4754 * will be thrown, because in that case no valid index can be specified.
4755 * </p>
4756 *
4757 * <pre>
4758 * ArrayUtils.remove([1], 0) = []
4759 * ArrayUtils.remove([1, 0], 0) = [0]
4760 * ArrayUtils.remove([1, 0], 1) = [1]
4761 * ArrayUtils.remove([1, 0, 1], 1) = [1, 1]
4762 * </pre>
4763 *
4764 * @param array
4765 * the array to remove the element from, may not be
4766 * <code>null</code>
4767 * @param index
4768 * the position of the element to be removed
4769 * @return A new array containing the existing elements except the element
4770 * at the specified position.
4771 * @throws IndexOutOfBoundsException
4772 * if the index is out of range (index < 0 || index >=
4773 * array.length), or if the array is <code>null</code>.
4774 * @since 2.1
4775 */
4776 public static byte[] remove( byte[] array, int index )
4777 {
4778 return ( byte[] ) remove( ( Object ) array, index );
4779 }
4780
4781
4782 /**
4783 * <p>
4784 * Removes the first occurrence of the specified element from the specified
4785 * array. All subsequent elements are shifted to the left (substracts one
4786 * from their indices). If the array doesn't contains such an element, no
4787 * elements are removed from the array.
4788 * </p>
4789 * <p>
4790 * This method returns a new array with the same elements of the input array
4791 * except the first occurrence of the specified element. The component type
4792 * of the returned array is always the same as that of the input array.
4793 * </p>
4794 *
4795 * <pre>
4796 * ArrayUtils.removeElement(null, 1) = null
4797 * ArrayUtils.removeElement([], 1) = []
4798 * ArrayUtils.removeElement([1], 0) = [1]
4799 * ArrayUtils.removeElement([1, 0], 0) = [1]
4800 * ArrayUtils.removeElement([1, 0, 1], 1) = [0, 1]
4801 * </pre>
4802 *
4803 * @param array
4804 * the array to remove the element from, may be <code>null</code>
4805 * @param element
4806 * the element to be removed
4807 * @return A new array containing the existing elements except the first
4808 * occurrence of the specified element.
4809 * @since 2.1
4810 */
4811 public static byte[] removeElement( byte[] array, byte element )
4812 {
4813 int index = indexOf( array, element );
4814 if ( index == -1 )
4815 {
4816 return clone( array );
4817 }
4818 return remove( array, index );
4819 }
4820
4821
4822 /**
4823 * <p>
4824 * Removes the element at the specified position from the specified array.
4825 * All subsequent elements are shifted to the left (substracts one from
4826 * their indices).
4827 * </p>
4828 * <p>
4829 * This method returns a new array with the same elements of the input array
4830 * except the element on the specified position. The component type of the
4831 * returned array is always the same as that of the input array.
4832 * </p>
4833 * <p>
4834 * If the input array is <code>null</code>, an IndexOutOfBoundsException
4835 * will be thrown, because in that case no valid index can be specified.
4836 * </p>
4837 *
4838 * <pre>
4839 * ArrayUtils.remove(['a'], 0) = []
4840 * ArrayUtils.remove(['a', 'b'], 0) = ['b']
4841 * ArrayUtils.remove(['a', 'b'], 1) = ['a']
4842 * ArrayUtils.remove(['a', 'b', 'c'], 1) = ['a', 'c']
4843 * </pre>
4844 *
4845 * @param array
4846 * the array to remove the element from, may not be
4847 * <code>null</code>
4848 * @param index
4849 * the position of the element to be removed
4850 * @return A new array containing the existing elements except the element
4851 * at the specified position.
4852 * @throws IndexOutOfBoundsException
4853 * if the index is out of range (index < 0 || index >=
4854 * array.length), or if the array is <code>null</code>.
4855 * @since 2.1
4856 */
4857 public static char[] remove( char[] array, int index )
4858 {
4859 return ( char[] ) remove( ( Object ) array, index );
4860 }
4861
4862
4863 /**
4864 * <p>
4865 * Removes the first occurrence of the specified element from the specified
4866 * array. All subsequent elements are shifted to the left (substracts one
4867 * from their indices). If the array doesn't contains such an element, no
4868 * elements are removed from the array.
4869 * </p>
4870 * <p>
4871 * This method returns a new array with the same elements of the input array
4872 * except the first occurrence of the specified element. The component type
4873 * of the returned array is always the same as that of the input array.
4874 * </p>
4875 *
4876 * <pre>
4877 * ArrayUtils.removeElement(null, 'a') = null
4878 * ArrayUtils.removeElement([], 'a') = []
4879 * ArrayUtils.removeElement(['a'], 'b') = ['a']
4880 * ArrayUtils.removeElement(['a', 'b'], 'a') = ['b']
4881 * ArrayUtils.removeElement(['a', 'b', 'a'], 'a') = ['b', 'a']
4882 * </pre>
4883 *
4884 * @param array
4885 * the array to remove the element from, may be <code>null</code>
4886 * @param element
4887 * the element to be removed
4888 * @return A new array containing the existing elements except the first
4889 * occurrence of the specified element.
4890 * @since 2.1
4891 */
4892 public static char[] removeElement( char[] array, char element )
4893 {
4894 int index = indexOf( array, element );
4895 if ( index == -1 )
4896 {
4897 return clone( array );
4898 }
4899 return remove( array, index );
4900 }
4901
4902
4903 /**
4904 * <p>
4905 * Removes the element at the specified position from the specified array.
4906 * All subsequent elements are shifted to the left (substracts one from
4907 * their indices).
4908 * </p>
4909 * <p>
4910 * This method returns a new array with the same elements of the input array
4911 * except the element on the specified position. The component type of the
4912 * returned array is always the same as that of the input array.
4913 * </p>
4914 * <p>
4915 * If the input array is <code>null</code>, an IndexOutOfBoundsException
4916 * will be thrown, because in that case no valid index can be specified.
4917 * </p>
4918 *
4919 * <pre>
4920 * ArrayUtils.remove([1.1], 0) = []
4921 * ArrayUtils.remove([2.5, 6.0], 0) = [6.0]
4922 * ArrayUtils.remove([2.5, 6.0], 1) = [2.5]
4923 * ArrayUtils.remove([2.5, 6.0, 3.8], 1) = [2.5, 3.8]
4924 * </pre>
4925 *
4926 * @param array
4927 * the array to remove the element from, may not be
4928 * <code>null</code>
4929 * @param index
4930 * the position of the element to be removed
4931 * @return A new array containing the existing elements except the element
4932 * at the specified position.
4933 * @throws IndexOutOfBoundsException
4934 * if the index is out of range (index < 0 || index >=
4935 * array.length), or if the array is <code>null</code>.
4936 * @since 2.1
4937 */
4938 public static double[] remove( double[] array, int index )
4939 {
4940 return ( double[] ) remove( ( Object ) array, index );
4941 }
4942
4943
4944 /**
4945 * <p>
4946 * Removes the first occurrence of the specified element from the specified
4947 * array. All subsequent elements are shifted to the left (substracts one
4948 * from their indices). If the array doesn't contains such an element, no
4949 * elements are removed from the array.
4950 * </p>
4951 * <p>
4952 * This method returns a new array with the same elements of the input array
4953 * except the first occurrence of the specified element. The component type
4954 * of the returned array is always the same as that of the input array.
4955 * </p>
4956 *
4957 * <pre>
4958 * ArrayUtils.removeElement(null, 1.1) = null
4959 * ArrayUtils.removeElement([], 1.1) = []
4960 * ArrayUtils.removeElement([1.1], 1.2) = [1.1]
4961 * ArrayUtils.removeElement([1.1, 2.3], 1.1) = [2.3]
4962 * ArrayUtils.removeElement([1.1, 2.3, 1.1], 1.1) = [2.3, 1.1]
4963 * </pre>
4964 *
4965 * @param array
4966 * the array to remove the element from, may be <code>null</code>
4967 * @param element
4968 * the element to be removed
4969 * @return A new array containing the existing elements except the first
4970 * occurrence of the specified element.
4971 * @since 2.1
4972 */
4973 public static double[] removeElement( double[] array, double element )
4974 {
4975 int index = indexOf( array, element );
4976 if ( index == -1 )
4977 {
4978 return clone( array );
4979 }
4980 return remove( array, index );
4981 }
4982
4983
4984 /**
4985 * <p>
4986 * Removes the element at the specified position from the specified array.
4987 * All subsequent elements are shifted to the left (substracts one from
4988 * their indices).
4989 * </p>
4990 * <p>
4991 * This method returns a new array with the same elements of the input array
4992 * except the element on the specified position. The component type of the
4993 * returned array is always the same as that of the input array.
4994 * </p>
4995 * <p>
4996 * If the input array is <code>null</code>, an IndexOutOfBoundsException
4997 * will be thrown, because in that case no valid index can be specified.
4998 * </p>
4999 *
5000 * <pre>
5001 * ArrayUtils.remove([1.1], 0) = []
5002 * ArrayUtils.remove([2.5, 6.0], 0) = [6.0]
5003 * ArrayUtils.remove([2.5, 6.0], 1) = [2.5]
5004 * ArrayUtils.remove([2.5, 6.0, 3.8], 1) = [2.5, 3.8]
5005 * </pre>
5006 *
5007 * @param array
5008 * the array to remove the element from, may not be
5009 * <code>null</code>
5010 * @param index
5011 * the position of the element to be removed
5012 * @return A new array containing the existing elements except the element
5013 * at the specified position.
5014 * @throws IndexOutOfBoundsException
5015 * if the index is out of range (index < 0 || index >=
5016 * array.length), or if the array is <code>null</code>.
5017 * @since 2.1
5018 */
5019 public static float[] remove( float[] array, int index )
5020 {
5021 return ( float[] ) remove( ( Object ) array, index );
5022 }
5023
5024
5025 /**
5026 * <p>
5027 * Removes the first occurrence of the specified element from the specified
5028 * array. All subsequent elements are shifted to the left (substracts one
5029 * from their indices). If the array doesn't contains such an element, no
5030 * elements are removed from the array.
5031 * </p>
5032 * <p>
5033 * This method returns a new array with the same elements of the input array
5034 * except the first occurrence of the specified element. The component type
5035 * of the returned array is always the same as that of the input array.
5036 * </p>
5037 *
5038 * <pre>
5039 * ArrayUtils.removeElement(null, 1.1) = null
5040 * ArrayUtils.removeElement([], 1.1) = []
5041 * ArrayUtils.removeElement([1.1], 1.2) = [1.1]
5042 * ArrayUtils.removeElement([1.1, 2.3], 1.1) = [2.3]
5043 * ArrayUtils.removeElement([1.1, 2.3, 1.1], 1.1) = [2.3, 1.1]
5044 * </pre>
5045 *
5046 * @param array
5047 * the array to remove the element from, may be <code>null</code>
5048 * @param element
5049 * the element to be removed
5050 * @return A new array containing the existing elements except the first
5051 * occurrence of the specified element.
5052 * @since 2.1
5053 */
5054 public static float[] removeElement( float[] array, float element )
5055 {
5056 int index = indexOf( array, element );
5057 if ( index == -1 )
5058 {
5059 return clone( array );
5060 }
5061 return remove( array, index );
5062 }
5063
5064
5065 /**
5066 * <p>
5067 * Removes the element at the specified position from the specified array.
5068 * All subsequent elements are shifted to the left (substracts one from
5069 * their indices).
5070 * </p>
5071 * <p>
5072 * This method returns a new array with the same elements of the input array
5073 * except the element on the specified position. The component type of the
5074 * returned array is always the same as that of the input array.
5075 * </p>
5076 * <p>
5077 * If the input array is <code>null</code>, an IndexOutOfBoundsException
5078 * will be thrown, because in that case no valid index can be specified.
5079 * </p>
5080 *
5081 * <pre>
5082 * ArrayUtils.remove([1], 0) = []
5083 * ArrayUtils.remove([2, 6], 0) = [6]
5084 * ArrayUtils.remove([2, 6], 1) = [2]
5085 * ArrayUtils.remove([2, 6, 3], 1) = [2, 3]
5086 * </pre>
5087 *
5088 * @param array
5089 * the array to remove the element from, may not be
5090 * <code>null</code>
5091 * @param index
5092 * the position of the element to be removed
5093 * @return A new array containing the existing elements except the element
5094 * at the specified position.
5095 * @throws IndexOutOfBoundsException
5096 * if the index is out of range (index < 0 || index >=
5097 * array.length), or if the array is <code>null</code>.
5098 * @since 2.1
5099 */
5100 public static int[] remove( int[] array, int index )
5101 {
5102 return ( int[] ) remove( ( Object ) array, index );
5103 }
5104
5105
5106 /**
5107 * <p>
5108 * Removes the first occurrence of the specified element from the specified
5109 * array. All subsequent elements are shifted to the left (substracts one
5110 * from their indices). If the array doesn't contains such an element, no
5111 * elements are removed from the array.
5112 * </p>
5113 * <p>
5114 * This method returns a new array with the same elements of the input array
5115 * except the first occurrence of the specified element. The component type
5116 * of the returned array is always the same as that of the input array.
5117 * </p>
5118 *
5119 * <pre>
5120 * ArrayUtils.removeElement(null, 1) = null
5121 * ArrayUtils.removeElement([], 1) = []
5122 * ArrayUtils.removeElement([1], 2) = [1]
5123 * ArrayUtils.removeElement([1, 3], 1) = [3]
5124 * ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
5125 * </pre>
5126 *
5127 * @param array
5128 * the array to remove the element from, may be <code>null</code>
5129 * @param element
5130 * the element to be removed
5131 * @return A new array containing the existing elements except the first
5132 * occurrence of the specified element.
5133 * @since 2.1
5134 */
5135 public static int[] removeElement( int[] array, int element )
5136 {
5137 int index = indexOf( array, element );
5138 if ( index == -1 )
5139 {
5140 return clone( array );
5141 }
5142 return remove( array, index );
5143 }
5144
5145
5146 /**
5147 * <p>
5148 * Removes the element at the specified position from the specified array.
5149 * All subsequent elements are shifted to the left (substracts one from
5150 * their indices).
5151 * </p>
5152 * <p>
5153 * This method returns a new array with the same elements of the input array
5154 * except the element on the specified position. The component type of the
5155 * returned array is always the same as that of the input array.
5156 * </p>
5157 * <p>
5158 * If the input array is <code>null</code>, an IndexOutOfBoundsException
5159 * will be thrown, because in that case no valid index can be specified.
5160 * </p>
5161 *
5162 * <pre>
5163 * ArrayUtils.remove([1], 0) = []
5164 * ArrayUtils.remove([2, 6], 0) = [6]
5165 * ArrayUtils.remove([2, 6], 1) = [2]
5166 * ArrayUtils.remove([2, 6, 3], 1) = [2, 3]
5167 * </pre>
5168 *
5169 * @param array
5170 * the array to remove the element from, may not be
5171 * <code>null</code>
5172 * @param index
5173 * the position of the element to be removed
5174 * @return A new array containing the existing elements except the element
5175 * at the specified position.
5176 * @throws IndexOutOfBoundsException
5177 * if the index is out of range (index < 0 || index >=
5178 * array.length), or if the array is <code>null</code>.
5179 * @since 2.1
5180 */
5181 public static long[] remove( long[] array, int index )
5182 {
5183 return ( long[] ) remove( ( Object ) array, index );
5184 }
5185
5186
5187 /**
5188 * <p>
5189 * Removes the first occurrence of the specified element from the specified
5190 * array. All subsequent elements are shifted to the left (substracts one
5191 * from their indices). If the array doesn't contains such an element, no
5192 * elements are removed from the array.
5193 * </p>
5194 * <p>
5195 * This method returns a new array with the same elements of the input array
5196 * except the first occurrence of the specified element. The component type
5197 * of the returned array is always the same as that of the input array.
5198 * </p>
5199 *
5200 * <pre>
5201 * ArrayUtils.removeElement(null, 1) = null
5202 * ArrayUtils.removeElement([], 1) = []
5203 * ArrayUtils.removeElement([1], 2) = [1]
5204 * ArrayUtils.removeElement([1, 3], 1) = [3]
5205 * ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
5206 * </pre>
5207 *
5208 * @param array
5209 * the array to remove the element from, may be <code>null</code>
5210 * @param element
5211 * the element to be removed
5212 * @return A new array containing the existing elements except the first
5213 * occurrence of the specified element.
5214 * @since 2.1
5215 */
5216 public static long[] removeElement( long[] array, long element )
5217 {
5218 int index = indexOf( array, element );
5219 if ( index == -1 )
5220 {
5221 return clone( array );
5222 }
5223 return remove( array, index );
5224 }
5225
5226
5227 /**
5228 * <p>
5229 * Removes the element at the specified position from the specified array.
5230 * All subsequent elements are shifted to the left (substracts one from
5231 * their indices).
5232 * </p>
5233 * <p>
5234 * This method returns a new array with the same elements of the input array
5235 * except the element on the specified position. The component type of the
5236 * returned array is always the same as that of the input array.
5237 * </p>
5238 * <p>
5239 * If the input array is <code>null</code>, an IndexOutOfBoundsException
5240 * will be thrown, because in that case no valid index can be specified.
5241 * </p>
5242 *
5243 * <pre>
5244 * ArrayUtils.remove([1], 0) = []
5245 * ArrayUtils.remove([2, 6], 0) = [6]
5246 * ArrayUtils.remove([2, 6], 1) = [2]
5247 * ArrayUtils.remove([2, 6, 3], 1) = [2, 3]
5248 * </pre>
5249 *
5250 * @param array
5251 * the array to remove the element from, may not be
5252 * <code>null</code>
5253 * @param index
5254 * the position of the element to be removed
5255 * @return A new array containing the existing elements except the element
5256 * at the specified position.
5257 * @throws IndexOutOfBoundsException
5258 * if the index is out of range (index < 0 || index >=
5259 * array.length), or if the array is <code>null</code>.
5260 * @since 2.1
5261 */
5262 public static short[] remove( short[] array, int index )
5263 {
5264 return ( short[] ) remove( ( Object ) array, index );
5265 }
5266
5267
5268 /**
5269 * <p>
5270 * Removes the first occurrence of the specified element from the specified
5271 * array. All subsequent elements are shifted to the left (substracts one
5272 * from their indices). If the array doesn't contains such an element, no
5273 * elements are removed from the array.
5274 * </p>
5275 * <p>
5276 * This method returns a new array with the same elements of the input array
5277 * except the first occurrence of the specified element. The component type
5278 * of the returned array is always the same as that of the input array.
5279 * </p>
5280 *
5281 * <pre>
5282 * ArrayUtils.removeElement(null, 1) = null
5283 * ArrayUtils.removeElement([], 1) = []
5284 * ArrayUtils.removeElement([1], 2) = [1]
5285 * ArrayUtils.removeElement([1, 3], 1) = [3]
5286 * ArrayUtils.removeElement([1, 3, 1], 1) = [3, 1]
5287 * </pre>
5288 *
5289 * @param array
5290 * the array to remove the element from, may be <code>null</code>
5291 * @param element
5292 * the element to be removed
5293 * @return A new array containing the existing elements except the first
5294 * occurrence of the specified element.
5295 * @since 2.1
5296 */
5297 public static short[] removeElement( short[] array, short element )
5298 {
5299 int index = indexOf( array, element );
5300 if ( index == -1 )
5301 {
5302 return clone( array );
5303 }
5304 return remove( array, index );
5305 }
5306
5307
5308 /**
5309 * <p>
5310 * Removes the element at the specified position from the specified array.
5311 * All subsequent elements are shifted to the left (substracts one from
5312 * their indices).
5313 * </p>
5314 * <p>
5315 * This method returns a new array with the same elements of the input array
5316 * except the element on the specified position. The component type of the
5317 * returned array is always the same as that of the input array.
5318 * </p>
5319 * <p>
5320 * If the input array is <code>null</code>, an IndexOutOfBoundsException
5321 * will be thrown, because in that case no valid index can be specified.
5322 * </p>
5323 *
5324 * @param array
5325 * the array to remove the element from, may not be
5326 * <code>null</code>
5327 * @param index
5328 * the position of the element to be removed
5329 * @return A new array containing the existing elements except the element
5330 * at the specified position.
5331 * @throws IndexOutOfBoundsException
5332 * if the index is out of range (index < 0 || index >=
5333 * array.length), or if the array is <code>null</code>.
5334 * @since 2.1
5335 */
5336 private static Object remove( Object array, int index )
5337 {
5338 int length = getLength( array );
5339 if ( index < 0 || index >= length )
5340 {
5341 throw new IndexOutOfBoundsException( I18n.err( I18n.ERR_04338, index, length ) );
5342 }
5343
5344 Object result = Array.newInstance( array.getClass().getComponentType(), length - 1 );
5345 System.arraycopy( array, 0, result, 0, index );
5346 if ( index < length - 1 )
5347 {
5348 System.arraycopy( array, index + 1, result, index, length - index - 1 );
5349 }
5350
5351 return result;
5352 }
5353
5354 }