Package eu.bandm.tools.util.java

Class Collections

java.lang.Object

eu.bandm.tools.util.java.Collections

public abstract class Collections
extends Object

Library of constants and operations for working with the Java collection framework.

See Also:

• Collection

Nested Class Summary

Nested Classes

Modifier and Type	Class	Description
static class	Collections.MapBuilder<K,V>	Helper class for building maps incrementally.

Method Summary

Modifier and Type	Method	Description
static <A, B, C extends B> Map<A,B>	castValues(Class<? extends C> cls, Map<A,C> things)	Returns a view on a given collection that modifies the type of each element by casting.
static <A> Collection<A>	concat(Collection<? extends A> some, Collection<? extends A> other)	Returns a collection view that contains all elements of two given collections.
static <A, B> Map<B,A>	converse(Map<A,B> map)	Returns a map that contains all pairs of a given map with key and value swapped.
static <A> Set<A>	elements(Collection<? extends A> things)	Returns a new set of the elements of a given collection, without duplicates.
static <A> SortedSet<A>	elements(Collection<? extends A> things, Comparator<? super A> comparator)	Returns a new set of the elements of a given collection, without duplicates according to a given ordering.
static <A, B> SortedMap<A,B>	emptySortedMap()	Returns an unmodifiable empty sorted map.
static <A> SortedSet<A>	emptySortedSet()	Returns an unmodifiable empty sorted set.
static <K, V> Map.Entry<K,V>	entry(K key, V value)	Returns a new unmodifiable map entry with the given key and value.
static <A> Collection<A>	flatten(Collection<? extends Collection<? extends A>> colls)	Returns a view on a collection of collections that contains all of their elements.
static <D> D	infimum(SortedSet<D> set, D value)	Return the greatest member of a given nonempty set which is less or equal the given upper bound.
static <D> D	infimumKey(SortedMap<D,?> map, D key)	Return the greatest key in the domain of a given nonempty map which is less or equal the upper bound.
static <A> Set<A>	intersection(Collection<? extends A> some, Collection<? extends A> other)	Returns a new set that contains the elements commonly contained in both given collections.
static <A> A	lastOf(List<A> list)	Return the last element in a nonempty list.
static List<Integer>	literalIntList(int... values)	Returns an unmodifiable list of the given elements.
static <A> List<A>	literalList(A... values)	Returns an unmodifiable list of the given elements.
static <A, B> Collections.MapBuilder<A,B>	literalMap(A a, B b)	Starts the incremental creation of a map with one entry.
static <A> Set<A>	literalSet(A... values)	Returns an unmodifiable set of the given elements.
static <A, B, C> Map.Entry<A,C>	map(Function<? super B,? extends C> fun, Map.Entry<A,B> e)	Returns a new map entry where the value of a given entry is transformed with a function.
static <A> Set<A>	setminus(Collection<? extends A> some, Collection<? extends A> other)	Returns a new set that contains the elements contained in one given collection but not the other.
static <A extends Comparable<? super A>, B> SortedMap<A,B>	singletonSortedMap(A key, B value)	Returns an unmodifiable sorted map with one entry.
static <A, B> SortedMap<A,B>	singletonSortedMap(Comparator<? super A> comparator, A key, B value)	Returns an unmodifiable sorted map with one entry and a given ordering.
static <A extends Comparable<? super A>> SortedSet<A>	singletonSortedSet(A elem)	Returns an unmodifiable sorted set with one element.
static <A> SortedSet<A>	singletonSortedSet(Comparator<? super A> comparator, A elem)	Returns an unmodifiable sorted set with one element and a given ordering.
static <T> T	some(Collection<T> set)	Finds an arbitrary element contained in a collection.
static <T> T	the(Collection<T> set)	Finds the single element contained in a collection.
static <A, B> Map<A,B>	toGraph(Function<? super A,? extends B> fun, Set<? extends A> dom)	Returns a map with a given key set and values computed by a function.
static <A, B, C> Map<B,C>	toSpan(Function<? super A,? extends B> left, Function<? super A,? extends C> right, Collection<? extends A> gen)	Creates a map by generating entries from generating elements using two functions.
static <A, B, C> Map<B,C>	toSpan(Function<? super A,? extends B> left, Function<? super A,? extends C> right, BiFunction<? super C,? super C,? extends C> merge, Collection<? extends A> gen)	Creates a map by generating entries from generating elements using two functions.
static <A> Set<A>	union(Collection<? extends A> some, Collection<? extends A> other)	Returns a new set that contains the elements contained in either of the given collections.
static <K, V> Map.Entry<K,V>	unmodifiableEntry(Map.Entry<? extends K,? extends V> entry)	Returns an unmodifiable view on a given map entry.

