gov.sandia.cognition.collection

Class CollectionUtil

java.lang.Object

gov.sandia.cognition.collection.CollectionUtil

@CodeReview(reviewer="Kevin R. Dixon",
            date="2008-12-02",
            changesNeeded=false,
            comments="Looks good.")
public class CollectionUtil
extends java.lang.Object

The CollectionUtil class implements static methods for dealing with Collection and Iterable objects. They are both put into the same utility class so that they can be interchanged without changing the method call.

Since:

2.1

Author:

Justin Basilico

Constructor Summary

Constructors

Constructor and Description
CollectionUtil()

Method Summary

Modifier and Type	Method and Description
static <DataType> java.util.ArrayList<DataType>	asArrayList(java.lang.Iterable<DataType> data) Returns the Collection as an ArrayList.
static <DataType> java.util.ArrayList<DataType>	createArrayList(DataType first, DataType second) Creates a new ArrayList from the given pair of values.
static <KeyType,ValueType> java.util.HashMap<KeyType,ValueType>	createHashMapWithSize(int size) Creates a new HashMap with the given expected size.
static <ValueType> java.util.HashSet<ValueType>	createHashSetWithSize(int size) Creates a new HashSet with the given expected size.
static <KeyType,ValueType> java.util.LinkedHashMap<KeyType,ValueType>	createLinkedHashMapWithSize(int size) Creates a new LinkedHashMap with the given expected size.
static <ValueType> java.util.LinkedHashSet<ValueType>	createLinkedHashSetWithSize(int size) Creates a new LinkedHashSet with the given expected size.
static <DataType> java.util.ArrayList<java.util.List<? extends DataType>>	createSequentialPartitions(java.lang.Iterable<? extends DataType> data, int numPartitions) Creates a partition of the given data into "numPartition" roughly equal sets, preserving their pre-existing sequential ordering, with the nonzero remainder elements going into the final partition.
static <DataType> java.util.ArrayList<java.util.List<? extends DataType>>	createSequentialPartitions(java.util.List<? extends DataType> data, int numPartitions) Creates a partition of the given data into "numPartition" roughly equal sets, preserving their pre-existing sequential ordering, with the nonzero remainder elements going into the final partition.
static <T> boolean	equals(java.util.Collection<? extends T> data1, java.util.Collection<? extends T> data2) Check if two collections return exactly the same objects in the same order.
static <T> boolean	equals(java.lang.Iterable<? extends T> data1, java.lang.Iterable<? extends T> data2) Check if two iterables return exactly the same objects in the same order.
static <ComparableType> int[]	findKthLargest(int k, java.util.ArrayList<? extends ComparableType> data, java.util.Comparator<? super ComparableType> comparator) Returns the set of indices of the data array such that data[return[0..k-1]] ≤ data[return[k]] ≤ data[return[k+1...N-1]].
static <DataType> DataType	getElement(java.lang.Iterable<DataType> iterable, int index) Returns the indexed value into the Iterable.
static <T> T	getFirst(java.lang.Iterable<? extends T> iterable) Gets the first element from an iterable.
static <T> T	getFirst(java.util.List<? extends T> list) Gets the first element of the list.
static <T> T	getLast(java.util.List<? extends T> list) Gets the last element of the list.
static boolean	isEmpty(java.util.Collection<?> collection) Returns true if the given collection is null or empty.
static boolean	isEmpty(java.lang.Iterable<?> iterable) Returns true if the given iterable is null or empty.
static <DataType> DataType	removeElement(java.lang.Iterable<DataType> iterable, int index) Removes and returns the indexed value into the Iterable.
static int	size(java.util.Collection<?> collection) Determines the size of the given collection, checking for null.
static int	size(java.lang.Iterable<?> iterable) Determines the size of the given iterable.
static java.lang.String	toStringDelimited(java.lang.Iterable<?> list, java.lang.String delimiter) Performs a toString on each element given iterable with a given delimiter between elements.

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

isEmpty

public static boolean isEmpty(java.util.Collection<?> collection)

Returns true if the given collection is null or empty.

Parameters:

collection - The collection to determine if it is null or empty.

Returns:

True if the given collection is null or empty.

isEmpty

public static boolean isEmpty(java.lang.Iterable<?> iterable)

Returns true if the given iterable is null or empty.

Parameters:

iterable - The iterable to determine if it is null or empty.

Returns:

True if the given iterable is null or empty.

asArrayList

public static <DataType> java.util.ArrayList<DataType> asArrayList(java.lang.Iterable<DataType> data)

