java.lang.Object | +--java.util.Collections
static java.util.List | EMPTY_LIST An immutable, serializable, empty List, which implements RandomAccess. |
static java.util.Map | EMPTY_MAP An immutable, serializable, empty Map. |
static java.util.Set | EMPTY_SET An immutable, serializable, empty Set. |
static int | binarySearch(java.util.List l, java.lang.Object key) Perform a binary search of a List for a key, using the natural ordering of the elements. |
static int | binarySearch(java.util.List l, java.lang.Object key, java.util.Comparator c) Perform a binary search of a List for a key, using a supplied Comparator. |
static void | copy(java.util.List dest, java.util.List source) Copy one list to another. |
static java.util.Enumeration | enumeration(java.util.Collection c) Returns an Enumeration over a collection. |
static void | fill(java.util.List l, java.lang.Object val) Replace every element of a list with a given value. |
static int | indexOfSubList(java.util.List source, java.util.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(java.util.List source, java.util.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 java.util.ArrayList | list(java.util.Enumeration e) Returns an ArrayList holding the elements visited by a given Enumeration. |
static java.lang.Object | max(java.util.Collection c) Find the maximum element in a Collection, according to the natural ordering of the elements. |
static java.lang.Object | max(java.util.Collection c, java.util.Comparator order) Find the maximum element in a Collection, according to a specified Comparator. |
static java.lang.Object | min(java.util.Collection c) Find the minimum element in a Collection, according to the natural ordering of the elements. |
static java.lang.Object | min(java.util.Collection c, java.util.Comparator order) Find the minimum element in a Collection, according to a specified Comparator. |
static java.util.List | nCopies(final int n, final Object o) Creates an immutable list consisting of the same object repeated n times. |
static boolean | replaceAll(java.util.List list, java.lang.Object oldval, java.lang.Object newval) Replace all instances of one object with another in the specified list. |
static void | reverse(java.util.List l) Reverse a given list. |
static java.util.Comparator | reverseOrder() Get a comparator that implements the reverse of natural ordering. |
static void | rotate(java.util.List list, int distance) Rotate the elements in a list by a specified distance. |
static void | shuffle(java.util.List l) Shuffle a list according to a default source of randomness. |
static void | shuffle(java.util.List l, java.util.Random r) Shuffle a list according to a given source of randomness. |
static java.util.Set | singleton(java.lang.Object o) Obtain an immutable Set consisting of a single element. |
static java.util.List | singletonList(java.lang.Object o) Obtain an immutable List consisting of a single element. |
static java.util.Map | singletonMap(java.lang.Object key, java.lang.Object value) Obtain an immutable Map consisting of a single key-value pair. |
static void | sort(java.util.List l) Sort a list according to the natural ordering of its elements. |
static void | sort(java.util.List l, java.util.Comparator c) Sort a list according to a specified Comparator. |
static void | swap(java.util.List l, int i, int j) Swaps the elements at the specified positions within the list. |
static java.util.Collection | synchronizedCollection(java.util.Collection c) Returns a synchronized (thread-safe) collection wrapper backed by the given collection. |
static java.util.List | synchronizedList(java.util.List l) Returns a synchronized (thread-safe) list wrapper backed by the given list. |
static java.util.Map | synchronizedMap(java.util.Map m) Returns a synchronized (thread-safe) map wrapper backed by the given map. |
static java.util.Set | synchronizedSet(java.util.Set s) Returns a synchronized (thread-safe) set wrapper backed by the given set. |
static java.util.SortedMap | synchronizedSortedMap(java.util.SortedMap m) Returns a synchronized (thread-safe) sorted map wrapper backed by the given map. |
static java.util.SortedSet | synchronizedSortedSet(java.util.SortedSet s) Returns a synchronized (thread-safe) sorted set wrapper backed by the given set. |
static java.util.Collection | unmodifiableCollection(java.util.Collection c) Returns an unmodifiable view of the given collection. |
static java.util.List | unmodifiableList(java.util.List l) Returns an unmodifiable view of the given list. |
static java.util.Map | unmodifiableMap(java.util.Map m) Returns an unmodifiable view of the given map. |
static java.util.Set | unmodifiableSet(java.util.Set s) Returns an unmodifiable view of the given set. |
static java.util.SortedMap | unmodifiableSortedMap(java.util.SortedMap m) Returns an unmodifiable view of the given sorted map. |
static java.util.SortedSet | unmodifiableSortedSet(java.util.SortedSet s) Returns an unmodifiable view of the given sorted set. |
public static final List EMPTY_LIST
public static final Map EMPTY_MAP
public static final Set EMPTY_SET
public static int binarySearch(java.util.List l, java.lang.Object key)
This algorithm behaves in log(n) time for RandomAccess lists, and uses a linear search with O(n) link traversals and log(n) comparisons with AbstractSequentialList lists. Note: although the specification allows for an infinite loop if the list is unsorted, it will not happen in this (Classpath) implementation.
l
- the list to search (must be sorted)key
- the value to search forClassCastException
- if key could not be compared with one of the
elements of lNullPointerException
- if a null element has compareTo calledpublic static int binarySearch(java.util.List l, java.lang.Object key, java.util.Comparator c)
This algorithm behaves in log(n) time for RandomAccess lists, and uses a linear search with O(n) link traversals and log(n) comparisons with AbstractSequentialList lists. Note: although the specification allows for an infinite loop if the list is unsorted, it will not happen in this (Classpath) implementation.
l
- the list to search (must be sorted)key
- the value to search forc
- the comparator by which the list is sortedClassCastException
- if key could not be compared with one of the
elements of lNullPointerException
- if a null element is compared with natural
ordering (only possible when c is null)public static void copy(java.util.List dest, java.util.List source)
dest
- the destination listsource
- the source listIndexOutOfBoundsException
- if the destination list is shorter
than the source list (the destination will be unmodified)UnsupportedOperationException
- if dest.listIterator() does not
support the set operationpublic static Enumeration enumeration(java.util.Collection c)
c
- the Collection to iterate overpublic static void fill(java.util.List l, java.lang.Object val)
l
- the list to fill.val
- the object to vill the list with.UnsupportedOperationException
- if l.listIterator() does not
support the set operation.public static int indexOfSubList(java.util.List source, java.util.List target)
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.
source
- the list to searchtarget
- the sublist to search forpublic static int lastIndexOfSubList(java.util.List source, java.util.List target)
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.
source
- the list to searchtarget
- the sublist to search forpublic static ArrayList list(java.util.Enumeration e)
e
- the enumeration to put in a listpublic static Object max(java.util.Collection c)
c
- the Collection to find the maximum element ofNoSuchElementException
- if c is emptyClassCastException
- if elements in c are not mutually comparableNullPointerException
- if null.compareTo is calledpublic static Object max(java.util.Collection c, java.util.Comparator order)
c
- the Collection to find the maximum element oforder
- the Comparator to order the elements by, or null for natural
orderingNoSuchElementException
- if c is emptyClassCastException
- if elements in c are not mutually comparableNullPointerException
- if null is compared by natural ordering
(only possible when order is null)public static Object min(java.util.Collection c)
c
- the Collection to find the minimum element ofNoSuchElementException
- if c is emptyClassCastException
- if elements in c are not mutually comparableNullPointerException
- if null.compareTo is calledpublic static Object min(java.util.Collection c, java.util.Comparator order)
c
- the Collection to find the minimum element oforder
- the Comparator to order the elements by, or null for natural
orderingNoSuchElementException
- if c is emptyClassCastException
- if elements in c are not mutually comparableNullPointerException
- if null is compared by natural ordering
(only possible when order is null)public static List nCopies(final int n, final Object o)
n
- the number of times to repeat the objecto
- the object to repeatIllegalArgumentException
- if n < 0public static boolean replaceAll(java.util.List list, java.lang.Object oldval, java.lang.Object newval)
oldval == null ? e == null : oldval.equals(e)
.
list
- the list to iterate overoldval
- the element to replacenewval
- the new value for the elementUnsupportedOperationException
- if the list iterator does not allow
for the set operationClassCastException
- newval is of a type which cannot be added
to the listIllegalArgumentException
- some other aspect of newval stops
it being added to the listpublic static void reverse(java.util.List l)
l
- the list to reverseUnsupportedOperationException
- if l.listIterator() does not
support the set operationpublic static Comparator reverseOrder()
public static void rotate(java.util.List list, int distance)
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 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 #reverse(List) on the
pieces, then reverses the overall list.
list
- the list to rotatedistance
- the distance to rotate by; unrestricted in valueUnsupportedOperationException
- if the list does not support setpublic static void shuffle(java.util.List l)
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 RandomAccess, a temporary array is used to acheive this speed, since it would be quadratic access otherwise.
l
- the list to shuffleUnsupportedOperationException
- if l.listIterator() does not
support the set operationpublic static void shuffle(java.util.List l, java.util.Random r)
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 practise (eg if r = new Random()) the results are merely very close to perfect.
This method operates in linear time. To do this on large lists which do not implement RandomAccess, a temporary array is used to acheive this speed, since it would be quadratic access otherwise.
l
- the list to shuffler
- the source of randomness to use for the shuffleUnsupportedOperationException
- if l.listIterator() does not
support the set operationpublic static Set singleton(java.lang.Object o)
o
- the single elementpublic static List singletonList(java.lang.Object o)
o
- the single elementpublic static Map singletonMap(java.lang.Object key, java.lang.Object value)
key
- the single keyvalue
- the single valuepublic static void sort(java.util.List l)
l
- the List to sortClassCastException
- if some items are not mutually comparableUnsupportedOperationException
- if the List is not modifiableNullPointerException
- if some element is nullpublic static void sort(java.util.List l, java.util.Comparator c)
l
- the List to sortc
- the Comparator specifying the ordering for the elements, or
null for natural orderingClassCastException
- if c will not compare some pair of itemsUnsupportedOperationException
- if the List is not modifiableNullPointerException
- if null is compared by natural ordering
(only possible when c is null)public static void swap(java.util.List l, int i, int j)
l
- the list to work oni
- the first index to swapj
- the second indexUnsupportedOperationException
- if list.set is not supportedIndexOutOfBoundsException
- if either i or j is < 0 or >=
list.size()public static Collection synchronizedCollection(java.util.Collection c)
Collection c = Collections.synchronizedCollection(new Collection(...)); ... synchronized (c) { Iterator i = c.iterator(); while (i.hasNext()) foo(i.next()); }
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.
c
- the collection to wrappublic static List synchronizedList(java.util.List l)
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.
l
- the list to wrappublic static Map synchronizedMap(java.util.Map m)
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.
m
- the map to wrappublic static Set synchronizedSet(java.util.Set s)
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.
s
- the set to wrappublic static SortedMap synchronizedSortedMap(java.util.SortedMap m)
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.
m
- the sorted map to wrappublic static SortedSet synchronizedSortedSet(java.util.SortedSet s)
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.
s
- the sorted set to wrappublic static Collection unmodifiableCollection(java.util.Collection c)
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.
c
- the collection to wrappublic static List unmodifiableList(java.util.List l)
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.
l
- the list to wrappublic static Map unmodifiableMap(java.util.Map m)
The returned Map implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.
m
- the map to wrappublic static Set unmodifiableSet(java.util.Set s)
The returned Set implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.
s
- the set to wrappublic static SortedMap unmodifiableSortedMap(java.util.SortedMap m)
The returned SortedMap implements Serializable, but can only be serialized if the map it wraps is likewise Serializable.
m
- the map to wrappublic static SortedSet unmodifiableSortedSet(java.util.SortedSet s)
The returns SortedSet implements Serializable, but can only be serialized if the set it wraps is likewise Serializable.
s
- the set to wrap
All methods which take a collection throw a NullPointerException if that collection is null. Algorithms which can change a collection may, but are not required, to throw the 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.