java.util

Class Collections

public class Collections extends Object

Utility class consisting of static methods that operate on, or return Collections. Contains methods to sort, search, reverse, fill and shuffle Collections, methods to facilitate interoperability with legacy APIs that are unaware of collections, a method to return a list which consists of multiple copies of one element, and methods which "wrap" collections to give them extra properties, such as thread-safety and unmodifiability.

All methods which take a collection throw a {@link NullPointerException} if that collection is null. Algorithms which can change a collection may, but are not required, to throw the {@link UnsupportedOperationException} that the underlying collection would throw during an attempt at modification. For example, Collections.singleton("").addAll(Collections.EMPTY_SET) does not throw a exception, even though addAll is an unsupported operation on a singleton; the reason for this is that addAll did not attempt to modify the set.

Since: 1.2

See Also: Collection Set List Map Arrays

UNKNOWN: updated to 1.5

Field Summary
static List	EMPTY_LIST An immutable, serializable, empty List, which implements RandomAccess.
static Map	EMPTY_MAP An immutable, serializable, empty Map.
static Set	EMPTY_SET An immutable, serializable, empty Set.

Method Summary
static <T> boolean	addAll(Collection<? super T> c, T... a) Adds all the specified elements to the given collection, in a similar way to the `addAll` method of the `Collection`.
static <T> Queue<T>	asLifoQueue(Deque<T> deque) Returns a view of a {@link Deque} as a stack or LIFO (Last-In-First-Out) {@link Queue}.
static <T> int	binarySearch(List<? extends Comparable<? super T>> l, T key) Perform a binary search of a List for a key, using the natural ordering of the elements.
static <T> int	binarySearch(List<? extends T> l, T key, Comparator<? super T> c) Perform a binary search of a List for a key, using a supplied Comparator.
static <E> Collection<E>	checkedCollection(Collection<E> c, Class<E> type) Returns a dynamically typesafe view of the given collection, where any modification is first checked to ensure that the type of the new data is appropriate.
static <E> List<E>	checkedList(List<E> l, Class<E> type) Returns a dynamically typesafe view of the given list, where any modification is first checked to ensure that the type of the new data is appropriate.
static <K,V> Map<K,V>	checkedMap(Map<K,V> m, Class<K> keyType, Class<V> valueType) Returns a dynamically typesafe view of the given map, where any modification is first checked to ensure that the type of the new data is appropriate.
static <E> Set<E>	checkedSet(Set<E> s, Class<E> type) Returns a dynamically typesafe view of the given set, where any modification is first checked to ensure that the type of the new data is appropriate.
static <K,V> SortedMap<K,V>	checkedSortedMap(SortedMap<K,V> m, Class<K> keyType, Class<V> valueType) Returns a dynamically typesafe view of the given sorted map, where any modification is first checked to ensure that the type of the new data is appropriate.
static <E> SortedSet<E>	checkedSortedSet(SortedSet<E> s, Class<E> type) Returns a dynamically typesafe view of the given sorted set, where any modification is first checked to ensure that the type of the new data is appropriate.
static <T> void	copy(List<? super T> dest, List<? extends T> source) Copy one list to another.
static boolean	disjoint(Collection<?> c1, Collection<?> c2) Returns true if the two specified collections have no elements in common.
static <T> List<T>	emptyList() Returns an immutable, serializable parameterized empty list.
static <K,V> Map<K,V>	emptyMap() Returns an immutable, serializable parameterized empty map.
static <T> Set<T>	emptySet() Returns an immutable, serializable parameterized empty set.
static <T> Enumeration<T>	enumeration(Collection<T> c) Returns an Enumeration over a collection.
static <T> void	fill(List<? super T> l, T val) Replace every element of a list with a given value.
static int	frequency(Collection<?> c, Object o) Returns the frequency of the specified object within the supplied collection.
static int	indexOfSubList(List<?> source, List<?> target) Returns the starting index where the specified sublist first occurs in a larger list, or -1 if there is no matching position.
static int	lastIndexOfSubList(List<?> source, List<?> target) Returns the starting index where the specified sublist last occurs in a larger list, or -1 if there is no matching position.
static <T> ArrayList<T>	list(Enumeration<T> e) Returns an ArrayList holding the elements visited by a given Enumeration.
static <T extends Object&Comparable<? super T>> T	max(Collection<? extends T> c) Find the maximum element in a Collection, according to the natural ordering of the elements.
static <T> T	max(Collection<? extends T> c, Comparator<? super T> order) Find the maximum element in a Collection, according to a specified Comparator.
static <T extends Object&Comparable<? super T>> T	min(Collection<? extends T> c) Find the minimum element in a Collection, according to the natural ordering of the elements.
static <T> T	min(Collection<? extends T> c, Comparator<? super T> order) Find the minimum element in a Collection, according to a specified Comparator.
static <T> List<T>	nCopies(int n, T o) Creates an immutable list consisting of the same object repeated n times.
static <E> Set<E>	newSetFromMap(Map<E,Boolean> map) Returns a set backed by the supplied map.
static <T> boolean	replaceAll(List<T> list, T oldval, T newval) Replace all instances of one object with another in the specified list.
static void	reverse(List<?> l) Reverse a given list.
static <T> Comparator<T>	reverseOrder(Comparator<T> c) Get a comparator that implements the reverse of the ordering specified by the given Comparator.
static <T> Comparator<T>	reverseOrder() Get a comparator that implements the reverse of natural ordering.
static void	rotate(List<?> list, int distance) Rotate the elements in a list by a specified distance.
static void	shuffle(List<?> l) Shuffle a list according to a default source of randomness.
static void	shuffle(List<?> l, Random r) Shuffle a list according to a given source of randomness.
static <T> Set<T>	singleton(T o) Obtain an immutable Set consisting of a single element.
static <T> List<T>	singletonList(T o) Obtain an immutable List consisting of a single element.
static <K,V> Map<K,V>	singletonMap(K key, V value) Obtain an immutable Map consisting of a single key-value pair.
static <T extends Comparable<? super T>> void	sort(List<T> l) Sort a list according to the natural ordering of its elements.
static <T> void	sort(List<T> l, Comparator<? super T> c) Sort a list according to a specified Comparator.
static void	swap(List<?> l, int i, int j) Swaps the elements at the specified positions within the list.
static <T> Collection<T>	synchronizedCollection(Collection<T> c) Returns a synchronized (thread-safe) collection wrapper backed by the given collection.
static <T> List<T>	synchronizedList(List<T> l) Returns a synchronized (thread-safe) list wrapper backed by the given list.
static <K,V> Map<K,V>	synchronizedMap(Map<K,V> m) Returns a synchronized (thread-safe) map wrapper backed by the given map.
static <T> Set<T>	synchronizedSet(Set<T> s) Returns a synchronized (thread-safe) set wrapper backed by the given set.
static <K,V> SortedMap<K,V>	synchronizedSortedMap(SortedMap<K,V> m) Returns a synchronized (thread-safe) sorted map wrapper backed by the given map.
static <T> SortedSet<T>	synchronizedSortedSet(SortedSet<T> s) Returns a synchronized (thread-safe) sorted set wrapper backed by the given set.
static <T> Collection<T>	unmodifiableCollection(Collection<? extends T> c) Returns an unmodifiable view of the given collection.
static <T> List<T>	unmodifiableList(List<? extends T> l) Returns an unmodifiable view of the given list.
static <K,V> Map<K,V>	unmodifiableMap(Map<? extends K,? extends V> m) Returns an unmodifiable view of the given map.
static <T> Set<T>	unmodifiableSet(Set<? extends T> s) Returns an unmodifiable view of the given set.
static <K,V> SortedMap<K,V>	unmodifiableSortedMap(SortedMap<K,? extends V> m) Returns an unmodifiable view of the given sorted map.
static <T> SortedSet<T>	unmodifiableSortedSet(SortedSet<T> s) Returns an unmodifiable view of the given sorted set.

