ucar.unidata.util

Class CollectionHelpers

java.lang.Object

ucar.unidata.util.CollectionHelpers

public final class CollectionHelpers
extends java.lang.Object

A collection (ugh) of static methods that make working with Java's default collections a bit easier, or at least allows you to elide some of the redundancy of idiomatic Java.

Make use of "static imports" to omit even more needless code.

Method Summary

Modifier and Type	Method and Description
static <T> T[]	arr(T... ts) "Converts" the incoming "varargs" into an array.
static <E> java.util.List<E>	arrList() Creates an empty ArrayList that uses a little cleverness with Java's generics.
static <E> java.util.List<E>	arrList(java.util.Collection<? extends E> c) Copies an existing Collection into a new ArrayList.
static <E> java.util.List<E>	arrList(int capacity) Creates an empty ArrayList with a given capacity.
static <A,B extends A> B	cast(A o) "Generics-friendly" way to cast an object of some superclass (A) to a subclass or implementation (B).
static <E> java.util.Collection<E>	collect(java.lang.Class<? extends java.util.Collection> cl, E... elements) Creates a new cl instance (limited to things implementing Collection) populated with the "varargs".
static <E> java.util.List<E>	concurrentList() Creates an empty CopyOnWriteArrayList.
static <E> java.util.List<E>	concurrentList(java.util.Collection<E> original) Creates a new CopyOnWriteArrayList that contains all of the elements in original.
static <E> java.util.List<E>	concurrentList(E... elems) Creates a new CopyOnWriteArrayList from the incoming "varargs".
static <K,V> java.util.Map<K,V>	concurrentMap() Abuses Java's sad "type" implementation to create a new ConcurrentHashMap.
static <E> java.util.Set<E>	concurrentSet() Creates a new CopyOnWriteArraySet.
static <E> java.util.Set<E>	concurrentSet(java.util.Collection<E> original) Creates a new CopyOnWriteArraySet that contains all of the elements in original.
static <E> java.util.Set<E>	concurrentSet(E... elems) Creates a new CopyOnWriteArraySet from the incoming "varargs".
static boolean	contains(java.lang.Object collection, java.lang.Object item) Searches an object to see if it "contains" another object.
static int	len(java.lang.Object o) Determines the "length" of a given object.
static <E> java.util.List<E>	linkedList()
static <E> java.util.List<E>	linkedList(java.util.Collection<? extends E> c)
static <E> java.util.List<E>	list(E... elements) Creates a List from incoming "varargs".
static <A,B> java.util.List<B>	map(Function<A,B> f, java.util.List<A> as) Applies a given function to each item in a given list.
static <A,B> java.util.Set<B>	map(Function<A,B> f, java.util.Set<A> as) Applies a given function to each item in a given Set.
static <E> java.util.Set<E>	newHashSet() Creates an empty HashSet that uses a little cleverness with Java's generics.
static <E> java.util.Set<E>	newHashSet(java.util.Collection<E> original) Copies an existing Collection into a new HashSet.
static <E> java.util.Set<E>	newHashSet(int initialCapacity) Creates an empty HashSet with a given initial capacity.
static <K,V> java.util.Map<K,V>	newLinkedHashMap() Creates an empty LinkedHashMap that uses a little cleverness with Java's generics.
static <K,V> java.util.Map<K,V>	newLinkedHashMap(int initialCapacity) Creates an empty LinkedHashMap with a given initial capacity.
static <K,V> java.util.Map<K,V>	newLinkedHashMap(java.util.Map<K,V> original) Copies an existing Map into a new LinkedHashMap.
static <E> java.util.Set<E>	newLinkedHashSet() Creates an empty LinkedHashSet that uses a little cleverness with Java's generics.
static <E> java.util.Set<E>	newLinkedHashSet(java.util.Collection<E> original) Copies a Collection into a new LinkedHashSet.
static <E> java.util.Set<E>	newLinkedHashSet(int initialCapacity) Creates an empty LinkedHashSet with a given initial capacity.
static <K,V> java.util.Map<K,V>	newMap() Creates an empty HashSet that uses a little cleverness with Java's generics.
static <K,V> java.util.Map<K,V>	newMap(int initialCapacity) Creates an empty HashSet with a given initial capacity.
static <K,V> java.util.Map<K,V>	newMap(java.util.Map<K,V> original) Copies an existing Map into a new HashMap.
static <E> java.util.Collection<E>	recollect(java.lang.Class<? extends java.util.Collection> cl, java.util.Collection<E> old) Copies an existing Collection into a new (non-abstract!) Collection class.
static <E> java.util.Set<E>	set(E... elements) Creates a Set from incoming "varargs".
static <K,V> java.util.Map<K,V>	zipMap(java.util.Collection<? extends K> keys, java.util.Collection<? extends V> values) A version of zipMap(Object[], Object[]) that works with Collections.
static <K,V> java.util.Map<K,V>	zipMap(K[] keys, V[] values) Takes arrays of keys and values and merges them together to form a Map.