Methods inherited from class java.lang.Object

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

Method Details

the

public static <T> T the(Collection<T> set)

Finds the single element contained in a collection.

Type Parameters:

T - the type of elements

Parameters:

set - a collection of elements of size 1

Returns:

the single element contained in the collection

Throws:

IllegalArgumentException - if set contains none, or more than one element

See Also:

• Collection.size()

some

public static <T> T some(Collection<T> set)

Finds an arbitrary element contained in a collection.

Type Parameters:

T - the type of elements

Parameters:

set - a nonempty collection of elements

Returns:

an arbitrary element contained in the collection

Throws:

IllegalArgumentException - if set contains no element

See Also:

• Collection.isEmpty()

literalSet

@SafeVarargs
public static <A> Set<A> literalSet(A... values)

Returns an unmodifiable set of the given elements.

Use this method where the behavior of the alternative Set.of(Object[]) is not appropriate.

Type Parameters:

A - the type of elements

Parameters:

values - an array of elements

Returns:

a set containing exactly the given elements

See Also:

• Collections.emptySet()
• Collections.singleton(T)

literalList

@SafeVarargs
public static <A> List<A> literalList(A... values)

Returns an unmodifiable list of the given elements.

Use this method where the behavior of the alternative List.of(Object[]) is not appropriate.

Type Parameters:

A - the type of elements

Parameters:

values - an array of elements

Returns:

a list containing exactly the given elements in the same order

See Also:

• Collections.emptyList()
• Collections.singletonList(T)

literalIntList

@SafeVarargs
public static List<Integer> literalIntList(int... values)

Returns an unmodifiable list of the given elements.

Parameters:

values - an array of elements

Returns:

a list containing exactly the given elements (boxed) in the same order

map

public static <A,
B,
C> Map.Entry<A,C> map(Function<? super B,? extends C> fun,
 Map.Entry<A,B> e)

Returns a new map entry where the value of a given entry is transformed with a function.

Type Parameters:

A - the type of the key

B - the type of the given value

C - the type of the transformed value

Parameters:

fun - the transformer function

e - a map entry

Returns:

a map entry that has the same key as e and a value resulting from applying fun to the value of e

toSpan

public static <A,
B,
C> Map<B,C> toSpan(Function<? super A,? extends B> left,
 Function<? super A,? extends C> right,
 Collection<? extends A> gen)

Creates a map by generating entries from generating elements using two functions.

Type Parameters:

A - the type of generating elemens

B - the type of keys

C - the type of values

Parameters:

left - the key-generating function

right - the value-generating function

gen - the generating elements

Returns:

an unmodifiable map that contains, for each generating element, the computed entry

Throws:

IllegalArgumentException - if two generating elements result in the same key but different values

toSpan

public static <A,
B,
C> Map<B,C> toSpan(Function<? super A,? extends B> left,
 Function<? super A,? extends C> right,
 BiFunction<? super C,? super C,? extends C> merge,
 Collection<? extends A> gen)

Creates a map by generating entries from generating elements using two functions.

Type Parameters:

A - the type of generating elemens

B - the type of keys

C - the type of values

Parameters:

left - the key-generating function

right - the value-generating function

merge - an operation to reconcile values if two generating elements result in the same key

gen - the generating elements

Returns:

an unmodifiable map that contains, for each generating element, the computed entry

toGraph

public static <A,
B> Map<A,B> toGraph(Function<? super A,? extends B> fun,
 Set<? extends A> dom)

Returns a map with a given key set and values computed by a function.

Type Parameters:

A - the type of keys

B - the type of values

Parameters:

fun - a function to compute values from keys

dom - the key set

Returns:

a new map that maps all keys in dom to values computed with fun

concat

public static <A> Collection<A> concat(Collection<? extends A> some,
 Collection<? extends A> other)

Returns a collection view that contains all elements of two given collections.

Changes to the underlying collections are reflected in the resulting collection. By contrast, the resulting collection cannot be modified on its own.

Type Parameters:

A - the element type

Parameters:

some - one collection

other - another collection

Returns:

an unmodifiable collection that always contains the current elements of both given collections

Throws:

NullPointerException - if some or other is null

union

public static <A> Set<A> union(Collection<? extends A> some,
 Collection<? extends A> other)

Returns a new set that contains the elements contained in either of the given collections.

Changes to the underlying sets are not reflected by the result.

Type Parameters:

A - the type of elements

Parameters:

some - a collection of elements

other - another collection of elements

Returns:

a new set that contains those elements that are contained in either some or other

setminus

public static <A> Set<A> setminus(Collection<? extends A> some,
 Collection<? extends A> other)

Returns a new set that contains the elements contained in one given collection but not the other.

Changes to the underlying sets are not reflected by the result.

Type Parameters:

A - the type of elements

Parameters:

some - a collection of elements

other - another collection of elements

Returns:

a new set that contains those elements that are contained in some but not in other

intersection

public static <A> Set<A> intersection(Collection<? extends A> some,
 Collection<? extends A> other)

Returns a new set that contains the elements commonly contained in both given collections.

Changes to the underlying sets are not reflected by the result.

Type Parameters:

A - the type of elements

Parameters:

some - a collection of elements

other - another collection of elements

Returns:

a new set that contains those elements that are contained in both some and other

flatten

public static <A> Collection<A> flatten(Collection<? extends Collection<? extends A>> colls)

Returns a view on a collection of collections that contains all of their elements.

Changes to the underlying collection(s) are reflected by the resulting view.

Type Parameters:

A - the type of elements

Parameters:

colls - a collection of collections of elements

Returns:

an unmodifiable collection that contains all elements that are contained in a collection contained in colls

unmodifiableEntry

public static <K,
V> Map.Entry<K,V> unmodifiableEntry(Map.Entry<? extends K,? extends V> entry)

Returns an unmodifiable view on a given map entry.

Changes to the underlying entry are reflected by the resulting view.

Type Parameters:

K - the key type

V - the value type

Parameters:

entry - the entry

Returns:

an unmodifiable map entry with the same key and value as entry

entry

public static <K,
V> Map.Entry<K,V> entry(K key,
 V value)

Returns a new unmodifiable map entry with the given key and value.

Type Parameters:

K - the key type

V - the value type

Parameters:

key - the key

value - the value

Returns:

an unmodifiable map entry with the given key and value

See Also:

• AbstractMap.SimpleImmutableEntry

elements

public static <A> Set<A> elements(Collection<? extends A> things)

Returns a new set of the elements of a given collection, without duplicates.

Duplicates are element for which Object.equals(java.lang.Object) returns true.

Type Parameters:

A - the type of elements

Parameters:

things - a collection of elements

Returns:

a new set containing all elements of things, but no duplicates

elements

public static <A> SortedSet<A> elements(Collection<? extends A> things,
 Comparator<? super A> comparator)

Returns a new set of the elements of a given collection, without duplicates according to a given ordering.

Duplicates are element for which comparator.compare returns 0.

Type Parameters:

A - the type of elements

Parameters:

things - a collection of elements

comparator - a comparison function that specifies the ordering

Returns:

a new set containing all elements of things, but no duplicates

Throws:

IllegalArgumentException - if some elements cannot be compared

castValues

public static <A,
B,
C extends B> Map<A,B> castValues(Class<? extends C> cls,
 Map<A,C> things)

Returns a view on a given collection that modifies the type of each element by casting.

Changes to the underlying collection are reflected by the resulting view.

Type Parameters:

A - the type of keys

B - the actual type of elements

C - the apparent type of elements

Parameters:

cls - the class to cast to

things - the map to transform

Returns:

an unmodifiable map that has, for each current value of things, a cast reference of type cls, for the same key

literalMap