Field Detail

EMPTY_LIST

public static final List EMPTY_LIST

An immutable, serializable, empty List, which implements RandomAccess.

See Also: Serializable RandomAccess

EMPTY_MAP

public static final Map EMPTY_MAP

An immutable, serializable, empty Map.

See Also: Serializable

EMPTY_SET

public static final Set EMPTY_SET

An immutable, serializable, empty Set.

See Also: Serializable

Method Detail

addAll

public static <T> boolean addAll(Collection<? super T> c, T... a)

Adds all the specified elements to the given collection, in a similar way to the addAll method of the Collection. However, this is a variable argument method which allows the new elements to be specified individually or in array form, as opposed to the list required by the collection's addAll method. This has benefits in both simplicity (multiple elements can be added without having to be wrapped inside a grouping structure) and efficiency (as a redundant list doesn't have to be created to add an individual set of elements or an array).

Parameters: c the collection to which the elements should be added. a the elements to be added to the collection.

Returns: true if the collection changed its contents as a result.

Throws: UnsupportedOperationException if the collection does not support addition. NullPointerException if one or more elements in a are null, and the collection does not allow null elements. This exception is also thrown if either c or a are null. IllegalArgumentException if the collection won't allow an element to be added for some other reason.

Since: 1.5

asLifoQueue

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