Returns the Collection as an ArrayList. It first checks to see if data is already an ArrayList and returns the casted value. Otherwise, this method creates a new ArrayList from the data without copying each value.

Type Parameters:

DataType - Type of data in the Collection.

Parameters:

data - Collection to return as an ArrayList.

Returns:

ArrayList of the given Collection.

size

public static int size(java.util.Collection<?> collection)

Determines the size of the given collection, checking for null.

Parameters:

collection - The collection to get the size of.

Returns:

The size of the collection. If it is null, zero is returned.

size

public static int size(java.lang.Iterable<?> iterable)

Determines the size of the given iterable. If it is null, zero is returned. If it is a Collection, then the size method is used. Otherwise, the iterable is iterated over to get the size.

Parameters:

iterable - The iterable to determine the size of.

Returns:

The size of the given iterable.

getFirst

public static <T> T getFirst(java.lang.Iterable<? extends T> iterable)

Gets the first element from an iterable. If the iterable is null or empty, null is returned.

Type Parameters:

T - The type of element.

Parameters:

iterable - The iterable to get the first element from.

Returns:

The first element from the iterable, if one exists. Otherwise, null.

getFirst

public static <T> T getFirst(java.util.List<? extends T> list)

Gets the first element of the list. If the list is null or empty, null is returned.

Type Parameters:

T - The type of element in the list.

Parameters:

list - The list to get the first element from.

Returns:

The first element from the list, if one exists. Otherwise, null.

getLast

public static <T> T getLast(java.util.List<? extends T> list)

Gets the last element of the list. If the list is null or empty, null is returned.

Type Parameters:

T - The type of element in the list.

Parameters:

list - The list to get the last element from.

Returns:

The last element from the list, if one exists. Otherwise, null.

equals

public static <T> boolean equals(java.util.Collection<? extends T> data1,
                                 java.util.Collection<? extends T> data2)

Check if two collections return exactly the same objects in the same order. This means that both collections must return the same number of objects.

Type Parameters:

T -

Parameters:

data1 -

data2 -

Returns:

true if simultaneous iteration of data1 and data2 always returns objects for which Object.equals(java.lang.Object) is true; false otherwise

equals

public static <T> boolean equals(java.lang.Iterable<? extends T> data1,
                                 java.lang.Iterable<? extends T> data2)

Check if two iterables return exactly the same objects in the same order. This means that both iterables must return the same number of objects.

Type Parameters:

T -

Parameters:

data1 -

data2 -

Returns:

true if simultaneous iteration of data1 and data2 always returns objects for which Object.equals(java.lang.Object) is true; false otherwise

findKthLargest

@PublicationReference(author={"William H Press","Saul A. Teukolsky","William T. Vetterling","Brian P. Flannery"},
                      title="Numerical Recipes, Third Edition",
                      type=Book,
                      year=2007,
                      pages=1104,
                      notes="Loosely based on the selecti() function")
public static <ComparableType> int[] findKthLargest(int k,
                                                                                                                                                                                                                                                                                                                                                                                                                 java.util.ArrayList<? extends ComparableType> data,
                                                                                                                                                                                                                                                                                                                                                                                                                 java.util.Comparator<? super ComparableType> comparator)

Returns the set of indices of the data array such that data[return[0..k-1]] ≤ data[return[k]] ≤ data[return[k+1...N-1]]. This algorithm will partition the data set in O(N) time. This is faster than the typical sort and split time of O(N*log(N)). Note that the subsets data[return[0..k-1]] and data[return[k+1..N-1]] are themselves unsorted. Because of this, NRC calls "Selection is sorting's austere sister."

Type Parameters:

ComparableType - Type of data to compare to.

Parameters:

k - kth largest value to split upon.

data - Data to partition, left unchanged by this method.

comparator - Comparator used to determine if two values are greater than, less than, or equal to each other.

Returns:

Indices into data so that data[return[0..k-1]] ≤ data[return[k]] ≤ data[return[k+1...N-1]].

createSequentialPartitions

public static <DataType> java.util.ArrayList<java.util.List<? extends DataType>> createSequentialPartitions(java.lang.Iterable<? extends DataType> data,
                                                                                                            int numPartitions)

Creates a partition of the given data into "numPartition" roughly equal sets, preserving their pre-existing sequential ordering, with the nonzero remainder elements going into the final partition.

Type Parameters:

DataType - Type of data to partition.

Parameters:

data - Collection of data to partition

numPartitions - Number of partitions to create.

Returns:

List of Lists of size data.size()/numPartitions, with the remainder of data elements going into the final partition.

createSequentialPartitions