public static <A,
B> Collections.MapBuilder<A,B> literalMap(A a,
 B b)

Starts the incremental creation of a map with one entry.

Type Parameters:

A - the type of keys

B - the type of values

Parameters:

a - the key of the initial entry

b - the value of the initial entry

Returns:

a builder for a map that already contains the given entry

See Also:

• Collections.MapBuilder.close()

emptySortedSet

public static <A> SortedSet<A> emptySortedSet()

Returns an unmodifiable empty sorted set.

Type Parameters:

A - the type of elements

Returns:

an unmodifiable empty sorted set

See Also:

• Collections.emptySet()

singletonSortedSet

public static <A extends Comparable<? super A>>
SortedSet<A> singletonSortedSet(A elem)

Returns an unmodifiable sorted set with one element.

Type Parameters:

A - the type of elements

Parameters:

elem - the element

Returns:

an unmodifiable sorted set with the given element

See Also:

• Collections.singleton(T)

singletonSortedSet

public static <A> SortedSet<A> singletonSortedSet(Comparator<? super A> comparator,
 A elem)

Returns an unmodifiable sorted set with one element and a given ordering.

Type Parameters:

A - the type of elements

Parameters:

comparator - a comparison function that specifies the ordering

elem - the element

Returns:

an unmodifiable sorted set with the given element

See Also:

• Collections.singleton(T)

emptySortedMap

public static <A,
B> SortedMap<A,B> emptySortedMap()

Returns an unmodifiable empty sorted map.

Type Parameters:

A - the type of keys

B - the type of values

Returns:

an unmodifiable empty sorted map

See Also:

• Collections.emptyMap()

singletonSortedMap

public static <A extends Comparable<? super A>,
B>
SortedMap<A,B> singletonSortedMap(A key,
 B value)

Returns an unmodifiable sorted map with one entry.

Type Parameters:

A - the type of keys

B - the type of values

Parameters:

key - the key of the entry

value - the value of the entry

Returns:

an unmodifiable sorted map with the given entry

See Also:

• Collections.singletonMap(K, V)

singletonSortedMap

public static <A,
B> SortedMap<A,B> singletonSortedMap(Comparator<? super A> comparator,
 A key,
 B value)

Returns an unmodifiable sorted map with one entry and a given ordering.

Type Parameters:

A - the type of keys

B - the type of values

Parameters:

comparator - a comparison function specifying the ordering

key - the key of the entry

value - the value of the entry

Returns:

an unmodifiable sorted map with the given entry

See Also:

• Collections.singletonMap(K, V)

infimum

public static <D> D infimum(SortedSet<D> set,
 D value)

Return the greatest member of a given nonempty set which is less or equal the given upper bound.

Type Parameters:

D - the type of elements

Parameters:

set - a nonempty sorted set

value - the upper bound

Returns:

the greatest element of set which is less or equal to value

Throws:

NoSuchElementException - if the given set is empty

infimumKey

public static <D> D infimumKey(SortedMap<D,?> map,
 D key)

Return the greatest key in the domain of a given nonempty map which is less or equal the upper bound.

This method is not easily emulated by infimum(SortedSet, Object), because for some reason SortedMap.keySet() does not return a SortedSet.

Type Parameters:

D - the type of keys

Parameters:

map - a nonempty sorted map

key - the upper bound

Returns:

the greatest key of map which is less or equal to key

Throws:

NoSuchElementException - if the given map is empty

converse

public static <A,
B> Map<B,A> converse(Map<A,B> map)

Returns a map that contains all pairs of a given map with key and value swapped.

The values of the given map must be unique. null keys and/or values are not supported.

This operation copies map entries; later changes to the given map are not reflected.

Type Parameters:

A - the key type of the given map; the value type of the resulting map

B - the value type of the given map; the key type of the resulting map

Parameters:

map - a map

Returns:

an unmodifiable map of all values of the given map to their corresponding keys

Throws:

UnsupportedOperationException - if a value is associated with more than one key

lastOf

public static <A> A lastOf(List<A> list)

Return the last element in a nonempty list.

Type Parameters:

A - the type of elements

Parameters:

list - a nonempty list

Returns:

the last element of the list

Throws:

IllegalArgumentException - if the list is empty