Returns a view of a {@link Deque} as a stack or LIFO (Last-In-First-Out) {@link Queue}. Each call to the LIFO queue corresponds to one equivalent method call to the underlying deque, with the exception of {@link Collection#addAll(Collection)}, which is emulated by a series of {@link Deque#push(E)} calls.

Parameters: deque the deque to convert to a LIFO queue.

Returns: a LIFO queue.

Since: 1.6

binarySearch

public static <T> int binarySearch(List<? extends Comparable<? super T>> l, T key)

Perform a binary search of a List for a key, using the natural ordering of the elements. The list must be sorted (as by the sort() method) - if it is not, the behavior of this method is undefined, and may be an infinite loop. Further, the key must be comparable with every item in the list. If the list contains the key more than once, any one of them may be found.

This algorithm behaves in log(n) time for {@link RandomAccess} lists, and uses a linear search with O(n) link traversals and log(n) comparisons with {@link AbstractSequentialList} lists. Note: although the specification allows for an infinite loop if the list is unsorted, it will not happen in this (Classpath) implementation.

Parameters: l the list to search (must be sorted) key the value to search for

Returns: the index at which the key was found, or -n-1 if it was not found, where n is the index of the first value higher than key or a.length if there is no such value

Throws: ClassCastException if key could not be compared with one of the elements of l NullPointerException if a null element has compareTo called

binarySearch

public static <T> int binarySearch(List<? extends T> l, T key, Comparator<? super T> c)

Perform a binary search of a List for a key, using a supplied Comparator. The list must be sorted (as by the sort() method with the same Comparator) - if it is not, the behavior of this method is undefined, and may be an infinite loop. Further, the key must be comparable with every item in the list. If the list contains the key more than once, any one of them may be found. If the comparator is null, the elements' natural ordering is used.

Parameters: l the list to search (must be sorted) key the value to search for c the comparator by which the list is sorted

Returns: the index at which the key was found, or -n-1 if it was not found, where n is the index of the first value higher than key or a.length if there is no such value

Throws: ClassCastException if key could not be compared with one of the elements of l NullPointerException if a null element is compared with natural ordering (only possible when c is null)

checkedCollection

public static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type)

Returns a dynamically typesafe view of the given collection, where any modification is first checked to ensure that the type of the new data is appropriate. Although the addition of generics and parametrically-typed collections prevents an incorrect type of element being added to a collection at compile-time, via static type checking, this can be overridden by casting. In contrast, wrapping the collection within a dynamically-typesafe wrapper, using this and associated methods, guarantees that the collection will only contain elements of an appropriate type (provided it only contains such at the type of wrapping, and all subsequent access is via the wrapper). This can be useful for debugging the cause of a ClassCastException caused by erroneous casting, or for protecting collections from corruption by external libraries.

Since the collection might be a List or a Set, and those have incompatible equals and hashCode requirements, this relies on Object's implementation rather than passing those calls on to the wrapped collection. The returned Collection implements Serializable, but can only be serialized if the collection it wraps is likewise Serializable.

Parameters: c the collection to wrap in a dynamically typesafe wrapper type the type of elements the collection should hold.

Returns: a dynamically typesafe view of the collection.

Since: 1.5

See Also: Serializable

checkedList

public static <E> List<E> checkedList(List<E> l, Class<E> type)

Returns a dynamically typesafe view of the given list, where any modification is first checked to ensure that the type of the new data is appropriate. Although the addition of generics and parametrically-typed collections prevents an incorrect type of element being added to a collection at compile-time, via static type checking, this can be overridden by casting. In contrast, wrapping the collection within a dynamically-typesafe wrapper, using this and associated methods, guarantees that the collection will only contain elements of an appropriate type (provided it only contains such at the type of wrapping, and all subsequent access is via the wrapper). This can be useful for debugging the cause of a ClassCastException caused by erroneous casting, or for protecting collections from corruption by external libraries.

The returned List implements Serializable, but can only be serialized if the list it wraps is likewise Serializable. In addition, if the wrapped list implements RandomAccess, this does too.

Parameters: l the list to wrap type the type of the elements within the checked list.

Returns: a dynamically typesafe view of the list

See Also: Serializable RandomAccess

checkedMap

public static <K,V> Map<K,V> checkedMap(Map<K,V> m, Class<K> keyType, Class<V> valueType)

