public class Collections

  1. Object
  2. Collections
Collections contains static methods which operate on Collection classes.

Fields

public static final List EMPTY_LISTAn empty immutable instance of List.
public static final Set EMPTY_SETAn empty immutable instance of Set.
public static final Map EMPTY_MAPAn empty immutable instance of Map.

Methods

public static <T> int binarySearch(List<? extends Comparable<? super T>> list, T object)Performs a binary search for the specified element in the specified sorted list.
public static <T> int binarySearch(List<? extends T> list, T object, Comparator<? super T> comparator)Performs a binary search for the specified element in the specified sorted list using the specified comparator.
public static <T> void copy(List<? super T> destination, List<? extends T> source)Copies the elements from the source list to the destination list.
public static <T> Enumeration<T> enumeration(Collection<T> collection)Returns an Enumeration on the specified collection.
public static <T> void fill(List<? super T> list, T object)Fills the specified list with the specified element.
public static <T extends Comparable<? super T>> T max(Collection<? extends T> collection)Searches the specified collection for the maximum element.
public static <T> T max(Collection<? extends T> collection, Comparator<? super T> comparator)Searches the specified collection for the maximum element using the specified comparator.
public static <T extends Comparable<? super T>> T min(Collection<? extends T> collection)Searches the specified collection for the minimum element.
public static <T> T min(Collection<? extends T> collection, Comparator<? super T> comparator)Searches the specified collection for the minimum element using the specified comparator.
public static <T> List<T> nCopies(int length, T object)Returns a list containing the specified number of the specified element.
public static void reverse(List<?> list)Modifies the specified List by reversing the order of the elements.
public static <T> Comparator<T> reverseOrder()A comparator which reverses the natural order of the elements.
public static <T> Comparator<T> reverseOrder(Comparator<T> c)Returns a Comparator that reverses the order of the Comparator passed.
public static void shuffle(List<?> list)Moves every element of the list to a random new position in the list.
public static void shuffle(List<?> list, Random random)Moves every element of the list to a random new position in the list using the specified random number generator.
public static <E> Set<E> singleton(E object)Returns a set containing the specified element.
public static <E> List<E> singletonList(E object)Returns a list containing the specified element.
public static <K, V> Map<K, V> singletonMap(K key, V value)Returns a Map containing the specified key and value.
public static <T extends Comparable<? super T>> void sort(List<T> list)Sorts the specified list in ascending natural order.
public static <T> void sort(List<T> list, Comparator<? super T> comparator)Sorts the specified list using the specified comparator.
public static void swap(List<?> list, int index1, int index2)Swaps the elements of list list at indices index1 and index2.
public static <T> boolean replaceAll(List<T> list, T obj, T obj2)Replaces all occurrences of Object obj in list with newObj.
public static void rotate(List<?> lst, int dist)Rotates the elements in list by the distance dist
public static int indexOfSubList(List<?> list, List<?> sublist)Searches the list for sublist and returns the beginning index of the first occurrence.
public static int lastIndexOfSubList(List<?> list, List<?> sublist)Searches the list for sublist and returns the beginning index of the last occurrence.
public static <T> ArrayList<T> list(Enumeration<T> enumeration)Returns an ArrayList with all the elements in the enumeration.
public static <T> Collection<T> synchronizedCollection(Collection<T> collection)Returns a wrapper on the specified collection which synchronizes all access to the collection.
public static <T> List<T> synchronizedList(List<T> list)Returns a wrapper on the specified List which synchronizes all access to the List.
public static <K, V> Map<K, V> synchronizedMap(Map<K, V> map)Returns a wrapper on the specified map which synchronizes all access to the map.
public static <E> Set<E> synchronizedSet(Set<E> set)Returns a wrapper on the specified set which synchronizes all access to the set.
public static <K, V> SortedMap<K, V> synchronizedSortedMap(SortedMap<K, V> map)Returns a wrapper on the specified sorted map which synchronizes all access to the sorted map.
public static <E> SortedSet<E> synchronizedSortedSet(SortedSet<E> set)Returns a wrapper on the specified sorted set which synchronizes all access to the sorted set.
public static <E> Collection<E> unmodifiableCollection(Collection<? extends E> collection)Returns a wrapper on the specified collection which throws an UnsupportedOperationException whenever an attempt is made to modify the collection.
public static <E> List<E> unmodifiableList(List<? extends E> list)Returns a wrapper on the specified list which throws an UnsupportedOperationException whenever an attempt is made to modify the list.
public static <K, V> Map<K, V> unmodifiableMap(Map<? extends K, ? extends V> map)Returns a wrapper on the specified map which throws an UnsupportedOperationException whenever an attempt is made to modify the map.
public static <E> Set<E> unmodifiableSet(Set<? extends E> set)Returns a wrapper on the specified set which throws an UnsupportedOperationException whenever an attempt is made to modify the set.
public static <K, V> SortedMap<K, V> unmodifiableSortedMap(SortedMap<K, ? extends V> map)Returns a wrapper on the specified sorted map which throws an UnsupportedOperationException whenever an attempt is made to modify the sorted map.
public static <E> SortedSet<E> unmodifiableSortedSet(SortedSet<E> set)Returns a wrapper on the specified sorted set which throws an UnsupportedOperationException whenever an attempt is made to modify the sorted set.
public static int frequency(Collection<?> c, Object o)Returns the number of elements in the Collection that match the Object passed.
public static final <T> List<T> emptyList()Returns a type-safe empty, immutable List.
public static final <T> Set<T> emptySet()Returns a type-safe empty, immutable Set.
public static final <K, V> Map<K, V> emptyMap()Returns a type-safe empty, immutable Map.
public static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type)Returns a dynamically typesafe view of the specified collection.
public static <T> boolean addAll(Collection<? super T> c, T... a)Adds all the specified elements to the specified collection.
public static boolean disjoint(Collection<?> c1, Collection<?> c2)Returns whether the specified collections have no elements in common.
public static <E> Set<E> newSetFromMap(Map<E, Boolean> map)Answers a set backed by a map.
public static <T> Queue<T> asLifoQueue(Deque<T> deque)Answers a LIFO Queue as a view of a Deque.

