View Javadoc

1   /*
2    * Copyright (C) 2004 Christian Siefkes <christian@siefkes.net>.
3    * Development of this software is supported by the German Research Society,
4    * Berlin-Brandenburg Graduate School in Distributed Information Systems
5    * (DFG grant no. GRK 316).
6    *
7    * This library is free software; you can redistribute it and/or
8    * modify it under the terms of the GNU Lesser General Public
9    * License as published by the Free Software Foundation; either
10   * version 2.1 of the License, or (at your option) any later version.
11   *
12   * This library is distributed in the hope that it will be useful,
13   * but WITHOUT ANY WARRANTY; without even the implied warranty of
14   * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
15   * Lesser General Public License for more details.
16   *
17   * You should have received a copy of the GNU Lesser General Public
18   * License along with this library; if not, visit
19   * http://www.gnu.org/licenses/lgpl.html or write to the Free Software
20   * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307, USA.
21   */
22  package de.fu_berlin.ties.util;
23  
24  import java.util.ArrayList;
25  import java.util.Arrays;
26  import java.util.HashSet;
27  import java.util.List;
28  import java.util.Set;
29  
30  /***
31   * A static class that provides utility methods for working with
32   * {@link java.util.Collection}s and arrays. No instances of this class can be
33   * created, only the static members should be used.
34   *
35   * @author Christian Siefkes
36   * @version $Revision: 1.1 $, $Date: 2004/12/06 17:59:41 $, $Author: siefkes $
37   */
38  public final class CollectionUtils {
39  
40      /***
41       * Default separator used to {@linkplain #flatten(Object[]) flatten} array
42       * if no other separator is specified: {@value} (a single space).
43       */
44      public static final String SEPARATOR = " ";
45  
46      /***
47       * Wraps an array into a set. Duplicates will be ignored.
48       *
49       * @param array the array to wrap
50       * @return a set containing the contents of the set (in random order,
51       * without duplicates)
52       */
53      public static <T> Set<T> arrayAsSet(final T[] array) {
54          return new HashSet<T>(Arrays.asList(array));
55      }
56  
57      /***
58       * Converts an object array into a boolean array, calling
59       * {@link Util#asBoolean(Object)} on each element.
60       *
61       * @param objArray the array of objects to convert
62       * @return the converted boolean array
63       * @throws IllegalArgumentException if an object's <code>toString()</code>
64       * output cannot be parsed as a boolean
65       */
66      public static boolean[] asBooleanArray(final Object[] objArray)
67      throws IllegalArgumentException {
68          final boolean[] result = new boolean[objArray.length];
69          for (int i = 0; i < objArray.length; i++) {
70              result[i] = Util.asBoolean(objArray[i]);
71          }
72          return result;
73      }
74  
75      /***
76       * Converts an object array into a byte array, calling
77       * {@link Util#asByte(Object)} on each element.
78       *
79       * @param objArray the array of objects to convert
80       * @return the converted byte array
81       * @throws NumberFormatException if an object's <code>toString()</code>
82       * output does not contain a parsable byte
83       */
84      public static byte[] asByteArray(final Object[] objArray)
85      throws NumberFormatException {
86          final byte[] result = new byte[objArray.length];
87          for (int i = 0; i < objArray.length; i++) {
88              result[i] = Util.asByte(objArray[i]);
89          }
90          return result;
91      }
92  
93      /***
94       * Converts an object array into a char array, calling
95       * {@link Util#asChar(Object)} on each element.
96       *
97       * @param objArray the array of objects to convert
98       * @return the converted char array
99       * @throws IndexOutOfBoundsException if the object's <code>toString()</code>
100      * output is the empty string (after trimming outer whitespace)
101      */
102     public static char[] asCharArray(final Object[] objArray)
103     throws IndexOutOfBoundsException {
104         final char[] result = new char[objArray.length];
105         for (int i = 0; i < objArray.length; i++) {
106             result[i] = Util.asChar(objArray[i]);
107         }
108         return result;
109     }
110 
111     /***
112      * Converts an object array into a double array, calling
113      * {@link Util#asDouble(Object)} on each element.
114      *
115      * @param objArray the array of objects to convert
116      * @return the converted double array
117      * @throws NumberFormatException if an object's <code>toString()</code>
118      * output does not contain a parsable double
119      */
120     public static double[] asDoubleArray(final Object[] objArray)
121     throws NumberFormatException {
122         final double[] result = new double[objArray.length];
123         for (int i = 0; i < objArray.length; i++) {
124             result[i] = Util.asDouble(objArray[i]);
125         }
126         return result;
127     }
128 
129     /***
130      * Converts an object array into a float array, calling
131      * {@link Util#asFloat(Object)} on each element.
132      *
133      * @param objArray the array of objects to convert
134      * @return the converted float array
135      * @throws NumberFormatException if an object's <code>toString()</code>
136      * output does not contain a parsable float
137      */
138     public static float[] asFloatArray(final Object[] objArray)
139     throws NumberFormatException {
140         final float[] result = new float[objArray.length];
141         for (int i = 0; i < objArray.length; i++) {
142             result[i] = Util.asFloat(objArray[i]);
143         }
144         return result;
145     }
146 
147     /***
148      * Converts an object array into an integer array, calling
149      * {@link Util#asInt(Object)} on each element.
150      *
151      * @param objArray the array of objects to convert
152      * @return the converted int array
153      * @throws NumberFormatException if an object's <code>toString()</code>
154      * output does not contain a parsable int
155      */
156     public static int[] asIntArray(final Object[] objArray)
157     throws NumberFormatException {
158         final int[] result = new int[objArray.length];
159         for (int i = 0; i < objArray.length; i++) {
160             result[i] = Util.asInt(objArray[i]);
161         }
162         return result;
163     }
164 
165     /***
166      * Converts an object array into a long array, calling
167      * {@link Util#asLong(Object)} on each element.
168      *
169      * @param objArray the array of objects to convert
170      * @return the converted long array
171      * @throws NumberFormatException if an object's <code>toString()</code>
172      * output does not contain a parsable long
173      */
174     public static long[] asLongArray(final Object[] objArray)
175     throws NumberFormatException {
176         final long[] result = new long[objArray.length];
177         for (int i = 0; i < objArray.length; i++) {
178             result[i] = Util.asLong(objArray[i]);
179         }
180         return result;
181     }
182 
183     /***
184      * Converts an object array into a short array, calling
185      * {@link Util#asShort(Object)} on each element.
186      *
187      * @param objArray the array of objects to convert
188      * @return the converted short array
189      * @throws NumberFormatException if an object's <code>toString()</code>
190      * output does not contain a parsable short
191      */
192     public static short[] asShortArray(final Object[] objArray)
193     throws NumberFormatException {
194         final short[] result = new short[objArray.length];
195         for (int i = 0; i < objArray.length; i++) {
196             result[i] = Util.asShort(objArray[i]);
197         }
198         return result;
199     }
200 
201     /***
202      * Converts an object array into a String array, calling
203      * {@link Util#asString(Object)} on each element.
204      *
205      * @param objArray the array of objects to convert
206      * @return the converted String array
207      */
208     public static String[] asStringArray(final Object[] objArray) {
209         final String[] result = new String[objArray.length];
210         for (int i = 0; i < objArray.length; i++) {
211             result[i] = Util.asString(objArray[i]);
212         }
213         return result;
214     }
215 
216     /***
217      * Combines two array into a target array, inserting all elements of the
218      * first array and then all elements of the second array in the target
219      * array.
220      *
221      * @param array1 the first array to copy
222      * @param array2 the second array to copy
223      * @param targetArray the array to copy the two other array into; the
224      * type of this array must be suitable to accept elements from both array;
225      * the length of this array must be equal or greater than
226      * <code>array1.length + array2.length</code>
227      */
228     public static void combineArrays(final Object[] array1,
229                                     final Object[] array2,
230                                     final Object[] targetArray) {
231         final int lengthOfFirst = array1.length;
232         int i;
233         // copy first array into target array
234         for (i = 0; i < lengthOfFirst; i++) {
235             targetArray[i] = array1[i];
236         }
237     
238         // copy second array into target array
239         for (i = 0; i < array2.length; i++) {
240             targetArray[i + lengthOfFirst] = array2[i];
241         }
242     }
243 
244     /***
245      * Flattens the elements of the provided array into a single string,
246      * separating elements by a space character.
247      *
248      * @param array the array of values to join
249      * @return the flattened string
250      */
251     public static String flatten(final boolean[] array) {
252         final StringBuilder result = new StringBuilder();
253 
254         for (int i = 0; i < array.length; i++) {
255             if (i > 0) {
256                 result.append(SEPARATOR);
257             }
258             result.append(array[i]);
259         }
260 
261         return result.toString();
262     }
263 
264     /***
265      * Flattens the elements of the provided array into a single string,
266      * separating elements by a space character.
267      *
268      * @param array the array of values to join
269      * @return the flattened string
270      */
271     public static String flatten(final byte[] array) {
272         final StringBuilder result = new StringBuilder();
273 
274         for (int i = 0; i < array.length; i++) {
275             if (i > 0) {
276                 result.append(SEPARATOR);
277             }
278             result.append(array[i]);
279         }
280 
281         return result.toString();
282     }
283 
284     /***
285      * Flattens the elements of the provided array into a single string,
286      * separating elements by a space character.
287      *
288      * @param array the array of values to join
289      * @return the flattened string
290      */
291     public static String flatten(final char[] array) {
292         final StringBuilder result = new StringBuilder();
293 
294         for (int i = 0; i < array.length; i++) {
295             if (i > 0) {
296                 result.append(SEPARATOR);
297             }
298             result.append(array[i]);
299         }
300 
301         return result.toString();
302     }
303 
304     /***
305      * Flattens the elements of the provided array into a single string,
306      * separating elements by a space character.
307      *
308      * @param array the array of values to join
309      * @return the flattened string
310      */
311     public static String flatten(final double[] array) {
312         final StringBuilder result = new StringBuilder();
313 
314         for (int i = 0; i < array.length; i++) {
315             if (i > 0) {
316                 result.append(SEPARATOR);
317             }
318             result.append(array[i]);
319         }
320 
321         return result.toString();
322     }
323 
324     /***
325      * Flattens the elements of the provided array into a single string,
326      * separating elements by a space character.
327      *
328      * @param array the array of values to join
329      * @return the flattened string
330      */
331     public static String flatten(final float[] array) {
332         final StringBuilder result = new StringBuilder();
333 
334         for (int i = 0; i < array.length; i++) {
335             if (i > 0) {
336                 result.append(SEPARATOR);
337             }
338             result.append(array[i]);
339         }
340 
341         return result.toString();
342     }
343 
344     /***
345      * Flattens the elements of the provided array into a single string,
346      * separating elements by a space character.
347      *
348      * @param array the array of values to join
349      * @return the flattened string
350      */
351     public static String flatten(final int[] array) {
352         final StringBuilder result = new StringBuilder();
353 
354         for (int i = 0; i < array.length; i++) {
355             if (i > 0) {
356                 result.append(SEPARATOR);
357             }
358             result.append(array[i]);
359         }
360 
361         return result.toString();
362     }
363 
364     /***
365      * Flattens the elements of the provided array into a single string,
366      * separating elements by a space character.
367      *
368      * @param array the array of values to join
369      * @return the flattened string
370      */
371     public static String flatten(final long[] array) {
372         final StringBuilder result = new StringBuilder();
373 
374         for (int i = 0; i < array.length; i++) {
375             if (i > 0) {
376                 result.append(SEPARATOR);
377             }
378             result.append(array[i]);
379         }
380 
381         return result.toString();
382     }
383 
384     /***
385      * Flattens the elements of the provided array into a single string,
386      * separating elements by a space character.
387      *
388      * @param array the array of values to join
389      * @return the flattened string
390      */
391     public static String flatten(final Object[] array) {
392         return flatten(array, SEPARATOR);
393     }
394 
395     /***
396      * Flattens the elements of the provided array into a single string,
397      * separating elements by the provided separator.
398      *
399      * @param array the array of values to join
400      * @param separator the separator string to use
401      * @return the flattened string
402      */
403     public static String flatten(final Object[] array, final String separator) {
404         final StringBuilder result = new StringBuilder();
405 
406         for (int i = 0; i < array.length; i++) {
407             if (i > 0) {
408                 result.append(separator);
409             }
410             result.append(array[i]);
411         }
412 
413         return result.toString();
414     }
415 
416     /***
417      * Flattens the elements of the provided array into a single string,
418      * separating elements by a space character.
419      *
420      * @param array the array of values to join
421      * @return the flattened string
422      */
423     public static String flatten(final short[] array) {
424         final StringBuilder result = new StringBuilder();
425 
426         for (int i = 0; i < array.length; i++) {
427             if (i > 0) {
428                 result.append(SEPARATOR);
429             }
430             result.append(array[i]);
431         }
432 
433         return result.toString();
434     }
435 
436     /***
437      * Copied the last <em>n</em> elements from a list into a new list (or all
438      * elements, if the size of the input list is smaller or equal to
439      * <em>n</em>). Modifications of the returned list will not affect the
440      * original list and vice versa.
441      *
442      * <p>If <code>number</code> is 0 or negative or if the original list is
443      * <code>null</code> or empty, an empty list is returned.
444      *
445      * <p>Note that this is somewhat inefficient if the input list is a
446      * {@link java.util.LinkedList} because repeated calls to
447      * {@link List#get(int)} are necessary (unless the whole list is copied).
448      *
449      * @param list the input list
450      * @param number the number of elements to copy
451      * @return an ArrayList containing the last elements from the original list;
452      * or an empty ArrayList iff the <code>list</code> is <code>null</code>
453      */
454     public static <T> ArrayList<T> lastN(final List<? extends T> list,
455             final int number) {
456         final ArrayList<T> result;
457         if (list != null) {
458             final int size = list.size();
459             if (number <= size) {
460                 // copy the whole collection
461                 result = new ArrayList<T>(list);
462             } else {
463                 // add last N elements
464                 result = new ArrayList<T>(number);
465                 for (int i = number; i > 0; i--) {
466                     result.add(list.get(size - number));
467                 }
468             }
469         } else {
470             // return empty list if input list is null
471             result = new ArrayList<T>(0);
472         }
473         return result;
474     }
475 
476 
477     /***
478      * Private constructor prevents creation of instances.
479      */
480     private CollectionUtils() {
481         super();
482     }
483 
484 }