public static <DataType> java.util.ArrayList<java.util.List<? extends DataType>> createSequentialPartitions(java.util.List<? extends DataType> data,
                                                                                                            int numPartitions)

Creates a partition of the given data into "numPartition" roughly equal sets, preserving their pre-existing sequential ordering, with the nonzero remainder elements going into the final partition.

Type Parameters:

DataType - Type of data to partition.

Parameters:

data - Collection of data to partition

numPartitions - Number of partitions to create.

Returns:

List of Lists of size data.size()/numPartitions, with the remainder of data elements going into the final partition.

getElement

public static <DataType> DataType getElement(java.lang.Iterable<DataType> iterable,
                                             int index)

Returns the indexed value into the Iterable. It first checks to see if the Iterable is a List, and if so calls the get method. Otherwise, it walks the Iterable to get to the element.

Type Parameters:

DataType - The type of data.

Parameters:

iterable - The iterable to pull the value from.

index - The 0-based index to pull from the iterable.

Returns:

The value at the given spot in the iterable.

Throws:

java.lang.IndexOutOfBoundsException - If the index is less than zero or greater than or equal to the number of elements in the iterable.

removeElement

public static <DataType> DataType removeElement(java.lang.Iterable<DataType> iterable,
                                                int index)

Removes and returns the indexed value into the Iterable. It first checks to see if the Iterable is a List, and if so calls the remove method. Otherwise, it walks the Iterable to get to the element and remove it. This only works on Iterables that are Lists or whose Iterator implements the optional remove method.

Type Parameters:

DataType - The type of data.

Parameters:

iterable - The iterable to remove the value from.

index - The 0-based index to remove from the iterable.

Returns:

The value removed from the given index in the iterable.

Throws:

java.lang.IndexOutOfBoundsException - If the index is less than zero or greater than or equal to the number of elements in the iterable.

java.lang.UnsupportedOperationException - If the iterable does not support remove.

toStringDelimited

public static java.lang.String toStringDelimited(java.lang.Iterable<?> list,
                                                 java.lang.String delimiter)

Performs a toString on each element given iterable with a given delimiter between elements.

Parameters:

list - The list to call toString on each element for.

delimiter - The delimiter.

Returns:

A string with the toString on each element in the list called with a given delimiter between elements. If null is given, then "null" is returned. If an empty list is given, "" is returned.

createArrayList

public static <DataType> java.util.ArrayList<DataType> createArrayList(DataType first,
                                                                       DataType second)

Creates a new ArrayList from the given pair of values.

Type Parameters:

DataType - The data type.

Parameters:

first - The first value.

second - The second value.

Returns:

A new array list with the two elements in it.

createHashMapWithSize

public static <KeyType,ValueType> java.util.HashMap<KeyType,ValueType> createHashMapWithSize(int size)

Creates a new HashMap with the given expected size. It uses the default load factor (0.75) to estimate the proper number of elements for the data structure to avoid a rehash or resize when the given number of elements are added.

Type Parameters:

KeyType - The type for the key of the map.

ValueType - The type of the value in the map.

Parameters:

size - The size. Must be positive.

Returns:

A new hash map with the given expected size.

createLinkedHashMapWithSize

public static <KeyType,ValueType> java.util.LinkedHashMap<KeyType,ValueType> createLinkedHashMapWithSize(int size)

Creates a new LinkedHashMap with the given expected size. It uses the default load factor (0.75) to estimate the proper number of elements for the data structure to avoid a rehash or resize when the given number of elements are added.

Type Parameters:

KeyType - The type for the key of the map.

ValueType - The type of the value in the map.

Parameters:

size - The size. Must be positive.

Returns:

A new hash map with the given expected size.

createHashSetWithSize

public static <ValueType> java.util.HashSet<ValueType> createHashSetWithSize(int size)

Creates a new HashSet with the given expected size. It uses the default load factor (0.75) to estimate the proper number of elements for the data structure to avoid a rehash or resize when the given number of elements are added.

Type Parameters:

ValueType - The type of the value in the set.

Parameters:

size - The size. Must be positive.

Returns:

A new hash map with the given expected size.

createLinkedHashSetWithSize

public static <ValueType> java.util.LinkedHashSet<ValueType> createLinkedHashSetWithSize(int size)

Creates a new LinkedHashSet with the given expected size. It uses the default load factor (0.75) to estimate the proper number of elements for the data structure to avoid a rehash or resize when the given number of elements are added.

Type Parameters:

ValueType - The type of the value in the set.

Parameters:

size - The size. Must be positive.

Returns:

A new hash map with the given expected size.