net.sf.kdgcommons.collections

Class CollectionUtil

java.lang.Object

net.sf.kdgcommons.collections.CollectionUtil

public class CollectionUtil
extends Object

Static utility methods for working with collections -- particularly parameterized collections.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CollectionUtil.FilterException An exception wrapper for filter(java.util.Collection<V>, net.sf.kdgcommons.collections.CollectionUtil.Predicate<V>).
static interface	CollectionUtil.IndexValueMapFunctor<V,R> A functor interface for map(java.util.Collection<V>, net.sf.kdgcommons.collections.CollectionUtil.IndexValueMapFunctor<V, R>).
static interface	CollectionUtil.IndexValueReduceFunctor<V,R> A functor used for the reduce(java.util.Collection<V>, net.sf.kdgcommons.collections.CollectionUtil.IndexValueReduceFunctor<V, R>) operation.
static class	CollectionUtil.MapException An exception wrapper for map(java.util.Collection<V>, net.sf.kdgcommons.collections.CollectionUtil.IndexValueMapFunctor<V, R>).
static interface	CollectionUtil.Predicate<V> Implement this for the filter(java.util.Collection<V>, net.sf.kdgcommons.collections.CollectionUtil.Predicate<V>) operation: return true to include an element in the result, false to skip it.
static class	CollectionUtil.ReduceException An exception wrapper for reduce(java.util.Collection<V>, net.sf.kdgcommons.collections.CollectionUtil.IndexValueReduceFunctor<V, R>).

Constructor Summary

Constructors

Constructor and Description
CollectionUtil()

Method Summary

Modifier and Type	Method and Description
static <T> void	addAll(Collection<T> coll, Iterable<T> src) Appends the contents of an iterable object to the passed collection.
static <T> void	addAll(Collection<T> coll, Iterator<T> src) Appends the values returned by an iterator to the passed collection.
static <T> void	addAll(Collection<T> coll, T... elems) Appends an arbitrary number of explicit elements to an existing collection.
static <T> Collection<T>	addIf(Collection<T> coll, T value, boolean expr) Adds a value to the collection if the boolean expression is true.
static <T> Collection<T>	addIfNotNull(Collection<T> coll, T value) Adds a value to the collection if it's not null.
static HashMap<Object,Object>	asMap(Object... elems) Returns a map (HashMap) built from the passed elements.
static <T> HashSet<T>	asSet(T... elems) Returns a set (HashSet) containing the passed elements.
static <T> List<T>	cast(List<?> list, Class<T> klass) Verifies that the passed list contains only elements of the given type, and returns it as a parameterized list (does not create a new list).
static <K,V> Map<K,V>	cast(Map<?,?> map, Class<K> keyClass, Class<V> valueClass) Verifies that the passed set contains only keys and values of the given types, and returns it as a parameterized map (does not create a new map).
static <T> Set<T>	cast(Set<?> set, Class<T> klass) Verifies that the passed set contains only elements of the given type, and returns it as a parameterized set (does not create a new set).
static <T> List<T>	combine(List<T> dest, Collection<T>... src) Adds all elements of the src collections to dest, returning dest.
static <K,V> Map<K,V>	combine(Map<K,V> dest, Map<K,V>... src) Adds all elements of the src collections to dest, returning dest.
static <T> Set<T>	combine(Set<T> dest, Collection<T>... src) Adds all elements of the src collections to dest, returning dest.
static int	compare(Collection<? extends Comparable> c1, Collection<? extends Comparable> c2) Compares two collections of Comparable elements.
static <T> Collection<T>	defaultIfEmpty(Collection<T> reg, Collection<T> def) Returns the default collection if the regular object is null or empty.
static <T> Iterable<T>	defaultIfNull(Iterable<T> reg, Iterable<T> def) Returns the second iterable if the first is null.
static <V> List<V>	filter(Collection<V> coll, CollectionUtil.Predicate<V> predicate) Applies the specified predicate functor to every element of a collection, in its natural iteration order, and returns a list containing only those elements for which the predicate returned true.
static <T> List<T>	filter(List<T> list, String regex, boolean include) Applies the given regex to the string value of every item in the passed list, building a new list from those value that either match or do not match.
static <T> T	first(List<T> list) Returns the first element of the passed list, null if the list is empty or null.
static Object	getVia(Object root, Object... keys) Retrieves a value from a nested collection hierarchy by following a sequence of keys.
static boolean	isEmpty(Collection<?> c) Returns true if the passed collection is either null or has size 0.
static boolean	isEmpty(Map<?,?> m) Returns true if the passed map is either null or has size 0.
static boolean	isNotEmpty(Collection<?> c) Returns true if the passed collection is not null and has size > 0.
static boolean	isNotEmpty(Map<?,?> m) Returns true if the passed map is not null and has size > 0.
static <T> String	join(Iterable<T> coll, String delim) Iterates the passed collection, converts its elements to strings, then concatenates those strings with the specified delimiter between them.
static <T> T	last(List<T> list) Returns the last element of the passed list, null if the list is empty or null.
static <V,R> List<R>	map(Collection<V> coll, CollectionUtil.IndexValueMapFunctor<V,R> functor) Applies the specified functor to every element of the given collection, in its natural iteration order, and returns a list of the results.
static <V,R> List<R>	map(ExecutorService threadpool, Collection<V> values, CollectionUtil.IndexValueMapFunctor<V,R> functor) Performs a parallel map operation.
static <T> List<List<T>>	partition(Iterable<T> source, int maxSize) Partitions the passed iterable into N sublists, each of which has at most maxSize elements.
static <K,V> Map<K,V>	putIf(Map<K,V> map, K key, V value, boolean expr) Stores an entry in a map if the boolean expression is true.
static <K,V> V	putIfAbsent(Map<K,V> map, K key, V value) Adds the specified item to a map if it does not already exist.
static <K,V> void	putIfAbsent(Map<K,V> base, Map<K,V> add) Adds entries from add to base where there is not already a mapping with the same key.
static <K,V> Map<K,V>	putIfNotNull(Map<K,V> map, K key, V value) Stores an entry in a map if the value is not null.
static <V,R> R	reduce(Collection<V> coll, CollectionUtil.IndexValueReduceFunctor<V,R> functor) Applies the specified functor to every element in the given collection, with the expectation that it will return a single value based on the item and any previous value.
static <T> List<T>	resize(List<T> list, int newSize) Resizes the passed list to N entries.
static <T> List<T>	resize(List<T> list, int newSize, T obj) Resizes the passed list to N entries.
static <K,V> Map<K,V>	submap(Map<K,V> src, Collection<K> keys) Returns a map that contains all keys in the specified collection.
static <K,V> Map<K,V>	submap(Map<K,V> src, Collection<K> keys, Map<K,V> dest) Extracts all mappings from the source map that correspond to the passed keys, and stores them in the destination map.