Inherited methods

From Object

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

Field details

EMPTY_LIST

public static final List EMPTY_LIST
An empty immutable instance of List.

EMPTY_SET

public static final Set EMPTY_SET
An empty immutable instance of Set.

EMPTY_MAP

public static final Map EMPTY_MAP
An empty immutable instance of Map.

Method details

binarySearch

public static <T> int binarySearch(List<? extends Comparable<? super T>> list, T object)
Performs a binary search for the specified element in the specified sorted list. The list needs to be already sorted in natural sorting order. Searching in an unsorted array has an undefined result. It’s also undefined which element is found if there are multiple occurrences of the same element.

Parameters

list List<? extends Comparable<? super T>>
the sorted list to search.
object T
the element to find.

Returns

the non-negative index of the element, or a negative index which is the -index - 1 where the element would be inserted

Throws

ClassCastException
if an element in the List or the search element does not implement Comparable, or cannot be compared to each other.

binarySearch

public static <T> int binarySearch(List<? extends T> list, T object, Comparator<? super T> comparator)
Performs a binary search for the specified element in the specified sorted list using the specified comparator. The list needs to be already sorted according to the comparator passed. Searching in an unsorted array has an undefined result. It’s also undefined which element is found if there are multiple occurrences of the same element.

Parameters

list List<? extends T>
the sorted List to search.
object T
the element to find.
comparator Comparator<? super T>
the comparator. If the comparator is null then the search uses the objects’ natural ordering.

Returns

the non-negative index of the element, or a negative index which is the -index - 1 where the element would be inserted.

Throws

ClassCastException
when an element in the list and the searched element cannot be compared to each other using the comparator.

copy

public static <T> void copy(List<? super T> destination, List<? extends T> source)
Copies the elements from the source list to the destination list. At the end both lists will have the same objects at the same index. If the destination array is larger than the source list, the elements in the destination list with index >= source.size() will be unchanged.

Parameters

destination List<? super T>
the list whose elements are set from the source list.
source List<? extends T>
the list with the elements to be copied into the destination.

Throws

IndexOutOfBoundsException
when the destination list is smaller than the source list.
UnsupportedOperationException
when replacing an element in the destination list is not supported.

enumeration

public static <T> Enumeration<T> enumeration(Collection<T> collection)
Returns an Enumeration on the specified collection.

Parameters

collection Collection<T>
the collection to enumerate.

Returns

an Enumeration.

fill

public static <T> void fill(List<? super T> list, T object)
Fills the specified list with the specified element.

Parameters

list List<? super T>
the list to fill.
object T
the element to fill the list with.

Throws

UnsupportedOperationException
when replacing an element in the List is not supported.

