edu.stanford.nlp.util
Class CollectionUtils

java.lang.Object
  extended by edu.stanford.nlp.util.CollectionUtils

public class CollectionUtils
extends java.lang.Object

Collection of useful static methods for working with Collections. Includes methods to increment counts in maps and cast list/map elements to common types.

Author:
Joseph Smarr (jsmarr@stanford.edu)

Method Summary
static
<T> void
addAll(java.util.Collection<T> collection, java.lang.Iterable<? extends T> items)
          Add all the items from an iterable to a collection.
static java.util.List<java.lang.Double> asList(double[] a)
           
static java.util.List<java.lang.Integer> asList(int[] a)
           
static java.util.List<java.lang.Object> asList(java.lang.Object... args)
          Returns a new List containing the specified objects.
static
<T> java.util.Set<T>
asSet(T[] o)
          Returns a new Set containing all the objects in the specified array.
static
<T extends java.lang.Comparable<T>>
int
compareLists(java.util.List<T> list1, java.util.List<T> list2)
           
static
<T> boolean
containsObject(java.util.Collection<T> c, T o)
          Checks whether a Collection contains a specified Object.
static
<T> java.util.Collection<T>
diff(java.util.Collection<T> list1, java.util.Collection<T> list2)
          all objects in list1 that are not in list2
static
<T> int
getIndex(java.util.List<T> l, T o)
          Returns the index of the first occurrence in the list of the specified object, using object identity (==) not equality as the criterion for object presence.
static
<T> int
getIndex(java.util.List<T> l, T o, int fromIndex)
          Returns the index of the first occurrence after the startIndex (exclusive) in the list of the specified object, using object equals function.
static
<C extends java.lang.Comparable<C>>
java.util.Comparator<java.util.List<C>>
getListComparator()
           
static
<K,V> java.util.Map<K,V>
getMapFromString(java.lang.String s, java.lang.Class<K> keyClass, java.lang.Class<V> valueClass, MapFactory<K,V> mapFactory)
           
static
<T> java.util.List<java.util.List<T>>
getNGrams(java.util.List<T> items, int minSize, int maxSize)
          Get all sub-lists of the given list of the given sizes.
static
<T> java.util.List<java.util.List<T>>
getPrefixesAndSuffixes(java.util.List<T> items, int minSize, int maxSize, T paddingSymbol, boolean includePrefixes, boolean includeSuffixes)
          Get all prefix/suffix combinations from a list.
static
<T> java.util.Set<T>
intersection(java.util.Set<T> set1, java.util.Set<T> set2)
           
static
<T> boolean
isSubList(java.util.List<T> l1, java.util.List<? super T> l)
          Returns true iff l1 is a sublist of l (i.e., every member of l1 is in l, and for every e1 < e2 in l1, there is an e1 < e2 occurrence in l).
static
<T> void
loadCollection(java.io.File file, java.lang.Class<T> itemClass, java.util.Collection<T> collection)
          Adds the items from the file to the collection.
static
<T> java.util.Collection<T>
loadCollection(java.io.File file, java.lang.Class<T> c, CollectionFactory<T> cf)
           
static
<T> void
loadCollection(java.lang.String fileName, java.lang.Class<T> itemClass, java.util.Collection<T> collection)
          Adds the items from the file to the collection.
static
<T> java.util.Collection<T>
loadCollection(java.lang.String filename, java.lang.Class<T> c, CollectionFactory<T> cf)
           
static
<T> java.util.List<T>
makeList(T e)
          Returns a new List containing the given object.
static
<T> java.util.List<T>
makeList(T e1, T e2)
          Returns a new List containing the given objects.
static
<T> java.util.List<T>
makeList(T e1, T e2, T e3)
          Returns a new List containing the given objects.
static
<T> boolean
removeObject(java.util.List<T> l, T o)
          Removes the first occurrence in the list of the specified object, using object identity (==) not equality as the criterion for object presence.
static
<E> E
sample(java.util.List<E> l, java.util.Random r)
           
