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 (&lt;0) is promoted to 0,
508         *            overvalue (&gt;array.length) results in an empty array.
509         * @param endIndexExclusive
510         *            elements up to endIndex-1 are present in the returned
511         *            subarray. Undervalue (&lt; startIndex) produces empty array,
512         *            overvalue (&gt;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 (&lt;0) is promoted to 0,
556         *            overvalue (&gt;array.length) results in an empty array.
557         * @param endIndexExclusive
558         *            elements up to endIndex-1 are present in the returned
559         *            subarray. Undervalue (&lt; startIndex) produces empty array,
560         *            overvalue (&gt;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 (&lt;0) is promoted to 0,
604         *            overvalue (&gt;array.length) results in an empty array.
605         * @param endIndexExclusive
606         *            elements up to endIndex-1 are present in the returned
607         *            subarray. Undervalue (&lt; startIndex) produces empty array,
608         *            overvalue (&gt;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 (&lt;0) is promoted to 0,
652         *            overvalue (&gt;array.length) results in an empty array.
653         * @param endIndexExclusive
654         *            elements up to endIndex-1 are present in the returned
655         *            subarray. Undervalue (&lt; startIndex) produces empty array,
656         *            overvalue (&gt;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 (&lt;0) is promoted to 0,
700         *            overvalue (&gt;array.length) results in an empty array.
701         * @param endIndexExclusive
702         *            elements up to endIndex-1 are present in the returned
703         *            subarray. Undervalue (&lt; startIndex) produces empty array,
704         *            overvalue (&gt;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 (&lt;0) is promoted to 0,
748         *            overvalue (&gt;array.length) results in an empty array.
749         * @param endIndexExclusive
750         *            elements up to endIndex-1 are present in the returned
751         *            subarray. Undervalue (&lt; startIndex) produces empty array,
752         *            overvalue (&gt;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 (&lt;0) is promoted to 0,
796         *            overvalue (&gt;array.length) results in an empty array.
797         * @param endIndexExclusive
798         *            elements up to endIndex-1 are present in the returned
799         *            subarray. Undervalue (&lt; startIndex) produces empty array,
800         *            overvalue (&gt;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 (&lt;0) is promoted to 0,
844         *            overvalue (&gt;array.length) results in an empty array.
845         * @param endIndexExclusive
846         *            elements up to endIndex-1 are present in the returned
847         *            subarray. Undervalue (&lt; startIndex) produces empty array,
848         *            overvalue (&gt;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 (&lt;0) is promoted to 0,
892         *            overvalue (&gt;array.length) results in an empty array.
893         * @param endIndexExclusive
894         *            elements up to endIndex-1 are present in the returned
895         *            subarray. Undervalue (&lt; startIndex) produces empty array,
896         *            overvalue (&gt;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([&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]) = 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([&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]) = 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([&quot;a&quot;, &quot;b&quot;, &quot;c&quot;], [&quot;1&quot;, &quot;2&quot;, &quot;3&quot;]) = [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;, &quot;1&quot;, &quot;2&quot;, &quot;3&quot;]
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, &quot;a&quot;)       = [&quot;a&quot;]
4173         *  ArrayUtils.add([&quot;a&quot;], null)     = [&quot;a&quot;, null]
4174         *  ArrayUtils.add([&quot;a&quot;], &quot;b&quot;)      = [&quot;a&quot;, &quot;b&quot;]
4175         *  ArrayUtils.add([&quot;a&quot;, &quot;b&quot;], &quot;c&quot;) = [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]
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, &quot;a&quot;)       = [&quot;a&quot;]
4535         *  ArrayUtils.add([&quot;a&quot;], 1, null)     = [&quot;a&quot;, null]
4536         *  ArrayUtils.add([&quot;a&quot;], 1, &quot;b&quot;)      = [&quot;a&quot;, &quot;b&quot;]
4537         *  ArrayUtils.add([&quot;a&quot;, &quot;b&quot;], 3, &quot;c&quot;) = [&quot;a&quot;, &quot;b&quot;, &quot;c&quot;]
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([&quot;a&quot;], 0)           = []
4597         *  ArrayUtils.remove([&quot;a&quot;, &quot;b&quot;], 0)      = [&quot;b&quot;]
4598         *  ArrayUtils.remove([&quot;a&quot;, &quot;b&quot;], 1)      = [&quot;a&quot;]
4599         *  ArrayUtils.remove([&quot;a&quot;, &quot;b&quot;, &quot;c&quot;], 1) = [&quot;a&quot;, &quot;c&quot;]
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, &quot;a&quot;)            = null
4635         *  ArrayUtils.removeElement([], &quot;a&quot;)              = []
4636         *  ArrayUtils.removeElement([&quot;a&quot;], &quot;b&quot;)           = [&quot;a&quot;]
4637         *  ArrayUtils.removeElement([&quot;a&quot;, &quot;b&quot;], &quot;a&quot;)      = [&quot;b&quot;]
4638         *  ArrayUtils.removeElement([&quot;a&quot;, &quot;b&quot;, &quot;a&quot;], &quot;a&quot;) = [&quot;b&quot;, &quot;a&quot;]
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    }