max

public static <T extends Comparable<? super T>> T max(Collection<? extends T> collection)
Searches the specified collection for the maximum element.

Parameters

collection Collection<? extends T>
the collection to search.

Returns

the maximum element in the Collection.

Throws

ClassCastException
when an element in the collection does not implement Comparable or elements cannot be compared to each other.

max

public static <T> T max(Collection<? extends T> collection, Comparator<? super T> comparator)
Searches the specified collection for the maximum element using the specified comparator.

Parameters

collection Collection<? extends T>
the collection to search.
comparator Comparator<? super T>
the comparator.

Returns

the maximum element in the Collection.

Throws

ClassCastException
when elements in the collection cannot be compared to each other using the Comparator.

min

public static <T extends Comparable<? super T>> T min(Collection<? extends T> collection)
Searches the specified collection for the minimum element.

Parameters

collection Collection<? extends T>
the collection to search.

Returns

the minimum element in the collection.

Throws

ClassCastException
when an element in the collection does not implement Comparable or elements cannot be compared to each other.

min

public static <T> T min(Collection<? extends T> collection, Comparator<? super T> comparator)
Searches the specified collection for the minimum element using the specified comparator.

Parameters

collection Collection<? extends T>
the collection to search.
comparator Comparator<? super T>
the comparator.

Returns

the minimum element in the collection.

Throws

ClassCastException
when elements in the collection cannot be compared to each other using the Comparator.

nCopies

public static <T> List<T> nCopies(int length, T object)
Returns a list containing the specified number of the specified element. The list cannot be modified. The list is serializable.

Parameters

length int
the size of the returned list.
object T
the element to be added length times to a list.

Returns

a list containing length copies of the element.

Throws

IllegalArgumentException
when length < 0.

reverse

public static void reverse(List<?> list)
Modifies the specified List by reversing the order of the elements.

Parameters

list List<?>
the list to reverse.

Throws

UnsupportedOperationException
when replacing an element in the List is not supported.

reverseOrder

public static <T> Comparator<T> reverseOrder()
A comparator which reverses the natural order of the elements. The Comparator that’s returned is Serializable.

Returns

a Comparator instance.

See also

reverseOrder

public static <T> Comparator<T> reverseOrder(Comparator<T> c)

Returns a Comparator that reverses the order of the Comparator passed. If the Comparator passed is null, then this method is equivalent to #reverseOrder().

The Comparator that’s returned is Serializable if the Comparator passed is serializable or null.

Parameters

c Comparator<T>
the Comparator to reverse or null.

Returns

a Comparator instance.

See also

shuffle

public static void shuffle(List<?> list)
Moves every element of the list to a random new position in the list.

Parameters

list List<?>
the List to shuffle.

Throws

UnsupportedOperationException
when replacing an element in the List is not supported.

shuffle

public static void shuffle(List<?> list, Random random)
Moves every element of the list to a random new position in the list using the specified random number generator.

Parameters

list List<?>
the list to shuffle.
random Random
the random number generator.

Throws

UnsupportedOperationException
when replacing an element in the list is not supported.

singleton

public static <E> Set<E> singleton(E object)
Returns a set containing the specified element. The set cannot be modified. The set is serializable.

Parameters

object E
the element.

Returns

a set containing the element.

singletonList

public static <E> List<E> singletonList(E object)
Returns a list containing the specified element. The list cannot be modified. The list is serializable.

Parameters

object E
the element.

Returns

a list containing the element.

singletonMap

public static <K, V> Map<K, V> singletonMap(K key, V value)
Returns a Map containing the specified key and value. The map cannot be modified. The map is serializable.

Parameters

key K
the key.
value V
the value.

Returns

a Map containing the key and value.

sort

public static <T extends Comparable<? super T>> void sort(List<T> list)
Sorts the specified list in ascending natural order. The algorithm is stable which means equal elements don’t get reordered.

Parameters

list List<T>
the list to be sorted.

Throws

ClassCastException
when an element in the List does not implement Comparable or elements cannot be compared to each other.

sort

public static <T> void sort(List<T> list, Comparator<? super T> comparator)
Sorts the specified list using the specified comparator. The algorithm is stable which means equal elements don’t get reordered.

Parameters

list List<T>
the list to be sorted.
comparator Comparator<? super T>
the comparator.

Throws

ClassCastException
when elements in the list cannot be compared to each other using the comparator.

swap

