com.twelvemonkeys.util
Class CollectionUtil

java.lang.Object
  com.twelvemonkeys.util.CollectionUtil

public final class CollectionUtil
extends Object

A utility class with some useful collection-related functions.

Version:

$Id: com/twelvemonkeys/util/CollectionUtil.java#3 $

Author:

Harald Kuhr, Eirik Torske, last modified by $Author: haku $

See Also:

Collections, Arrays

Method Summary

static <E> void	addAll(Collection<E> pCollection, Iterator<? extends E> pIterator) Adds all elements of the iterator to the collection.
static <K,V> Map<V,K>	invert(Map<K,V> pSource) Creates an inverted mapping of the key/value pairs in the given map.
static <K,V> Map<V,K>	invert(Map<K,V> pSource, Map<V,K> pResult, DuplicateHandler<K> pHandler) Creates an inverted mapping of the key/value pairs in the given map.
static <E> ListIterator<E>	iterator(E[] pArray) Creates a thin Iterator wrapper around an array.
static <E> ListIterator<E>	iterator(E[] pArray, int pStart, int pLength) Creates a thin Iterator wrapper around an array.
static <T> Iterator<T>	iterator(Enumeration<T> pEnum)
static void	main(String[] pArgs) Testing only.
static Object	mergeArrays(Object pArray1, int pOffset1, int pLength1, Object pArray2, int pOffset2, int pLength2) Merges two arrays into a new array.
static Object	mergeArrays(Object pArray1, Object pArray2) Merges two arrays into a new array.
static <T> Comparator<T>	reverseOrder(Comparator<T> pOriginal)
static Object	subArray(Object pArray, int pStart) Creates an array containing a subset of the original array.
static Object	subArray(Object pArray, int pStart, int pLength) Creates an array containing a subset of the original array.
static <T> T[]	subArray(T[] pArray, int pStart) Creates an array containing a subset of the original array.
static <T> T[]	subArray(T[] pArray, int pStart, int pLength) Creates an array containing a subset of the original array.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

main

public static void main(String[] pArgs)

Testing only.

Parameters:

pArgs - command line arguents

mergeArrays

public static Object mergeArrays(Object pArray1,
                                 Object pArray2)

Merges two arrays into a new array. Elements from array1 and array2 will be copied into a new array, that has array1.length + array2.length elements.

Parameters:

pArray1 - First array

pArray2 - Second array, must be compatible with (assignable from) the first array

Returns:

A new array, containing the values of array1 and array2. The array (wrapped as an object), will have the length of array1 + array2, and can be safely cast to the type of the array1 parameter.

See Also:

mergeArrays(Object,int,int,Object,int,int), System.arraycopy(Object,int,Object,int,int)

mergeArrays

public static Object mergeArrays(Object pArray1,
                                 int pOffset1,
                                 int pLength1,
                                 Object pArray2,
                                 int pOffset2,
                                 int pLength2)

Merges two arrays into a new array. Elements from pArray1 and pArray2 will be copied into a new array, that has pLength1 + pLength2 elements.

Parameters:

pArray1 - First array

pOffset1 - the offset into the first array

pLength1 - the number of elements to copy from the first array

pArray2 - Second array, must be compatible with (assignable from) the first array

pOffset2 - the offset into the second array

pLength2 - the number of elements to copy from the second array

Returns:

A new array, containing the values of pArray1 and pArray2. The array (wrapped as an object), will have the length of pArray1 + pArray2, and can be safely cast to the type of the pArray1 parameter.

See Also:

System.arraycopy(Object,int,Object,int,int)

subArray

public static Object subArray(Object pArray,
                              int pStart)

Creates an array containing a subset of the original array. If the sub array is same length as the original (pStart == 0), the original array will be returned.

Parameters:

pArray - the original array

pStart - the start index of the original array

Returns:

a subset of the original array, or the original array itself, if pStart is 0.

Throws:

IllegalArgumentException - if pArray is null or if pArray is not an array.

ArrayIndexOutOfBoundsException - if pStart < 0

subArray

public static <T> T[] subArray(T[] pArray,
                               int pStart)

Creates an array containing a subset of the original array. If the sub array is same length as the original (pStart == 0), the original array will be returned.

