org.plumelib.util

Class CollectionsPlume

java.lang.Object

org.plumelib.util.CollectionsPlume

public final class CollectionsPlume
extends java.lang.Object

Utility functions for Collections, ArrayList, Iterator, and Map.

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
static class	CollectionsPlume.EnumerationIterator<T> Converts an Enumeration into an Iterator.
static class	CollectionsPlume.FilteredIterator<T> An iterator that only returns elements that match the given Filter.
static class	CollectionsPlume.IteratorEnumeration<T> Converts an Iterator into an Enumeration.
static class	CollectionsPlume.MergedIterator<T> An Iterator that returns the elements in each of its argument Iterators, in turn.
static class	CollectionsPlume.MergedIterator2<T> An Iterator that returns first the elements returned by its first argument, then the elements returned by its second argument.
static class	CollectionsPlume.RemoveFirstAndLastIterator<T> Returns an iterator just like its argument, except that the first and last elements are removed.

Method Summary

Modifier and Type	Method and Description
static java.util.ArrayList<java.util.ArrayList<java.lang.Integer>>	createCombinations(int arity, int start, int cnt) Returns a list of lists of each combination (with repetition, but not permutations) of integers from start to cnt (inclusive) over arity dimensions.
static <T> java.util.List<java.util.List<T>>	createCombinations(int dims, int start, java.util.List<T> objs) Returns a list of lists of each combination (with repetition, but not permutations) of the specified objects starting at index start over dims dimensions, for dims > 0.
static boolean	deepEquals(@Nullable java.lang.Object o1, @Nullable java.lang.Object o2) Determines deep equality for the elements.
static @Nullable java.lang.Object	getFromSet(java.util.Set<?> set, java.lang.Object key) Return the object in this set that is equal to key.
static <K> @Nullable java.lang.Integer	incrementMap(java.util.Map<K,java.lang.Integer> m, K key) Increment the Integer which is indexed by key in the Map.
static <K> @Nullable java.lang.Integer	incrementMap(java.util.Map<K,java.lang.Integer> m, K key, int count) Increment the Integer which is indexed by key in the Map.
static <T> java.lang.Iterable<T>	iteratorToIterable(java.util.Iterator<T> source) Converts an Iterator to an Iterable.
static <T> java.util.ArrayList<T>	makeArrayList(java.util.Enumeration<T> e) Returns a vector containing the elements of the enumeration.
static <K,V> void	mapToString(java.lang.Appendable sb, java.util.Map<K,V> m, java.lang.String linePrefix) Write a multi-line representation of the map into the given Appendable (e.g., a StringBuilder).
static <K,V> java.lang.String	mapToString(java.util.Map<K,V> m) Returns a multi-line string representation of a map.
static <T> java.util.List<T>	randomElements(java.util.Iterator<T> itor, int numElts) Return a List containing numElts randomly chosen elements from the iterator, or all the elements of the iterator if there are fewer.
static <T> java.util.List<T>	randomElements(java.util.Iterator<T> itor, int numElts, java.util.Random random) Return a List containing numElts randomly chosen elements from the iterator, or all the elements of the iterator if there are fewer.
static <T> java.util.List<T>	removeDuplicates(java.util.List<T> l) Return a copy of the list with duplicates removed.
static <K extends java.lang.Comparable<? super K>,V> java.util.Collection<K>	sortedKeySet(java.util.Map<K,V> m) Returns a sorted version of m.keySet().
static <K,V> java.util.Collection<K>	sortedKeySet(java.util.Map<K,V> m, java.util.Comparator<K> comparator) Returns a sorted version of m.keySet().
static <T> java.util.List<T>	sortList(java.util.List<T> l, java.util.Comparator<? super T> c) Return the sorted version of the list.

Methods inherited from class java.lang.Object

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

Method Detail

sortList

public static <T> java.util.List<T> sortList(java.util.List<T> l,
                                             java.util.Comparator<? super T> c)

Return the sorted version of the list. Does not alter the list. Simply calls Collections.sort(List<T>, Comparator<? super T>).

Type Parameters:

T - type of elements of the list

Parameters:

l - a list to sort

c - a sorted version of the list

Returns:

a sorted version of the list

removeDuplicates

public static <T> java.util.List<T> removeDuplicates(java.util.List<T> l)

Return a copy of the list with duplicates removed. Retains the original order.

Type Parameters:

T - type of elements of the list

Parameters:

l - a list to remove duplicates from

Returns:

a copy of the list with duplicates removed

deepEquals

@Pure
public static boolean deepEquals(@Nullable java.lang.Object o1,
                                       @Nullable java.lang.Object o2)

Determines deep equality for the elements.

• If both are primitive arrays, uses java.util.Arrays.equals.
• If both are Object[], uses java.util.Arrays.deepEquals and does not recursively call this method.
• If both are lists, uses deepEquals recursively on each element.
• For other types, just uses equals() and does not recursively call this method.

Parameters:

o1 - first value to compare

o2 - second value to compare

Returns:

true iff o1 and o2 are deeply equal

makeArrayList

public static <T> java.util.ArrayList<T> makeArrayList(java.util.Enumeration<T> e)

Returns a vector containing the elements of the enumeration.

Type Parameters:

T - type of the enumeration and vector elements

Parameters:

e - an enumeration to convert to a ArrayList

Returns:

a vector containing the elements of the enumeration

createCombinations

public static <T> java.util.List<java.util.List<T>> createCombinations(int dims,
                                                                       int start,
                                                                       java.util.List<T> objs)

Returns a list of lists of each combination (with repetition, but not permutations) of the specified objects starting at index start over dims dimensions, for dims > 0.

For example, createCombinations(1, 0, {a, b, c}) returns a 3-element list of singleton lists:

    {a}, {b}, {c}
 