Methods inherited from class java.lang.Object

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

Method Detail

arr

@SafeVarargs
public static <T> T[] arr(T... ts)

"Converts" the incoming "varargs" into an array.

Useful for doing things like: String[] strs = arr("hello", "how", "are", "you?");

Type Parameters:

T - Type of items to be converted into an array.

Parameters:

ts - Items that will make up the elements of the returned array. Cannot be null, and (for now) the items should be of the same type.

Returns:

Array populated with each item from ts.

list

@SafeVarargs
public static <E> java.util.List<E> list(E... elements)

Creates a List from incoming "varargs". Currently uses ArrayList as the List implementation.

Used like so: List<String> listy = list("y", "helo", "thar");

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

elements - Items that will make up the elements of the returned List.

Returns:

List whose elements are each item within elements.

set

@SafeVarargs
public static <E> java.util.Set<E> set(E... elements)

Creates a Set from incoming "varargs". Currently uses LinkedHashSet as the Set implementation (to preserve ordering).

Used like so:

 for (String s : set("beep", "boop", "blorp")) { ... }

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

elements - Items that will appear within the returned Set. Cannot be null, and (for now) the items should be of the same type.

Returns:

A Set containing the items in elements. Remember that Sets only contain unique elements!

collect

public static <E> java.util.Collection<E> collect(java.lang.Class<? extends java.util.Collection> cl,
                                                  E... elements)

Creates a new cl instance (limited to things implementing Collection) populated with the "varargs". Useful if you truly despise arr(Object...), list(Object...), or set(Object...).

Example: Collection<Integer> ints = collect(PriorityBlockingQueue.class, 1, 2, 3);

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

cl - A (non-abstract!) class that implements Collection. Cannot be null.

elements - Objects that will be added to the collection.

Returns:

An instance of cl containing the given objects.

Throws:

java.lang.RuntimeException - if Constructor#newInstance(Object...) had problems.

See Also:

arr(Object...), list(Object...), set(Object...)

len

public static int len(java.lang.Object o)

Determines the "length" of a given object. This method currently understands:

• Collection
• Map
• CharSequence
• Array
• Iterable
• Iterator

More coming!

Parameters:

o - Object whose length we want. Cannot be null.

Returns:

"Length" of o.

Throws:

java.lang.NullPointerException - if o is null.

java.lang.IllegalArgumentException - if the method doesn't know how to test whatever type of object o might be.

contains

public static boolean contains(java.lang.Object collection,
                               java.lang.Object item)

Searches an object to see if it "contains" another object. This method currently knows how to search:

• Collection
• Map
• CharSequence
• Array
• Iterable
• Iterator

More coming!

Parameters:

collection - Object that will be searched for item. Cannot be null.

item - Object to search for within o. null values are allowed.

Returns:

true if o contains item, false otherwise.

Throws:

java.lang.NullPointerException - if o is null.

java.lang.IllegalArgumentException - if the method doesn't know how to search whatever type of object o might be.

newHashSet

public static <E> java.util.Set<E> newHashSet()

Creates an empty HashSet that uses a little cleverness with Java's generics. Useful for eliminating redundant type information and declaring fields as final.

Please consider using newHashSet(int) or newHashSet(Collection) instead of this method.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Returns:

A new, empty HashSet.

See Also:

newHashSet(int), newHashSet(Collection)

newHashSet

public static <E> java.util.Set<E> newHashSet(int initialCapacity)

Creates an empty HashSet with a given initial capacity.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

initialCapacity - Initial capacity of the HashSet. Cannot be negative.

Returns:

A new, empty HashSet with the given initial capacity.

newHashSet

public static <E> java.util.Set<E> newHashSet(java.util.Collection<E> original)

Copies an existing Collection into a new HashSet.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

original - Collection to be copied. Cannot be null.

Returns:

A new HashSet whose contents are the same as original.

newLinkedHashSet

public static <E> java.util.Set<E> newLinkedHashSet()

Creates an empty LinkedHashSet that uses a little cleverness with Java's generics. Useful for eliminating redundant type information and declaring fields as final.

Please consider using newLinkedHashSet(int) or newLinkedHashSet(Collection) instead of this method.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Returns:

A new, empty LinkedHashSet.

See Also:

newLinkedHashSet(int), newLinkedHashSet(Collection)

newLinkedHashSet

public static <E> java.util.Set<E> newLinkedHashSet(int initialCapacity)

Creates an empty LinkedHashSet with a given initial capacity.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

initialCapacity - Initial capacity of the LinkedHashSet. Cannot be negative.

Returns:

A new, empty LinkedHashSet with the given initial capacity.

newLinkedHashSet

public static <E> java.util.Set<E> newLinkedHashSet(java.util.Collection<E> original)

Copies a Collection into a new LinkedHashSet.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

original - Collection to be copied. Cannot be null.

Returns:

A new LinkedHashSet whose contents are the same as original.

newMap

public static <K,V> java.util.Map<K,V> newMap()

Creates an empty HashSet that uses a little cleverness with Java's generics. Useful for eliminating redundant type information and declaring fields as final, while also reducing compiler warnings.

Please consider using newMap(int) or newMap(Map) instead of this method.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Returns:

A new, empty HashMap.

See Also:

newMap(int), newMap(Map)

newMap

public static <K,V> java.util.Map<K,V> newMap(int initialCapacity)

Creates an empty HashSet with a given initial capacity.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Parameters:

initialCapacity - Initial capacity of the HashMap. Cannot be negative.

Returns:

A new, empty HashMap with the given initial capacity.

newMap

public static <K,V> java.util.Map<K,V> newMap(java.util.Map<K,V> original)

Copies an existing Map into a new HashMap.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Parameters:

original - Map to be copied. Cannot be null.

Returns:

A new HashMap whose contents are the same as original.

newLinkedHashMap

public static <K,V> java.util.Map<K,V> newLinkedHashMap()

Creates an empty LinkedHashMap that uses a little cleverness with Java's generics. Useful for eliminating redundant type information and declaring fields as final, while also reducing compiler warnings.

Please consider using newLinkedHashMap(int) or newLinkedHashSet(Collection) instead of this method.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Returns:

A new, empty LinkedHashMap.

See Also:

newLinkedHashMap(int), newLinkedHashMap(Map)

newLinkedHashMap

public static <K,V> java.util.Map<K,V> newLinkedHashMap(int initialCapacity)

Creates an empty LinkedHashMap with a given initial capacity.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Parameters:

initialCapacity - Initial capacity of the LinkedHashMap. Cannot be negative.

Returns:

A new, empty LinkedHashMap with the given initial capacity.

newLinkedHashMap