Parameters:

pArray - the original array

pStart - the start index of the original array

Returns:

a subset of the original array, or the original array itself, if pStart is 0.

Throws:

IllegalArgumentException - if pArray is null

ArrayIndexOutOfBoundsException - if pStart < 0

subArray

public static Object subArray(Object pArray,
                              int pStart,
                              int pLength)

Creates an array containing a subset of the original array. If the pLength parameter is negative, it will be ignored. If there are not pLength elements in the original array after pStart, the pLength parameter will be ignored. If the sub array is same length as the original, the original array will be returned.

Parameters:

pArray - the original array

pStart - the start index of the original array

pLength - the length of the new array

Returns:

a subset of the original array, or the original array itself, if pStart is 0 and pLength is either negative, or greater or equal to pArray.length.

Throws:

IllegalArgumentException - if pArray is null or if pArray is not an array.

ArrayIndexOutOfBoundsException - if pStart < 0

subArray

public static <T> T[] subArray(T[] pArray,
                               int pStart,
                               int pLength)

Creates an array containing a subset of the original array. If the pLength parameter is negative, it will be ignored. If there are not pLength elements in the original array after pStart, the pLength parameter will be ignored. If the sub array is same length as the original, the original array will be returned.

Parameters:

pArray - the original array

pStart - the start index of the original array

pLength - the length of the new array

Returns:

a subset of the original array, or the original array itself, if pStart is 0 and pLength is either negative, or greater or equal to pArray.length.

Throws:

IllegalArgumentException - if pArray is null

ArrayIndexOutOfBoundsException - if pStart < 0

iterator

public static <T> Iterator<T> iterator(Enumeration<T> pEnum)

addAll

public static <E> void addAll(Collection<E> pCollection,
                              Iterator<? extends E> pIterator)

Adds all elements of the iterator to the collection.

Parameters:

pCollection - the collection

pIterator - the elements to add

Throws:

UnsupportedOperationException - if add is not supported by the given collection.

ClassCastException - class of the specified element prevents it from being added to this collection.

NullPointerException - if the specified element is null and this collection does not support null elements.

IllegalArgumentException - some aspect of this element prevents it from being added to this collection.

iterator

public static <E> ListIterator<E> iterator(E[] pArray)

Creates a thin Iterator wrapper around an array.

Parameters:

pArray - the array to iterate

Returns:

a new ListIterator

Throws:

IllegalArgumentException - if pArray is null, pStart < 0, or pLength > pArray.length - pStart

iterator

public static <E> ListIterator<E> iterator(E[] pArray,
                                           int pStart,
                                           int pLength)

Creates a thin Iterator wrapper around an array.

Parameters:

pArray - the array to iterate

pStart - the offset into the array

pLength - the number of elements to include in the iterator

Returns:

a new ListIterator

Throws:

IllegalArgumentException - if pArray is null, pStart < 0, or pLength > pArray.length - pStart

invert

public static <K,V> Map<V,K> invert(Map<K,V> pSource)

Creates an inverted mapping of the key/value pairs in the given map.

Parameters:

pSource - the source map

Returns:

a new Map of same type as pSource

Throws:

IllegalArgumentException - if pSource == null, or if a new map can't be instantiated, or if source map contains duplicates.

See Also:

invert(java.util.Map, java.util.Map, DuplicateHandler)

invert

public static <K,V> Map<V,K> invert(Map<K,V> pSource,
                                    Map<V,K> pResult,
                                    DuplicateHandler<K> pHandler)

Creates an inverted mapping of the key/value pairs in the given map. Optionally, a duplicate handler may be specified, to resolve duplicate keys in the result map.

Parameters:

pSource - the source map

pResult - the map used to contain the result, may be null, in that case a new Map of same type as pSource is created. The result map should be empty, otherwise duplicate values will need to be resolved.

pHandler - duplicate handler, may be null if source map don't contain duplicate values

Returns:

pResult, or a new Map if pResult == null

Throws:

IllegalArgumentException - if pSource == null, or if result map is null and a new map can't be instantiated, or if source map contains duplicate values and pHandler == null.

reverseOrder

public static <T> Comparator<T> reverseOrder(Comparator<T> pOriginal)