org.geotoolkit.util.collection
Class XCollections

Object
  Static
      XCollections

public final class XCollections
extends Static

Static methods working on Collection objects. This is an extension to the Java Collections utility class.

Since:

3.10 (derived from 3.00)

Version:

3.20

Author:

Martin Desruisseaux (IRD, Geomatys)

Module:

utility/geotk-utility (download)

View source code for this class

Method Summary

static <E> boolean	addIfNonNull(Collection<E> collection, E element) Adds the given element to the given collection only if the element is non-null.
static Collection<?>	asCollection(Object value) Returns the given value as a collection.
static void	clear(Collection<?> collection) Clears the given collection, if non-null.
static void	clear(Map<?,?> map) Clears the given map, if non-null.
static <T extends Comparable<T>> Comparator<Collection<T>>	collectionComparator() Returns a comparator for arbitrary collections of comparable elements.
static <E> Collection<E>	copy(Collection<E> collection) Copies the content of the given collection to a standard Java collection.
static <K,V> Map<K,V>	copy(Map<K,V> map) Copies the content of the given map to a standard Java map.
static <E> Queue<E>	emptyQueue() Returns a queue which is always empty and accepts no element.
static <E> SortedSet<E>	emptySortedSet() Returns a sorted set which is always empty and accepts no element.
static int	hashMapCapacity(int elements) Returns the capacity to be given to the HashMap constructor for holding the given number of elements.
static <E> Set<E>	immutableSet(E... array) Returns the specified array as an immutable set, or null if the array is null.
static boolean	isNullOrEmpty(Collection<?> collection) Returns true if the given collection is either null or empty.
static boolean	isNullOrEmpty(Map<?,?> map) Returns true if the given map is either null or empty.
static <T extends Comparable<T>> Comparator<List<T>>	listComparator() Returns a comparator for lists of comparable elements.
static <T extends Comparable<T>> Comparator<SortedSet<T>>	sortedSetComparator() Returns a comparator for sorted sets of comparable elements.
static <K,V> Map<K,V>	unmodifiableMap(Map<K,V> map) Returns a unmodifiable version of the given map.

Methods inherited from class Object

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

Method Detail

clear

public static void clear(Collection<?> collection)

Clears the given collection, if non-null. If the collection is null, then this method does nothing. This is a convenience method when a null collection is a synonymous of empty.

Parameters:

collection - The collection to clear, or null.

Since:

3.18

clear

public static void clear(Map<?,?> map)

Clears the given map, if non-null. If the map is null, then this method does nothing. This is a convenience method when a null map is a synonymous of empty.

Parameters:

map - The map to clear, or null.

Since:

3.18

isNullOrEmpty

public static boolean isNullOrEmpty(Collection<?> collection)

Returns true if the given collection is either null or empty. If this method returns false, then the given collection is guaranteed to be non-null and to contain at least one element.

Parameters:

collection - The collection to test, or null.

Returns:

true if the given collection is null or empty, or false otherwise.

Since:

3.18

isNullOrEmpty

public static boolean isNullOrEmpty(Map<?,?> map)

Returns true if the given map is either null or empty. If this method returns false, then the given map is guaranteed to be non-null and to contain at least one element.

Parameters:

map - The map to test, or null.

Returns:

true if the given map is null or empty, or false otherwise.

Since:

3.18

addIfNonNull

public static <E> boolean addIfNonNull(Collection<E> collection,
                                       E element)

Adds the given element to the given collection only if the element is non-null. If any of the given argument is null, then this method does nothing.

Type Parameters:

E - The type of elements in the collection.

Parameters:

collection - The collection in which to add elements, or null.

element - The element to add in the collection, or null.

Returns:

true if the given element has been added, or false otherwise.

Since:

3.20

emptyQueue

public static <E> Queue<E> emptyQueue()

Returns a queue which is always empty and accepts no element.

Type Parameters:

E - The type of elements in the empty collection.

Returns:

An empty collection.

See Also:

Collections.emptyList(), Collections.emptySet()

emptySortedSet

public static <E> SortedSet<E> emptySortedSet()

Returns a sorted set which is always empty and accepts no element.

Type Parameters:

E - The type of elements in the empty collection.

Returns:

An empty collection.

See Also:

Collections.emptyList(), Collections.emptySet()

immutableSet

public static <E> Set<E> immutableSet(E... array)

Returns the specified array as an immutable set, or null if the array is null. If the given array contains duplicated elements, i.e. elements that are equal in the sense of Object.equals(Object), then only the last instance of the duplicated values will be included in the returned set.