public static <K,V> java.util.Map<K,V> newLinkedHashMap(java.util.Map<K,V> original)

Copies an existing Map into a new LinkedHashMap.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Parameters:

original - Map to be copied. Cannot be null.

Returns:

A new LinkedHashMap whose contents are the same as original.

concurrentMap

public static <K,V> java.util.Map<K,V> concurrentMap()

Abuses Java's sad "type" implementation to create a new ConcurrentHashMap.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Returns:

Shiny and new ConcurrentHashMap

concurrentList

public static <E> java.util.List<E> concurrentList()

Creates an empty CopyOnWriteArrayList. Keep in mind that you only want to use CopyOnWriteArrayList for lists that are not going to be modified very often!

Type Parameters:

E - Type of items that will be added to the resulting collection.

Returns:

A new, empty CopyOnWriteArrayList.

concurrentList

public static <E> java.util.List<E> concurrentList(java.util.Collection<E> original)

Creates a new CopyOnWriteArrayList that contains all of the elements in original. Keep in mind that you only want to use CopyOnWriteArrayList for lists that are not going to be modified very often!

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

original - Collection to be copied into the new list.

Returns:

A new CopyOnWriteArrayList whose contents are the same as original.

concurrentList

@SafeVarargs
public static <E> java.util.List<E> concurrentList(E... elems)

Creates a new CopyOnWriteArrayList from the incoming "varargs". Keep in mind that you only want to use CopyOnWriteArrayList for lists that are not going to be modified very often!

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

elems - Elements that will be contained in the resulting list.

Returns:

A new CopyOnWriteArrayList that contains the incoming objects.

concurrentSet

public static <E> java.util.Set<E> concurrentSet()

Creates a new CopyOnWriteArraySet. Keep in mind that you only want to use a CopyOnWriteArraySet for sets that are not going to be modified very often!

Type Parameters:

E - Type of items that will be added to the resulting collection.

Returns:

New, empty CopyOnWriteArraySet.

concurrentSet

public static <E> java.util.Set<E> concurrentSet(java.util.Collection<E> original)

Creates a new CopyOnWriteArraySet that contains all of the elements in original. Keep in mind that you only want to use a CopyOnWriteArraySet for sets that are not going to be modified very often!

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

original - Collection to be copied into the new set.

Returns:

CopyOnWriteArraySet whose contents are the same as original.

concurrentSet

@SafeVarargs
public static <E> java.util.Set<E> concurrentSet(E... elems)

Creates a new CopyOnWriteArraySet from the incoming "varargs". Keep in mind that you only want to use a CopyOnWriteArraySet for sets that are not going to be modified very often!

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

elems - Elements that will be contained in the resulting set.

Returns:

CopyOnWriteArraySet that contains the incoming objects.

linkedList

public static <E> java.util.List<E> linkedList()

linkedList

public static <E> java.util.List<E> linkedList(java.util.Collection<? extends E> c)

arrList

public static <E> java.util.List<E> arrList()

Creates an empty ArrayList that uses a little cleverness with Java's generics. Useful for eliminating redundant type information and declaring fields as final.

Used like so: List<String> listy = arrList();

Please consider using arrList(int) or arrList(Collection) instead of this method.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Returns:

A new, empty ArrayList.

See Also:

arrList(int), arrList(Collection)

arrList

public static <E> java.util.List<E> arrList(int capacity)

Creates an empty ArrayList with a given capacity.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

capacity - The initial size of the returned ArrayList.

Returns:

A new, empty ArrayList that has an initial capacity of capacity elements.

See Also:

ArrayList(int)

arrList

public static <E> java.util.List<E> arrList(java.util.Collection<? extends E> c)

Copies an existing Collection into a new ArrayList.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

c - Collection whose elements are to be placed into the returned ArrayList.

Returns:

An ArrayList containing the elements of c.

See Also:

ArrayList(Collection)

recollect