Returns a dynamically typesafe view of the given map, where any modification is first checked to ensure that the type of the new data is appropriate. Although the addition of generics and parametrically-typed collections prevents an incorrect type of element being added to a collection at compile-time, via static type checking, this can be overridden by casting. In contrast, wrapping the collection within a dynamically-typesafe wrapper, using this and associated methods, guarantees that the collection will only contain elements of an appropriate type (provided it only contains such at the type of wrapping, and all subsequent access is via the wrapper). This can be useful for debugging the cause of a ClassCastException caused by erroneous casting, or for protecting collections from corruption by external libraries.

The returned Map implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.

Parameters: m the map to wrap keyType the dynamic type of the map's keys. valueType the dynamic type of the map's values.

Returns: a dynamically typesafe view of the map

See Also: Serializable

checkedSet

public static <E> Set<E> checkedSet(Set<E> s, Class<E> type)

Returns a dynamically typesafe view of the given set, where any modification is first checked to ensure that the type of the new data is appropriate. Although the addition of generics and parametrically-typed collections prevents an incorrect type of element being added to a collection at compile-time, via static type checking, this can be overridden by casting. In contrast, wrapping the collection within a dynamically-typesafe wrapper, using this and associated methods, guarantees that the collection will only contain elements of an appropriate type (provided it only contains such at the type of wrapping, and all subsequent access is via the wrapper). This can be useful for debugging the cause of a ClassCastException caused by erroneous casting, or for protecting collections from corruption by external libraries.

The returned Set implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.

Parameters: s the set to wrap. type the type of the elements within the checked list.

Returns: a dynamically typesafe view of the set

See Also: Serializable

checkedSortedMap

public static <K,V> SortedMap<K,V> checkedSortedMap(SortedMap<K,V> m, Class<K> keyType, Class<V> valueType)

Returns a dynamically typesafe view of the given sorted map, where any modification is first checked to ensure that the type of the new data is appropriate. Although the addition of generics and parametrically-typed collections prevents an incorrect type of element being added to a collection at compile-time, via static type checking, this can be overridden by casting. In contrast, wrapping the collection within a dynamically-typesafe wrapper, using this and associated methods, guarantees that the collection will only contain elements of an appropriate type (provided it only contains such at the type of wrapping, and all subsequent access is via the wrapper). This can be useful for debugging the cause of a ClassCastException caused by erroneous casting, or for protecting collections from corruption by external libraries.

The returned SortedMap implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.

Parameters: m the map to wrap. keyType the dynamic type of the map's keys. valueType the dynamic type of the map's values.

Returns: a dynamically typesafe view of the map

See Also: Serializable

checkedSortedSet

public static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s, Class<E> type)

Returns a dynamically typesafe view of the given sorted set, where any modification is first checked to ensure that the type of the new data is appropriate. Although the addition of generics and parametrically-typed collections prevents an incorrect type of element being added to a collection at compile-time, via static type checking, this can be overridden by casting. In contrast, wrapping the collection within a dynamically-typesafe wrapper, using this and associated methods, guarantees that the collection will only contain elements of an appropriate type (provided it only contains such at the type of wrapping, and all subsequent access is via the wrapper). This can be useful for debugging the cause of a ClassCastException caused by erroneous casting, or for protecting collections from corruption by external libraries.

The returned SortedSet implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.

Parameters: s the set to wrap. type the type of the set's elements.

Returns: a dynamically typesafe view of the set

See Also: Serializable

copy

public static <T> void copy(List<? super T> dest, List<? extends T> source)

Copy one list to another. If the destination list is longer than the source list, the remaining elements are unaffected. This method runs in linear time.

Parameters: dest the destination list source the source list

Throws: IndexOutOfBoundsException if the destination list is shorter than the source list (the destination will be unmodified) UnsupportedOperationException if dest.listIterator() does not support the set operation

disjoint

public static boolean disjoint(Collection<?> c1, Collection<?> c2)

Returns true if the two specified collections have no elements in common. This method may give unusual results if one or both collections use a non-standard equality test. In the trivial case of comparing a collection with itself, this method returns true if, and only if, the collection is empty.

Parameters: c1 the first collection to compare. c2 the second collection to compare.

Returns: true if the collections are disjoint.

Throws: NullPointerException if either collection is null.

Since: 1.5

emptyList

public static final <T> List<T> emptyList()

Returns an immutable, serializable parameterized empty list. Unlike the constant EMPTY_LIST, the list returned by this method is type-safe.

Returns: an empty parameterized list.

Since: 1.5

emptyMap

public static final <K,V> Map<K,V> emptyMap()

Returns an immutable, serializable parameterized empty map. Unlike the constant EMPTY_MAP, the map returned by this method is type-safe.