Methods inherited from class java.lang.Object

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

Constructor Detail

CollectionUtil

public CollectionUtil()

Method Detail

asSet

public static <T> HashSet<T> asSet(T... elems)

Returns a set (HashSet) containing the passed elements.

asMap

public static HashMap<Object,Object> asMap(Object... elems)

Returns a map (HashMap) built from the passed elements. Elements alternate between keys and values, and if given an odd number of elements the last will be used as the key for a null value. Elements will be added in the order they appear as parameters, so repeating a key will mean that only the last value is stored.

Note that the result is parameterized as Object,Object; as there is no way to differentiate between keys and values with varargs, we have to use the lowest common denominator.

Since:

1.0.15

addAll

public static <T> void addAll(Collection<T> coll,
                              T... elems)

Appends an arbitrary number of explicit elements to an existing collection. Primarily useful when writing testcases.

addAll

public static <T> void addAll(Collection<T> coll,
                              Iterator<T> src)

Appends the values returned by an iterator to the passed collection.

addAll

public static <T> void addAll(Collection<T> coll,
                              Iterable<T> src)

Appends the contents of an iterable object to the passed collection.

addIf

public static <T> Collection<T> addIf(Collection<T> coll,
                                      T value,
                                      boolean expr)

Adds a value to the collection if the boolean expression is true. Returns the collection as a convenience for chained invocations.

Since:

1.0.8

addIfNotNull

public static <T> Collection<T> addIfNotNull(Collection<T> coll,
                                             T value)

Adds a value to the collection if it's not null. Returns the collection as a convenience for chained invocations.

Since:

1.0.11

putIf

public static <K,V> Map<K,V> putIf(Map<K,V> map,
                                   K key,
                                   V value,
                                   boolean expr)

Stores an entry in a map if the boolean expression is true. Returns the map as a convenience for chained invocations.

Since:

1.0.15

putIfNotNull

public static <K,V> Map<K,V> putIfNotNull(Map<K,V> map,
                                          K key,
                                          V value)