public static <E> java.util.Collection<E> recollect(java.lang.Class<? extends java.util.Collection> cl,
                                                    java.util.Collection<E> old)

Copies an existing Collection into a new (non-abstract!) Collection class.

Type Parameters:

E - Type of items that will be added to the resulting collection.

Parameters:

cl - Non-abstract Collection class.

old - An existing Collection.

Returns:

A new instance of cl that contains all of the elements from old.

Throws:

java.lang.RuntimeException - if there was trouble creating a new instance of cl.

See Also:

collect(Class, Object...)

zipMap

public static <K,V> java.util.Map<K,V> zipMap(K[] keys,
                                              V[] values)

Takes arrays of keys and values and merges them together to form a Map. The returned Map is a LinkedHashMap and is truncated in length to the length of the shorter parameter.

This is intended for use as "varargs" supplied to arr(Object...). Rather than doing something ugly like:

 Map<String, String> mappy = new LinkedHashMap<String, String>();
 mappy.put("key0", "val0");
 mappy.put("key1", "val1");
 ...
 mappy.put("keyN", "valN");
 

Simply do like so:

 mappy = zipMap(
     arr("key0", "key1", ..., "keyN"),
     arr("val0", "val1", ..., "valN"));
 

The latter approach also allows you to make static final Maps much more easily.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Parameters:

keys - Array whose elements will be the keys in a Map.

values - Array whose elements will the values in a Map.

Returns:

A Map whose entries are of the form keys[N], values[N].

See Also:

arr(Object...), zipMap(Collection, Collection)

zipMap

public static <K,V> java.util.Map<K,V> zipMap(java.util.Collection<? extends K> keys,
                                              java.util.Collection<? extends V> values)

A version of zipMap(Object[], Object[]) that works with Collections.

Type Parameters:

K - Type of keys that will be added to the Map.

V - Type of values that will be added to the Map.

Parameters:

keys - Items that will be the keys in the resulting Map.

values - Items that will be the values in the result Map.

Returns:

A Map whose entries are of the form keys[N], values[N].

See Also:

zipMap(Object[], Object[])

map

public static <A,B> java.util.List<B> map(Function<A,B> f,
                                          java.util.List<A> as)

Applies a given function to each item in a given list.

Type Parameters:

A - Type of items that will be passed into f.

B - Type of items that will be in the resulting List.

Parameters:

f - The Function to apply.

as - The list whose items are to be fed into f.

Returns:

New list containing the results of each element of as being passed through f.

map

public static <A,B> java.util.Set<B> map(Function<A,B> f,
                                         java.util.Set<A> as)

Applies a given function to each item in a given Set.

Type Parameters:

A - Type of items that will be passed into f.

B - Type of items that will be in the resulting Set.

Parameters:

f - The Function to apply to as.

as - The Set whose items are to be fed into f.

Returns:

New Set containing the results of passing each element in as through f.

cast

public static <A,B extends A> B cast(A o)

"Generics-friendly" way to cast an object of some superclass (A) to a subclass or implementation (B). This method will fail if you attempt to cast to a type that is not a subclass of type A.

Example/Justification:
Consider a method like XmlUtil.findChildren(Node, String).
Despite findChildren only returning lists containing Node objects, Java will generate a warning for the following code:

 import ucar.unidata.xml.XmlUtil;
 ....
 List<Node> nodes = XmlUtil.findChildren(panel, "blah");
 

cast is a nice and terse way to avoid those warnings. Here's the previous example (with static imports of cast and findChildren):

 import static ucar.unidata.xml.XmlUtil.findChildren;
 import static edu.wisc.ssec.mcidasv.util.CollectionHelpers.cast;
 ....
 List<Node> nodes = cast(findChildren(panel, "blah"));
 

Type Parameters:

A - Superclass of B. This is what you are "casting from"...likely Object in most cases

B - Subclass of A. This is what you are "casting to".

Parameters:

o - The object whose type you are casting.

Returns:

o, casted from type A to B. Enjoy!