Returns: an empty parameterized map.

Since: 1.5

emptySet

public static final <T> Set<T> emptySet()

Returns an immutable, serializable parameterized empty set. Unlike the constant EMPTY_SET, the set returned by this method is type-safe.

Returns: an empty parameterized set.

Since: 1.5

enumeration

public static <T> Enumeration<T> enumeration(Collection<T> c)

Returns an Enumeration over a collection. This allows interoperability with legacy APIs that require an Enumeration as input.

Parameters: c the Collection to iterate over

Returns: an Enumeration backed by an Iterator over c

fill

public static <T> void fill(List<? super T> l, T val)

Replace every element of a list with a given value. This method runs in linear time.

Parameters: l the list to fill. val the object to vill the list with.

Throws: UnsupportedOperationException if l.listIterator() does not support the set operation.

frequency

public static int frequency(Collection<?> c, Object o)

Returns the frequency of the specified object within the supplied collection. The frequency represents the number of occurrences of elements within the collection which return true when compared with the object using the equals method.

Parameters: c the collection to scan for occurrences of the object. o the object to locate occurrances of within the collection.

Throws: NullPointerException if the collection is null.

Since: 1.5

indexOfSubList

public static int indexOfSubList(List<?> source, List<?> target)

Returns the starting index where the specified sublist first occurs in a larger list, or -1 if there is no matching position. If target.size() > source.size(), this returns -1, otherwise this implementation uses brute force, checking for source.sublist(i, i + target.size()).equals(target) for all possible i.

Parameters: source the list to search target the sublist to search for

Returns: the index where found, or -1

Since: 1.4

lastIndexOfSubList

public static int lastIndexOfSubList(List<?> source, List<?> target)

Returns the starting index where the specified sublist last occurs in a larger list, or -1 if there is no matching position. If target.size() > source.size(), this returns -1, otherwise this implementation uses brute force, checking for source.sublist(i, i + target.size()).equals(target) for all possible i.

Parameters: source the list to search target the sublist to search for

Returns: the index where found, or -1

Since: 1.4

list

public static <T> ArrayList<T> list(Enumeration<T> e)

Returns an ArrayList holding the elements visited by a given Enumeration. This method exists for interoperability between legacy APIs and the new Collection API.

Parameters: e the enumeration to put in a list

Returns: a list containing the enumeration elements

Since: 1.4

max

public static <T extends Object&Comparable<? super T>> T max(Collection<? extends T> c)

Find the maximum element in a Collection, according to the natural ordering of the elements. This implementation iterates over the Collection, so it works in linear time.

Parameters: c the Collection to find the maximum element of

Returns: the maximum element of c

Throws: NoSuchElementException if c is empty ClassCastException if elements in c are not mutually comparable NullPointerException if null.compareTo is called

max

public static <T> T max(Collection<? extends T> c, Comparator<? super T> order)

Find the maximum element in a Collection, according to a specified Comparator. This implementation iterates over the Collection, so it works in linear time.

Parameters: c the Collection to find the maximum element of order the Comparator to order the elements by, or null for natural ordering

Returns: the maximum element of c

Throws: NoSuchElementException if c is empty ClassCastException if elements in c are not mutually comparable NullPointerException if null is compared by natural ordering (only possible when order is null)

min

public static <T extends Object&Comparable<? super T>> T min(Collection<? extends T> c)

Find the minimum element in a Collection, according to the natural ordering of the elements. This implementation iterates over the Collection, so it works in linear time.

Parameters: c the Collection to find the minimum element of

Returns: the minimum element of c

Throws: NoSuchElementException if c is empty ClassCastException if elements in c are not mutually comparable NullPointerException if null.compareTo is called

min

public static <T> T min(Collection<? extends T> c, Comparator<? super T> order)

Find the minimum element in a Collection, according to a specified Comparator. This implementation iterates over the Collection, so it works in linear time.

Parameters: c the Collection to find the minimum element of order the Comparator to order the elements by, or null for natural ordering

Returns: the minimum element of c

nCopies

public static <T> List<T> nCopies(int n, T o)

Creates an immutable list consisting of the same object repeated n times. The returned object is tiny, consisting of only a single reference to the object and a count of the number of elements. It is Serializable, and implements RandomAccess. You can use it in tandem with List.addAll for fast list construction.

Parameters: n the number of times to repeat the object o the object to repeat

Returns: a List consisting of n copies of o

Throws: IllegalArgumentException if n < 0

newSetFromMap

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