public static void swap(List<?> list, int index1, int index2)
Swaps the elements of list list at indices index1 and index2.

Parameters

list List<?>
the list to manipulate.
index1 int
position of the first element to swap with the element in index2.
index2 int
position of the other element.

Throws

IndexOutOfBoundsException
if index1 or index2 is out of range of this list.

replaceAll

public static <T> boolean replaceAll(List<T> list, T obj, T obj2)
Replaces all occurrences of Object obj in list with newObj. If the obj is null, then all occurrences of null are replaced with newObj.

Parameters

list List<T>
the list to modify.
obj T
the object to find and replace occurrences of.
obj2 T
the object to replace all occurrences of obj in list.

Returns

true, if at least one occurrence of obj has been found in list.

Throws

UnsupportedOperationException
if the list does not support setting elements.

rotate

public static void rotate(List<?> lst, int dist)

Rotates the elements in list by the distance dist

e.g. for a given list with elements [1, 2, 3, 4, 5, 6, 7, 8, 9, 0], calling rotate(list, 3) or rotate(list, -7) would modify the list to look like this: [8, 9, 0, 1, 2, 3, 4, 5, 6, 7]

Parameters

lst List<?>
the list whose elements are to be rotated.
dist int
is the distance the list is rotated. This can be any valid integer. Negative values rotate the list backwards.

indexOfSubList

public static int indexOfSubList(List<?> list, List<?> sublist)

Searches the list for sublist and returns the beginning index of the first occurrence.

-1 is returned if the sublist does not exist in list.

Parameters

list List<?>
the List to search sublist in.
sublist List<?>
the List to search in list.

Returns

the beginning index of the first occurrence of sublist in list, or -1.

lastIndexOfSubList

public static int lastIndexOfSubList(List<?> list, List<?> sublist)

Searches the list for sublist and returns the beginning index of the last occurrence.

-1 is returned if the sublist does not exist in list.

Parameters

list List<?>
the list to search sublist in.
sublist List<?>
the list to search in list.

Returns

the beginning index of the last occurrence of sublist in list, or -1.

list

public static <T> ArrayList<T> list(Enumeration<T> enumeration)
Returns an ArrayList with all the elements in the enumeration. The elements in the returned ArrayList are in the same order as in the enumeration.

Parameters

enumeration Enumeration<T>
the source Enumeration.

Returns

an ArrayList from enumeration.

synchronizedCollection

public static <T> Collection<T> synchronizedCollection(Collection<T> collection)
Returns a wrapper on the specified collection which synchronizes all access to the collection.

Parameters

collection Collection<T>
the Collection to wrap in a synchronized collection.

Returns

a synchronized Collection.

synchronizedList

public static <T> List<T> synchronizedList(List<T> list)
Returns a wrapper on the specified List which synchronizes all access to the List.

Parameters

list List<T>
the List to wrap in a synchronized list.

Returns

a synchronized List.

synchronizedMap

public static <K, V> Map<K, V> synchronizedMap(Map<K, V> map)
Returns a wrapper on the specified map which synchronizes all access to the map.

Parameters

map Map<K, V>
the map to wrap in a synchronized map.

Returns

a synchronized Map.

synchronizedSet

public static <E> Set<E> synchronizedSet(Set<E> set)
Returns a wrapper on the specified set which synchronizes all access to the set.

Parameters

set Set<E>
the set to wrap in a synchronized set.

Returns

a synchronized set.

synchronizedSortedMap

public static <K, V> SortedMap<K, V> synchronizedSortedMap(SortedMap<K, V> map)
Returns a wrapper on the specified sorted map which synchronizes all access to the sorted map.

Parameters

map SortedMap<K, V>
the sorted map to wrap in a synchronized sorted map.

Returns

a synchronized sorted map.

synchronizedSortedSet

public static <E> SortedSet<E> synchronizedSortedSet(SortedSet<E> set)
Returns a wrapper on the specified sorted set which synchronizes all access to the sorted set.

Parameters

set SortedSet<E>
the sorted set to wrap in a synchronized sorted set.

Returns

a synchronized sorted set.

unmodifiableCollection

public static <E> Collection<E> unmodifiableCollection(Collection<? extends E> collection)
Returns a wrapper on the specified collection which throws an UnsupportedOperationException whenever an attempt is made to modify the collection.

Parameters

collection Collection<? extends E>
the collection to wrap in an unmodifiable collection.

Returns