Stores an entry in a map if the value is not null. Returns the map as a convenience for chained invocations.

Since:

1.0.15

putIfAbsent

public static <K,V> V putIfAbsent(Map<K,V> map,
                                  K key,
                                  V value)

Adds the specified item to a map if it does not already exist. Returns either the added item or the existing mapping.

Note: The return behavior differs from Map.put(), in that it returns the new value if there was no prior mapping. I find this more useful, as I typically want to do something with the mapping.

Warning: This operation is not synchronized. In most cases, a better approach is to use DefaultMap, with a functor to generate new entries.

Since:

1.0.12

putIfAbsent

public static <K,V> void putIfAbsent(Map<K,V> base,
                                     Map<K,V> add)

Adds entries from add to base where there is not already a mapping with the same key.

Since:

1.0.14

first

public static <T> T first(List<T> list)

Returns the first element of the passed list, null if the list is empty or null.

last

public static <T> T last(List<T> list)

Returns the last element of the passed list, null if the list is empty or null. Uses an indexed get unless the list is a subclass of java.util.LinkedList

cast

public static <T> List<T> cast(List<?> list,
                               Class<T> klass)

Verifies that the passed list contains only elements of the given type, and returns it as a parameterized list (does not create a new list).

This function exists to avoid suppressing warnings in application code.

Throws:

ClassCastException - if any element is a different type.

cast

public static <T> Set<T> cast(Set<?> set,
                              Class<T> klass)

Verifies that the passed set contains only elements of the given type, and returns it as a parameterized set (does not create a new set).

This function exists to avoid suppressing warnings in application code.

Throws:

ClassCastException - if any element is a different type.

cast

public static <K,V> Map<K,V> cast(Map<?,?> map,
                                  Class<K> keyClass,
                                  Class<V> valueClass)

Verifies that the passed set contains only keys and values of the given types, and returns it as a parameterized map (does not create a new map).

This function exists to avoid suppressing warnings in application code.

Throws:

ClassCastException - if any key/value is a different type.

Since:

1.0.15

resize

public static <T> List<T> resize(List<T> list,
                                 int newSize,
                                 T obj)

Resizes the passed list to N entries. Will add the specified object if the list is smaller than the desired size, discard trailing entries if larger. This is primarily used to presize a list that will be accessed by index, but it may also be used to truncate a list for display.

Returns:

The list, as a convenience for callers

Throws:

UnsupportedOperationException - if the list does not implement RandomAccess and its list iterator does not support the remove() operation

resize

public static <T> List<T> resize(List<T> list,
                                 int newSize)

Resizes the passed list to N entries. Will add nulls if the list is smaller than the desired size, discard trailing entries if larger. This is primarily used to presize a list that will be accessed by index, but it may also be used to truncate a list for display.

Returns:

The list, as a convenience for callers

Throws:

UnsupportedOperationException - if the list does not implement RandomAccess and its list iterator does not support the remove() operation

join

public static <T> String join(Iterable<T> coll,
                              String delim)

Iterates the passed collection, converts its elements to strings, then concatenates those strings with the specified delimiter between them. Nulls are converted to empty strings.

Since:

1.0.2

combine

public static <T> List<T> combine(List<T> dest,
                                  Collection<T>... src)

Adds all elements of the src collections to dest, returning dest. This is typically used when you need to combine collections temporarily for a method argument.

Since:

1.0.7

combine

public static <T> Set<T> combine(Set<T> dest,
                                 Collection<T>... src)

Adds all elements of the src collections to dest, returning dest. This is typically used when you need to combine collections temporarily for a method argument.

Since:

1.0.7

combine

public static <K,V> Map<K,V> combine(Map<K,V> dest,
                                     Map<K,V>... src)

Adds all elements of the src collections to dest, returning dest. This is typically used when you need to combine collections temporarily for a method argument.

Note: source maps are added in order; if the same keys are present in multiple sources, the last one wins.

Since:

1.0.7

isEmpty

public static boolean isEmpty(Collection<?> c)

Returns true if the passed collection is either null or has size 0.

isNotEmpty

public static boolean isNotEmpty(Collection<?> c)

Returns true if the passed collection is not null and has size > 0.

isEmpty

public static boolean isEmpty(Map<?,?> m)

Returns true if the passed map is either null or has size 0.

isNotEmpty

public static boolean isNotEmpty(Map<?,?> m)

Returns true if the passed map is not null and has size > 0.