And createCombinations(2, 0, {a, b, c}) returns a 6-element list of 2-element lists:

    {a, a}, {a, b}, {a, c}
    {b, b}, {b, c},
    {c, c}
 

Type Parameters:

T - type of the input list elements, and type of the innermost output list elements

Parameters:

dims - number of dimensions: that is, size of each innermost list

start - initial index

objs - list of elements to create combinations of

Returns:

list of lists of length dims, each of which combines elements from objs

createCombinations

public static java.util.ArrayList<java.util.ArrayList<java.lang.Integer>> createCombinations(int arity,
                                                                                             int start,
                                                                                             int cnt)

Returns a list of lists of each combination (with repetition, but not permutations) of integers from start to cnt (inclusive) over arity dimensions.

For example, createCombinations(1, 0, 2) returns a 3-element list of singleton lists:

    {0}, {1}, {2}
 

And createCombinations(2, 10, 2) returns a 6-element list of 2-element lists:

    {10, 10}, {10, 11}, {10, 12}, {11, 11}, {11, 12}, {12, 12}
 

The length of the list is (cnt multichoose arity), which is ((cnt + arity - 1) choose arity).

Parameters:

arity - size of each innermost list

start - initial value

cnt - maximum element value

Returns:

list of lists of length arity, each of which combines integers from start to cnt

iteratorToIterable

public static <T> java.lang.Iterable<T> iteratorToIterable(java.util.Iterator<T> source)

Converts an Iterator to an Iterable. The resulting Iterable can be used to produce a single, working Iterator (the one that was passed in). Subsequent calls to its iterator() method will fail, because otherwise they would return the same Iterator instance, which may have been exhausted, or otherwise be in some indeterminate state. Calling iteratorToIterable twice on the same argument can have similar problems, so don't do that.

Type Parameters:

T - the element type

Parameters:

source - the Iterator to be converted to Iterable

Returns:

source, converted to Iterable

randomElements

public static <T> java.util.List<T> randomElements(java.util.Iterator<T> itor,
                                                   int numElts)

Return a List containing numElts randomly chosen elements from the iterator, or all the elements of the iterator if there are fewer. It examines every element of the iterator, but does not keep them all in memory.

Type Parameters:

T - type of the iterator elements

Parameters:

itor - elements to be randomly selected from

numElts - number of elements to select

Returns:

list of numElts elements from itor

randomElements

public static <T> java.util.List<T> randomElements(java.util.Iterator<T> itor,
                                                   int numElts,
                                                   java.util.Random random)

Return a List containing numElts randomly chosen elements from the iterator, or all the elements of the iterator if there are fewer. It examines every element of the iterator, but does not keep them all in memory.

Type Parameters:

T - type of the iterator elements

Parameters:

itor - elements to be randomly selected from

numElts - number of elements to select

random - the Random instance to use to make selections

Returns:

list of numElts elements from itor

incrementMap

public static <K> @Nullable java.lang.Integer incrementMap(java.util.Map<K,java.lang.Integer> m,
                                                           K key)

Increment the Integer which is indexed by key in the Map. Set the value to 1 if not currently mapped.

Type Parameters:

K - type of keys in the map

Parameters:

m - map from K to Integer

key - the key whose value will be incremented

Returns:

the old value, before it was incremented

Throws:

java.lang.Error - if the key is in the Map but maps to a non-Integer

incrementMap

public static <K> @Nullable java.lang.Integer incrementMap(java.util.Map<K,java.lang.Integer> m,
                                                           K key,
                                                           int count)

Increment the Integer which is indexed by key in the Map. Set the value to count if not currently mapped.

Type Parameters:

K - type of keys in the map

Parameters:

m - map from K to Integer

key - the key whose value will be incremented

count - how much to increment the value by

Returns:

the old value, before it was incremented

Throws:

java.lang.Error - if the key is in the Map but maps to a non-Integer

mapToString

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

Returns a multi-line string representation of a map.

Type Parameters:

K - type of map keys

V - type of map values

Parameters:

m - map to be converted to a string

Returns:

a multi-line string representation of m

mapToString

public static <K,V> void mapToString(java.lang.Appendable sb,
                                     java.util.Map<K,V> m,
                                     java.lang.String linePrefix)

Write a multi-line representation of the map into the given Appendable (e.g., a StringBuilder).

Type Parameters:

K - type of map keys

V - type of map values

Parameters:

sb - an Appendable (such as StringBuilder) to which to write a multi-line string representation of m

m - map to be converted to a string

linePrefix - prefix to write at the beginning of each line

sortedKeySet

public static <K extends java.lang.Comparable<? super K>,V> java.util.Collection<K> sortedKeySet(java.util.Map<K,V> m)

Returns a sorted version of m.keySet().

Type Parameters:

K - type of the map keys

V - type of the map values

Parameters:

m - a map whose keyset will be sorted

Returns:

a sorted version of m.keySet()

sortedKeySet

public static <K,V> java.util.Collection<K> sortedKeySet(java.util.Map<K,V> m,
                                                         java.util.Comparator<K> comparator)

Returns a sorted version of m.keySet().

Type Parameters:

K - type of the map keys

V - type of the map values

Parameters:

m - a map whose keyset will be sorted

comparator - the Comparator to use for sorting

Returns:

a sorted version of m.keySet()

getFromSet

public static @Nullable java.lang.Object getFromSet(java.util.Set<?> set,
                                                    java.lang.Object key)

Return the object in this set that is equal to key. The Set abstraction doesn't provide this; it only provides "contains". Returns null if the argument is null, or if it isn't in the set.

Parameters:

set - a set in which to look up the value

key - the value to look up in the set

Returns:

the object in this set that is equal to key, or null