an unmodifiable collection.

unmodifiableList

public static <E> List<E> unmodifiableList(List<? extends E> list)
Returns a wrapper on the specified list which throws an UnsupportedOperationException whenever an attempt is made to modify the list.

Parameters

list List<? extends E>
the list to wrap in an unmodifiable list.

Returns

an unmodifiable List.

unmodifiableMap

public static <K, V> Map<K, V> unmodifiableMap(Map<? extends K, ? extends V> map)
Returns a wrapper on the specified map which throws an UnsupportedOperationException whenever an attempt is made to modify the map.

Parameters

map Map<? extends K, ? extends V>
the map to wrap in an unmodifiable map.

Returns

a unmodifiable map.

unmodifiableSet

public static <E> Set<E> unmodifiableSet(Set<? extends E> set)
Returns a wrapper on the specified set which throws an UnsupportedOperationException whenever an attempt is made to modify the set.

Parameters

set Set<? extends E>
the set to wrap in an unmodifiable set.

Returns

a unmodifiable set

unmodifiableSortedMap

public static <K, V> SortedMap<K, V> unmodifiableSortedMap(SortedMap<K, ? extends V> map)
Returns a wrapper on the specified sorted map which throws an UnsupportedOperationException whenever an attempt is made to modify the sorted map.

Parameters

map SortedMap<K, ? extends V>
the sorted map to wrap in an unmodifiable sorted map.

Returns

a unmodifiable sorted map

unmodifiableSortedSet

public static <E> SortedSet<E> unmodifiableSortedSet(SortedSet<E> set)
Returns a wrapper on the specified sorted set which throws an UnsupportedOperationException whenever an attempt is made to modify the sorted set.

Parameters

set SortedSet<E>
the sorted set to wrap in an unmodifiable sorted set.

Returns

a unmodifiable sorted set.

frequency

public static int frequency(Collection<?> c, Object o)
Returns the number of elements in the Collection that match the Object passed. If the Object is null, then the number of null elements is returned.

Parameters

c Collection<?>
the Collection to search.
o Object
the Object to search for.

Returns

the number of matching elements.

Throws

NullPointerException
if the Collection parameter is null.

emptyList

public static final <T> List<T> emptyList()
Returns a type-safe empty, immutable List.

Returns

an empty List.

See also

emptySet

public static final <T> Set<T> emptySet()
Returns a type-safe empty, immutable Set.

Returns

an empty Set.

See also

emptyMap

public static final <K, V> Map<K, V> emptyMap()
Returns a type-safe empty, immutable Map.

Returns

an empty Map.

See also

checkedCollection

public static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type)
Returns a dynamically typesafe view of the specified collection. Trying to insert an element of the wrong type into this collection throws a ClassCastException. At creation time the types in c are not checked for correct type.

Parameters

c Collection<E>
the collection to be wrapped in a typesafe collection.
type Class<E>
the type of the elements permitted to insert.

Returns

a typesafe collection.

addAll

public static <T> boolean addAll(Collection<? super T> c, T... a)
Adds all the specified elements to the specified collection.

Parameters

c Collection<? super T>
the collection the elements are to be inserted into.
a T...
the elements to insert.

Returns

true if the collection changed during insertion.

Throws

UnsupportedOperationException
when the method is not supported.
NullPointerException
when c or a is null, or a contains one or more null elements and c doesn’t support null elements.
IllegalArgumentException
if at least one of the elements can’t be inserted into the collection.

disjoint

public static boolean disjoint(Collection<?> c1, Collection<?> c2)
Returns whether the specified collections have no elements in common.

Parameters

c1 Collection<?>
the first collection.
c2 Collection<?>
the second collection.

Returns

true if the collections have no elements in common, false otherwise.

Throws

NullPointerException
if one of the collections is null.

newSetFromMap

public static <E> Set<E> newSetFromMap(Map<E, Boolean> map)

Answers a set backed by a map. And the map must be empty when this method is called.

Type parameter E: type of elements in set

Parameters

map Map<E, Boolean>
the backing map

Returns

the set from the map

Throws

IllegalArgumentException
if the map is not empty

asLifoQueue

public static <T> Queue<T> asLifoQueue(Deque<T> deque)

Answers a LIFO Queue as a view of a Deque. Methods in the returned Queue need to be re-written to implement the LIFO feature.

Type parameter T: type of elements

Parameters

deque Deque<T>
the Deque

Returns

the LIFO Queue