compare

public static int compare(Collection<? extends Comparable> c1,
                          Collection<? extends Comparable> c2)

Compares two collections of Comparable elements. The two collections are iterated, and the first not-equal compareTo() result is returned. If the collections are of equal length and contain the same elements in iteration order, they are considered equal. If they are of unequal length but contain the same elements in iteration order, the shorter is considered less than the longer.

Note that two collections that are equal based on their intrinsic equals() method, but iterate in a different order (ie, hash-based collections) are not considered equal by this method.

Since:

1.0.14

defaultIfNull

public static <T> Iterable<T> defaultIfNull(Iterable<T> reg,
                                            Iterable<T> def)

Returns the second iterable if the first is null. This is used for a null-safe for loop.

defaultIfEmpty

public static <T> Collection<T> defaultIfEmpty(Collection<T> reg,
                                               Collection<T> def)

Returns the default collection if the regular object is null or empty.

getVia

public static Object getVia(Object root,
                            Object... keys)

Retrieves a value from a nested collection hierarchy by following a sequence of keys. Supports arbitrary nesting of maps, arrays, and lists.

Parameters:

root - The root object.

keys - One or more keys. The first key is applied to the root object, the second key is applied to the result of that, and so on. Arrays and lists may only be accessed via numeric keys; maps may be accessed via any type of key.

Returns:

The object located via the sequence of keys, null if any key along the path does not resolve to an object.

Throws:

IllegalArgumentException - if any object found during the traversal is not a valid collection type, or if the key is not appropriate for the collection.

Since:

1.0.15

map

public static <V,R> List<R> map(Collection<V> coll,
                                CollectionUtil.IndexValueMapFunctor<V,R> functor)

Applies the specified functor to every element of the given collection, in its natural iteration order, and returns a list of the results.

If the functor throws, it will be rethrown in a CollectionUtil.MapException, which provides detailed information and partial work.

Since:

1.0.10

map

public static <V,R> List<R> map(ExecutorService threadpool,
                                Collection<V> values,
                                CollectionUtil.IndexValueMapFunctor<V,R> functor)
                         throws InterruptedException

Performs a parallel map operation. For each element in the source collection, a callable is dispatched to the passed ExecutorService to invoke the specified functor. The results are accumulated and returned as a list, in the order of the original collection's iterator.

If any element causes an exception, this method throws CollectionUtil.MapException. While that exception returns partial results, there is no guarantee that the results represent a particular range of the source collection.

This method will wait until all of the elements of the collection have been processed, unless it is interrupted. If multiple invocations threw, one will be chosen arbitrarily; there is no guarantee that it represents the first collection element to cause an exception.

Throws:

InterruptedException

Since:

1.0.10

reduce

public static <V,R> R reduce(Collection<V> coll,
                             CollectionUtil.IndexValueReduceFunctor<V,R> functor)

Applies the specified functor to every element in the given collection, with the expectation that it will return a single value based on the item and any previous value.

Since:

1.0.10

filter

public static <V> List<V> filter(Collection<V> coll,
                                 CollectionUtil.Predicate<V> predicate)

Applies the specified predicate functor to every element of a collection, in its natural iteration order, and returns a list containing only those elements for which the predicate returned true.

If the functor throws, it will be rethrown in a CollectionUtil.FilterException, which provides detailed information and partial work.

Since:

1.0.11

filter

public static <T> List<T> filter(List<T> list,
                                 String regex,
                                 boolean include)

Applies the given regex to the string value of every item in the passed list, building a new list from those value that either match or do not match. Null entries are treated as an empty string for matching, but will be returned as null.

Parameters:

list - The source list; this is unmodified.

regex - Regex applied to every string in the list.

include - If true, strings that match are copied to the output list; if false, strings that don't match are copied.

Since:

1.0.3

partition

public static <T> List<List<T>> partition(Iterable<T> source,
                                          int maxSize)

Partitions the passed iterable into N sublists, each of which has at most maxSize elements.

submap

public static <K,V> Map<K,V> submap(Map<K,V> src,
                                    Collection<K> keys)

Returns a map that contains all keys in the specified collection.

The returned map is a HashMap; see variant for choosing map type.

submap

public static <K,V> Map<K,V> submap(Map<K,V> src,
                                    Collection<K> keys,
                                    Map<K,V> dest)

Extracts all mappings from the source map that correspond to the passed keys, and stores them in the destination map. Returns the destination map as a convenience.