static
<E> java.util.Collection<E>
sampleWithoutReplacement(java.util.Collection<E> c, int n)
          Samples without replacement from a collection.
static
<E> java.util.Collection<E>
sampleWithoutReplacement(java.util.Collection<E> c, int n, java.util.Random r)
          Samples without replacement from a collection, using your own Random number generator.
static
<E> java.util.Collection<E>
sampleWithReplacement(java.util.Collection<E> c, int n)
          Samples with replacement from a collection
static
<E> java.util.Collection<E>
sampleWithReplacement(java.util.Collection<E> c, int n, java.util.Random r)
          Samples with replacement from a collection, using your own Random number generator
static
<T extends java.lang.Comparable<T>>
java.util.List<T>
sorted(java.lang.Iterable<T> items)
          Return the items of an Iterable as a sorted list.
static
<T> java.util.List<T>
toList(java.lang.Iterable<T> items)
          Create a list out of the items in the Iterable.
static
<T> java.util.Set<T>
toSet(java.lang.Iterable<T> items)
          Create a set out of the items in the Iterable.
static
<K,V> java.lang.String
toVerticalString(java.util.Map<K,V> m)
           
static
<T> java.util.Collection<T>
union(java.util.Collection<T> set1, java.util.Collection<T> set2)
           
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Method Detail

asList

public static java.util.List<java.lang.Integer> asList(int[] a)

asList

public static java.util.List<java.lang.Double> asList(double[] a)

asList

public static java.util.List<java.lang.Object> asList(java.lang.Object... args)
Returns a new List containing the specified objects.


makeList

public static <T> java.util.List<T> makeList(T e)
Returns a new List containing the given object.


makeList

public static <T> java.util.List<T> makeList(T e1,
                                             T e2)
Returns a new List containing the given objects.


makeList

public static <T> java.util.List<T> makeList(T e1,
                                             T e2,
                                             T e3)
Returns a new List containing the given objects.


asSet

public static <T> java.util.Set<T> asSet(T[] o)
Returns a new Set containing all the objects in the specified array.


intersection

public static <T> java.util.Set<T> intersection(java.util.Set<T> set1,
                                                java.util.Set<T> set2)

union

public static <T> java.util.Collection<T> union(java.util.Collection<T> set1,
                                                java.util.Collection<T> set2)

diff

public static <T> java.util.Collection<T> diff(java.util.Collection<T> list1,
                                               java.util.Collection<T> list2)
all objects in list1 that are not in list2

Type Parameters:
T -
Parameters:
list1 - First collection
list2 - Second collection
Returns:
The collection difference list1 - list2

loadCollection

public static <T> java.util.Collection<T> loadCollection(java.lang.String filename,
                                                         java.lang.Class<T> c,
                                                         CollectionFactory<T> cf)
                                              throws java.lang.Exception
Parameters:
filename - the path to the file to load the List from
c - the Class to instantiate each member of the List. Must have a String constructor.
Throws:
java.lang.Exception

loadCollection

public static <T> java.util.Collection<T> loadCollection(java.io.File file,
                                                         java.lang.Class<T> c,
                                                         CollectionFactory<T> cf)
                                              throws java.lang.Exception
Parameters:
file - the file to load the List from
c - the Class to instantiate each member of the List. Must have a String constructor.
Throws:
java.lang.Exception

loadCollection

public static <T> void loadCollection(java.lang.String fileName,
                                      java.lang.Class<T> itemClass,
                                      java.util.Collection<T> collection)
                           throws java.lang.NoSuchMethodException,
                                  java.lang.InstantiationException,
                                  java.lang.IllegalAccessException,
                                  java.lang.reflect.InvocationTargetException,
                                  java.io.IOException
Adds the items from the file to the collection.

Type Parameters:
T - The type of the items.
Parameters:
fileName - The name of the file from which items should be loaded.
itemClass - The class of the items (must have a constructor that accepts a String).
collection - The collection to which items should be added.
Throws:
java.lang.NoSuchMethodException
java.lang.InstantiationException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.io.IOException

loadCollection