Returns a set backed by the supplied map. The resulting set has the same performance, concurrency and ordering characteristics as the original map. The supplied map must be empty and should not be used after the set is created. Each call to the set corresponds to one equivalent method call to the underlying map, with the exception of {@link Set#addAll(Collection)} which is emulated by a series of calls to put.

Parameters: map the map to convert to a set.

Returns: a set backed by the supplied map.

Throws: IllegalArgumentException if the map is not empty.

Since: 1.6

replaceAll

public static <T> boolean replaceAll(List<T> list, T oldval, T newval)

Replace all instances of one object with another in the specified list. The list does not change size. An element e is replaced if oldval == null ? e == null : oldval.equals(e).

Parameters: list the list to iterate over oldval the element to replace newval the new value for the element

Returns: true if a replacement occurred.

Throws: UnsupportedOperationException if the list iterator does not allow for the set operation ClassCastException if newval is of a type which cannot be added to the list IllegalArgumentException if some other aspect of newval stops it being added to the list

Since: 1.4

reverse

public static void reverse(List<?> l)

Reverse a given list. This method works in linear time.

Parameters: l the list to reverse

Throws: UnsupportedOperationException if l.listIterator() does not support the set operation

reverseOrder

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

Get a comparator that implements the reverse of the ordering specified by the given Comparator. If the Comparator is null, this is equivalent to {@link #reverseOrder()}. The return value of this method is Serializable, if the specified Comparator is either Serializable or null.

Parameters: c the comparator to invert

Returns: a comparator that imposes reverse ordering

Since: 1.5

reverseOrder

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

Get a comparator that implements the reverse of natural ordering. In other words, this sorts Comparable objects opposite of how their compareTo method would sort. This makes it easy to sort into reverse order, by simply passing Collections.reverseOrder() to the sort method. The return value of this method is Serializable.

Returns: a comparator that imposes reverse natural ordering

rotate

public static void rotate(List<?> list, int distance)

Rotate the elements in a list by a specified distance. After calling this method, the element now at index i was formerly at index (i - distance) mod list.size(). The list size is unchanged.

For example, suppose a list contains [t, a, n, k, s]. After either Collections.rotate(l, 4) or Collections.rotate(l, -1), the new contents are [s, t, a, n, k]. This can be applied to sublists to rotate just a portion of the list. For example, to move element a forward two positions in the original example, use Collections.rotate(l.subList(1, 3+1), -1), which will result in [t, n, k, a, s].

If the list is small or implements {@link RandomAccess}, the implementation exchanges the first element to its destination, then the displaced element, and so on until a circuit has been completed. The process is repeated if needed on the second element, and so forth, until all elements have been swapped. For large non-random lists, the implementation breaks the list into two sublists at index -distance mod size, calls {@link #reverse(List)} on the pieces, then reverses the overall list.

Parameters: list the list to rotate distance the distance to rotate by; unrestricted in value

Throws: UnsupportedOperationException if the list does not support set

Since: 1.4

shuffle

public static void shuffle(List<?> l)

Shuffle a list according to a default source of randomness. The algorithm used iterates backwards over the list, swapping each element with an element randomly selected from the elements in positions less than or equal to it (using r.nextInt(int)).

This algorithm would result in a perfectly fair shuffle (that is, each element would have an equal chance of ending up in any position) if r were a perfect source of randomness. In practice the results are merely very close to perfect.

This method operates in linear time. To do this on large lists which do not implement {@link RandomAccess}, a temporary array is used to acheive this speed, since it would be quadratic access otherwise.

Parameters: l the list to shuffle

Throws: UnsupportedOperationException if l.listIterator() does not support the set operation

shuffle

public static void shuffle(List<?> l, Random r)

Shuffle a list according to a given source of randomness. The algorithm used iterates backwards over the list, swapping each element with an element randomly selected from the elements in positions less than or equal to it (using r.nextInt(int)).

Parameters: l the list to shuffle r the source of randomness to use for the shuffle

Throws: UnsupportedOperationException if l.listIterator() does not support the set operation

singleton

public static <T> Set<T> singleton(T o)

Obtain an immutable Set consisting of a single element. The return value of this method is Serializable.

Parameters: o the single element

Returns: an immutable Set containing only o

See Also: Serializable

singletonList

public static <T> List<T> singletonList(T o)

Obtain an immutable List consisting of a single element. The return value of this method is Serializable, and implements RandomAccess.

Parameters: o the single element

Returns: an immutable List containing only o

Since: 1.3

See Also: Serializable RandomAccess

singletonMap

public static <K,V> Map<K,V> singletonMap(K key, V value)

Obtain an immutable Map consisting of a single key-value pair. The return value of this method is Serializable.

Parameters: key the single key value the single value

Returns: an immutable Map containing only the single key-value pair

Since: 1.3

See Also: Serializable

sort

public static <T extends Comparable<? super T>> void sort(List<T> l)

Sort a list according to the natural ordering of its elements. The list must be modifiable, but can be of fixed size. The sort algorithm is precisely that used by Arrays.sort(Object[]), which offers guaranteed nlog(n) performance. This implementation dumps the list into an array, sorts the array, and then iterates over the list setting each element from the array.

Parameters: l the List to sort (null not permitted)

Throws: ClassCastException if some items are not mutually comparable UnsupportedOperationException if the List is not modifiable NullPointerException if the list is null, or contains some element that is null.

sort

public static <T> void sort(List<T> l, Comparator<? super T> c)

Sort a list according to a specified Comparator. The list must be modifiable, but can be of fixed size. The sort algorithm is precisely that used by Arrays.sort(Object[], Comparator), which offers guaranteed nlog(n) performance. This implementation dumps the list into an array, sorts the array, and then iterates over the list setting each element from the array.

Parameters: l the List to sort (null not permitted) c the Comparator specifying the ordering for the elements, or null for natural ordering

Throws: ClassCastException if c will not compare some pair of items UnsupportedOperationException if the List is not modifiable NullPointerException if the List is null or null is compared by natural ordering (only possible when c is null)

swap

public static void swap(List<?> l, int i, int j)

Swaps the elements at the specified positions within the list. Equal positions have no effect.

Parameters: l the list to work on i the first index to swap j the second index

Throws: UnsupportedOperationException if list.set is not supported IndexOutOfBoundsException if either i or j is < 0 or >= list.size()

Since: 1.4

synchronizedCollection

public static <T> Collection<T> synchronizedCollection(Collection<T> c)

Returns a synchronized (thread-safe) collection wrapper backed by the given collection. Notice that element access through the iterators is thread-safe, but if the collection can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 Collection c = Collections.synchronizedCollection(new Collection(...));
 ...
 synchronized (c)
   {
     Iterator i = c.iterator();
     while (i.hasNext())
       foo(i.next());
   }

Parameters: c the collection to wrap

Returns: a synchronized view of the collection

See Also: Serializable

synchronizedList

public static <T> List<T> synchronizedList(List<T> l)

Returns a synchronized (thread-safe) list wrapper backed by the given list. Notice that element access through the iterators is thread-safe, but if the list can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 List l = Collections.synchronizedList(new List(...));
 ...
 synchronized (l)
   {
     Iterator i = l.iterator();
     while (i.hasNext())
       foo(i.next());
   }

The returned List implements Serializable, but can only be serialized if the list it wraps is likewise Serializable. In addition, if the wrapped list implements RandomAccess, this does too.

Parameters: l the list to wrap

Returns: a synchronized view of the list

See Also: Serializable RandomAccess

synchronizedMap

public static <K,V> Map<K,V> synchronizedMap(Map<K,V> m)

Returns a synchronized (thread-safe) map wrapper backed by the given map. Notice that element access through the collection views and their iterators are thread-safe, but if the map can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 Map m = Collections.synchronizedMap(new Map(...));
 ...
 Set s = m.keySet(); // safe outside a synchronized block
 synchronized (m) // synch on m, not s
   {
     Iterator i = s.iterator();
     while (i.hasNext())
       foo(i.next());
   }

The returned Map implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.

Parameters: m the map to wrap

Returns: a synchronized view of the map

See Also: Serializable

synchronizedSet

public static <T> Set<T> synchronizedSet(Set<T> s)

Returns a synchronized (thread-safe) set wrapper backed by the given set. Notice that element access through the iterator is thread-safe, but if the set can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 Set s = Collections.synchronizedSet(new Set(...));
 ...
 synchronized (s)
   {
     Iterator i = s.iterator();
     while (i.hasNext())
       foo(i.next());
   }

The returned Set implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.

Parameters: s the set to wrap

Returns: a synchronized view of the set

See Also: Serializable

synchronizedSortedMap

public static <K,V> SortedMap<K,V> synchronizedSortedMap(SortedMap<K,V> m)

Returns a synchronized (thread-safe) sorted map wrapper backed by the given map. Notice that element access through the collection views, subviews, and their iterators are thread-safe, but if the map can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 SortedMap m = Collections.synchronizedSortedMap(new SortedMap(...));
 ...
 Set s = m.keySet(); // safe outside a synchronized block
 SortedMap m2 = m.headMap(foo); // safe outside a synchronized block
 Set s2 = m2.keySet(); // safe outside a synchronized block
 synchronized (m) // synch on m, not m2, s or s2
   {
     Iterator i = s.iterator();
     while (i.hasNext())
       foo(i.next());
     i = s2.iterator();
     while (i.hasNext())
       bar(i.next());
   }

The returned SortedMap implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.

Parameters: m the sorted map to wrap

Returns: a synchronized view of the sorted map

See Also: Serializable

synchronizedSortedSet

public static <T> SortedSet<T> synchronizedSortedSet(SortedSet<T> s)

Returns a synchronized (thread-safe) sorted set wrapper backed by the given set. Notice that element access through the iterator and through subviews are thread-safe, but if the set can be structurally modified (adding or removing elements) then you should synchronize around the iteration to avoid non-deterministic behavior:

 SortedSet s = Collections.synchronizedSortedSet(new SortedSet(...));
 ...
 SortedSet s2 = s.headSet(foo); // safe outside a synchronized block
 synchronized (s) // synch on s, not s2
   {
     Iterator i = s2.iterator();
     while (i.hasNext())
       foo(i.next());
   }

The returned SortedSet implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.

Parameters: s the sorted set to wrap

Returns: a synchronized view of the sorted set

See Also: Serializable

unmodifiableCollection

public static <T> Collection<T> unmodifiableCollection(Collection<? extends T> c)

Returns an unmodifiable view of the given collection. This allows "read-only" access, although changes in the backing collection show up in this view. Attempts to modify the collection directly or via iterators will fail with {@link UnsupportedOperationException}. Although this view prevents changes to the structure of the collection and its elements, the values referenced by the objects in the collection can still be modified.

Parameters: c the collection to wrap

Returns: a read-only view of the collection

See Also: Serializable

unmodifiableList

public static <T> List<T> unmodifiableList(List<? extends T> l)

Returns an unmodifiable view of the given list. This allows "read-only" access, although changes in the backing list show up in this view. Attempts to modify the list directly, via iterators, or via sublists, will fail with {@link UnsupportedOperationException}. Although this view prevents changes to the structure of the list and its elements, the values referenced by the objects in the list can still be modified.

The returned List implements Serializable, but can only be serialized if the list it wraps is likewise Serializable. In addition, if the wrapped list implements RandomAccess, this does too.

Parameters: l the list to wrap

Returns: a read-only view of the list

See Also: Serializable RandomAccess

unmodifiableMap

public static <K,V> Map<K,V> unmodifiableMap(Map<? extends K,? extends V> m)

Returns an unmodifiable view of the given map. This allows "read-only" access, although changes in the backing map show up in this view. Attempts to modify the map directly, or via collection views or their iterators will fail with {@link UnsupportedOperationException}. Although this view prevents changes to the structure of the map and its entries, the values referenced by the objects in the map can still be modified.

The returned Map implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.

Parameters: m the map to wrap

Returns: a read-only view of the map

See Also: Serializable

unmodifiableSet

public static <T> Set<T> unmodifiableSet(Set<? extends T> s)

Returns an unmodifiable view of the given set. This allows "read-only" access, although changes in the backing set show up in this view. Attempts to modify the set directly or via iterators will fail with {@link UnsupportedOperationException}. Although this view prevents changes to the structure of the set and its entries, the values referenced by the objects in the set can still be modified.

The returned Set implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.

Parameters: s the set to wrap

Returns: a read-only view of the set

See Also: Serializable

unmodifiableSortedMap

public static <K,V> SortedMap<K,V> unmodifiableSortedMap(SortedMap<K,? extends V> m)

Returns an unmodifiable view of the given sorted map. This allows "read-only" access, although changes in the backing map show up in this view. Attempts to modify the map directly, via subviews, via collection views, or iterators, will fail with {@link UnsupportedOperationException}. Although this view prevents changes to the structure of the map and its entries, the values referenced by the objects in the map can still be modified.

The returned SortedMap implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.

Parameters: m the map to wrap

Returns: a read-only view of the map

See Also: Serializable

unmodifiableSortedSet

public static <T> SortedSet<T> unmodifiableSortedSet(SortedSet<T> s)

Returns an unmodifiable view of the given sorted set. This allows "read-only" access, although changes in the backing set show up in this view. Attempts to modify the set directly, via subsets, or via iterators, will fail with {@link UnsupportedOperationException}. Although this view prevents changes to the structure of the set and its entries, the values referenced by the objects in the set can still be modified.

The returns SortedSet implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.

Parameters: s the set to wrap

Returns: a read-only view of the set

See Also: Serializable