Type Parameters:

E - The type of array elements.

Parameters:

array - The array to copy in a set. May be null.

Returns:

A set containing the array elements, or null if the given array was null.

Since:

3.17

See Also:

Collections.unmodifiableSet(Set)

unmodifiableMap

public static <K,V> Map<K,V> unmodifiableMap(Map<K,V> map)

Returns a unmodifiable version of the given map. This method is different than the standard Collections.unmodifiableMap(Map) in that it tries to returns a more efficient object when there is zero or one element. The map returned by this method may or may not be a view of the given map. Consequently this method shall be used only if the given map will not be modified after this method call. In case of doubt, use the standard Collections.unmodifiableMap(Map) method instead.

Type Parameters:

K - The type of keys in the map.

V - The type of values in the map.

Parameters:

map - The map to make unmodifiable, or null.

Returns:

A unmodifiable version of the given map, or null if the given map was null.

Since:

3.18 (derived from 3.17)

asCollection

public static Collection<?> asCollection(Object value)

Returns the given value as a collection. Special cases:

• If the value is an instance of Collection, then it is returned unchanged.
• Otherwise if the value is an array of objects, then it is returned as a list.
• Otherwise if the value is non-null, then it is returned as a singleton.
• Otherwise this method returns an empty set.

Parameters:

value - The value to return as a collection, or null.

Returns:

The value as a collection, or wrapped in a collection (never null).

Since:

3.20

listComparator

public static <T extends Comparable<T>> Comparator<List<T>> listComparator()

Returns a comparator for lists of comparable elements. The first element of each list are compared. If one is greater than or less than the other, the result of that comparison is returned. Otherwise the second element are compared, and so on until either non-equal elements are found, or end-of-list are reached. In the later case, the shortest list is considered less than the longest one.

If both lists have the same length and equal elements in the sense of Comparable.compareTo(T), then the comparator returns 0.

Type Parameters:

T - The type of elements in both lists.

Returns:

The ordering between two lists.

Since:

3.18 (derived from 2.5)

sortedSetComparator

public static <T extends Comparable<T>> Comparator<SortedSet<T>> sortedSetComparator()

Returns a comparator for sorted sets of comparable elements. The elements are compared in iteration order as for the list comparator.

Type Parameters:

T - The type of elements in both sets.

Returns:

The ordering between two sets.

Since:

3.18 (derived from 2.5)

collectionComparator

public static <T extends Comparable<T>> Comparator<Collection<T>> collectionComparator()

Returns a comparator for arbitrary collections of comparable elements. The elements are compared in iteration order as for the list comparator. This comparator make sense only for collections having determinist order like TreeSet, LinkedHashSet or queues. Do not use it with HashSet.

Type Parameters:

T - The type of elements in both collections.

Returns:

The ordering between two collections.

Since:

3.18 (derived from 2.5)

hashMapCapacity

public static int hashMapCapacity(int elements)

Returns the capacity to be given to the HashMap constructor for holding the given number of elements. This method computes the capacity for the default load factor, which is 0.75.

The same calculation can be used for LinkedHashMap and HashSet as well, which are built on top of HashMap.

Parameters:

elements - The number of elements to be put into the hash map or hash set.

Returns:

The optimal initial capacity to be given to the hash map constructor.

copy

public static <E> Collection<E> copy(Collection<E> collection)

Copies the content of the given collection to a standard Java collection. This method can be used when a in-memory, unsynchronized and modifiable copy of a collection is desired without prior knowledge of the collection type. The following table gives the type mapping applied by the method:

Input type	Output type
SortedSet	TreeSet
HashSet	HashSet
Other Set	LinkedHashSet
Queue	LinkedList
List or other Collection	ArrayList

Type Parameters:

E - The type of elements in the collection.

Parameters:

collection - The collection to copy, or null.

Returns:

A copy of the given collection, or null if the given collection was null.

Since:

3.18 (derived from 3.00)

copy

public static <K,V> Map<K,V> copy(Map<K,V> map)

Copies the content of the given map to a standard Java map. This method can be used when a in-memory, unsynchronized and modifiable copy of a map is desired without prior knowledge of the map type. The following table gives the type mapping applied by the method:

Input type	Output type
SortedMap	TreeMap
HashMap	HashMap
Other Map	LinkedHashMap

Type Parameters:

K - The type of keys in the map.

V - The type of values in the map.

Parameters:

map - The map to copy, or null.

Returns:

A copy of the given map, or null if the given map was null.

Since:

3.18 (derived from 3.00)