public static <T> void loadCollection(java.io.File file,
                                      java.lang.Class<T> itemClass,
                                      java.util.Collection<T> collection)
                           throws java.lang.NoSuchMethodException,
                                  java.lang.InstantiationException,
                                  java.lang.IllegalAccessException,
                                  java.lang.reflect.InvocationTargetException,
                                  java.io.IOException
Adds the items from the file to the collection.

Type Parameters:
T - The type of the items.
Parameters:
file - The file from which items should be loaded.
itemClass - The class of the items (must have a constructor that accepts a String).
collection - The collection to which items should be added.
Throws:
java.lang.NoSuchMethodException
java.lang.InstantiationException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.io.IOException

getMapFromString

public static <K,V> java.util.Map<K,V> getMapFromString(java.lang.String s,
                                                        java.lang.Class<K> keyClass,
                                                        java.lang.Class<V> valueClass,
                                                        MapFactory<K,V> mapFactory)
                                           throws java.lang.ClassNotFoundException,
                                                  java.lang.NoSuchMethodException,
                                                  java.lang.IllegalAccessException,
                                                  java.lang.reflect.InvocationTargetException,
                                                  java.lang.InstantiationException
Throws:
java.lang.ClassNotFoundException
java.lang.NoSuchMethodException
java.lang.IllegalAccessException
java.lang.reflect.InvocationTargetException
java.lang.InstantiationException

containsObject

public static <T> boolean containsObject(java.util.Collection<T> c,
                                         T o)
Checks whether a Collection contains a specified Object. Object equality (==), rather than .equals(), is used.


removeObject

public static <T> boolean removeObject(java.util.List<T> l,
                                       T o)
Removes the first occurrence in the list of the specified object, using object identity (==) not equality as the criterion for object presence. If this list does not contain the element, it is unchanged.

Parameters:
l - The List from which to remove the object
o - The object to be removed.
Returns:
Whether or not the List was changed.

getIndex

public static <T> int getIndex(java.util.List<T> l,
                               T o)
Returns the index of the first occurrence in the list of the specified object, using object identity (==) not equality as the criterion for object presence. If this list does not contain the element, return -1.

Parameters:
l - The List to find the object in.
o - The sought-after object.
Returns:
Whether or not the List was changed.

getIndex

public static <T> int getIndex(java.util.List<T> l,
                               T o,
                               int fromIndex)
Returns the index of the first occurrence after the startIndex (exclusive) in the list of the specified object, using object equals function. If this list does not contain the element, return -1.

Parameters:
l - The List to find the object in.
o - The sought-after object.
fromIndex - The start index
Returns:
Whether or not the List was changed.

sampleWithoutReplacement

public static <E> java.util.Collection<E> sampleWithoutReplacement(java.util.Collection<E> c,
                                                                   int n)
Samples without replacement from a collection.

Parameters:
c - The collection to be sampled from
n - The number of samples to take
Returns:
a new collection with the sample

sampleWithoutReplacement

public static <E> java.util.Collection<E> sampleWithoutReplacement(java.util.Collection<E> c,
                                                                   int n,
                                                                   java.util.Random r)
Samples without replacement from a collection, using your own Random number generator.

Parameters:
c - The collection to be sampled from
n - The number of samples to take
r - the random number generator
Returns:
a new collection with the sample

sample

public static <E> E sample(java.util.List<E> l,
                           java.util.Random r)

sampleWithReplacement

public static <E> java.util.Collection<E> sampleWithReplacement(java.util.Collection<E> c,
                                                                int n)
Samples with replacement from a collection

Parameters:
c - The collection to be sampled from
n - The number of samples to take
Returns:
a new collection with the sample

sampleWithReplacement

public static <E> java.util.Collection<E> sampleWithReplacement(java.util.Collection<E> c,
                                                                int n,
                                                                java.util.Random r)
Samples with replacement from a collection, using your own Random number generator

Parameters:
c - The collection to be sampled from
n - The number of samples to take
r - the random number generator
Returns:
a new collection with the sample

isSubList

public static <T> boolean isSubList(java.util.List<T> l1,
                                    java.util.List<? super T> l)
Returns true iff l1 is a sublist of l (i.e., every member of l1 is in l, and for every e1 < e2 in l1, there is an e1 < e2 occurrence in l).


toVerticalString

public static <K,V> java.lang.String toVerticalString(java.util.Map<K,V> m)

compareLists

public static <T extends java.lang.Comparable<T>> int compareLists(java.util.List<T> list1,
                                                                   java.util.List<T> list2)

getListComparator

public static <C extends java.lang.Comparable<C>> java.util.Comparator<java.util.List<C>> getListComparator()

sorted

public static <T extends java.lang.Comparable<T>> java.util.List<T> sorted(java.lang.Iterable<T> items)
Return the items of an Iterable as a sorted list.

Type Parameters:
T - The type of items in the Iterable.
Parameters:
items - The collection to be sorted.
Returns:
A list containing the same items as the Iterable, but sorted.

toList

public static <T> java.util.List<T> toList(java.lang.Iterable<T> items)
Create a list out of the items in the Iterable.

Type Parameters:
T - The type of items in the Iterable.
Parameters:
items - The items to be made into a list.
Returns:
A list consisting of the items of the Iterable, in the same order.

toSet

public static <T> java.util.Set<T> toSet(java.lang.Iterable<T> items)
Create a set out of the items in the Iterable.

Type Parameters:
T - The type of items in the Iterable.
Parameters:
items - The items to be made into a set.
Returns:
A set consisting of the items from the Iterable.

addAll

public static <T> void addAll(java.util.Collection<T> collection,
                              java.lang.Iterable<? extends T> items)
Add all the items from an iterable to a collection.

Type Parameters:
T - The type of items in the iterable and the collection
Parameters:
collection - The collection to which the items should be added.
items - The items to add to the collection.

getNGrams

public static <T> java.util.List<java.util.List<T>> getNGrams(java.util.List<T> items,
                                                              int minSize,
                                                              int maxSize)
Get all sub-lists of the given list of the given sizes. For example:
 List<String> items = Arrays.asList("a", "b", "c", "d");
 System.out.println(CollectionUtils.getNGrams(items, 1, 2));
 
would print out:
 [[a], [a, b], [b], [b, c], [c], [c, d], [d]]
 

Type Parameters:
T - The type of items contained in the list.
Parameters:
items - The list of items.
minSize - The minimum size of an ngram.
maxSize - The maximum size of an ngram.
Returns:
All sub-lists of the given sizes.

getPrefixesAndSuffixes

public static <T> java.util.List<java.util.List<T>> getPrefixesAndSuffixes(java.util.List<T> items,
                                                                           int minSize,
                                                                           int maxSize,
                                                                           T paddingSymbol,
                                                                           boolean includePrefixes,
                                                                           boolean includeSuffixes)
Get all prefix/suffix combinations from a list. It can extract just prefixes, just suffixes, or prefixes and suffixes of the same length. For example:
 List<String> items = Arrays.asList("a", "b", "c", "d");
 System.out.println(CollectionUtils.getPrefixesAndSuffixes(items, 1, 2, null, true, true));
 
would print out:
 [[d], [a], [a, d], [d, c], [a, b], [a, b, c, d]]
 
and
 List<String> items2 = Arrays.asList("a");
 System.out.println(CollectionUtils.getPrefixesAndSuffixes(items2, 1, 2, null, true, true));
 
would print:
 [[a], [a], [a, a], [a, null], [a, null], [a, null, a, null]]
 

Type Parameters:
T - The type of items contained in the list.
Parameters:
items - The list of items.
minSize - The minimum length of a prefix/suffix span (should be at least 1)
maxSize - The maximum length of a prefix/suffix span
paddingSymbol - Symbol to be included if we run out of bounds (e.g. if items has size 3 and we try to extract a span of length 4).
includePrefixes - whether to extract prefixes
includeSuffixes - whether to extract suffixes
Returns:
All prefix/suffix combinations of the given sizes.


Stanford NLP Group