This class defines static methods
and constants that are useful for working with collections and maps.
One of the most commonly used methods is sort( ),
which sorts a List in place (the list cannot be
immutable, of course). The sorting algorithm is stable, which means
that equal elements retain the same relative order. One version of
sort( ) uses a specified
Comparator to perform the sort; the other relies
on the natural ordering of the list elements and requires all the
elements to implement java.lang.Comparable.
reverseOrder( ) returns a
Comparator object that reverses the order of
another Comparator or that reverse the natural
ordering of Comparable objects.
A related method is
binarySearch( ). It efficiently (in logarithmic
time) searches a sorted List for a specified
object and returns the index at which a matching object is found. If
no match is found, it returns a negative number. For a negative
return value r, the value
-(r+1) specifies the index at which the specified
object can be inserted into the list to maintain the sorted order of
the list. As with sort( ), binarySearch(
) can be passed a Comparator that
defines the order of the sorted list. If no
Comparator is specified, the list elements must
all implement Comparable, and the list is assumed
to be sorted according to the natural ordering defined by this
interface.
See Arrays for methods that perform sorting and
searching operations on arrays instead of collections.
The
various methods whose names begin with
synchronized return a threadsafe collection object
wrapped around the specified collection. Vector
and Hashtable are the only two collection objects
threadsafe by default. Use these methods to obtain a
synchronized wrapper object if you are using any
other type of Collection or Map
in a multithreaded environment where more than one thread can modify
it.
The
various methods whose names begin with
unmodifiable function like
synchronized methods. They return a
Collection or Map object
wrapped around the specified collection. The returned object is
unmodifiable, however, so its add( ),
remove( ), set( ),
put( ), etc. methods all throw
java.lang.UnsupportedOperationException. In Java
5.0, the "checked" methods return
wrapped collections that enforce a specified element type for the
collection, so that it is not possible to add an element of the wrong
type.
In addition to the "synchronized",
"unmodifiable", and
"checked" methods,
Collections defines a number of other methods that
return special-purpose collections or maps:
singleton( )
returns an unmodifiable set that contains only the specified object.
singletonList( ) and singletonMap(
) return an immutable list and an immutable map,
respectively, each of which contains only a single entry. The
Collections class also defines related constants,
EMPTY_LIST, EMPTY_SET, and
EMPTY_MAP, which are immutable
List, Set, and
Map objects that contain no elements or mappings.
In Java 5.0, the emptySet( ), emptyList(
), and emptyMap( ) methods are preferred
alternatives to these constants, because they are generic methods and
return correctly parameterized empty collections. nCopies(
) creates a new immutable List that
contains a specified number of copies of a specified object.
list( ) returns a List object
that represents the elements of the specified
Enumeration object. enumeration(
) does the reverse: it returns an
Enumeration for a Collection,
which is useful when working with code that uses the old
Enumeration interface instead of the newer
Iterator interface.
The Collections
class also defines methods that mutate a collection. These methods
throw an UnsupportedOperationException if the
target collection is does not allow mutation. copy(
) copies elements of a source list into a destination list.
fill( ) replaces all elements of the specified
list with the specified object. swap( ) swaps the
elements at two specified indexes of a List.
replaceAll( ) replaces all elements in a
List that are equal to (using the equals(
) method) with another object, and returns
true if any replacements were done.
reverse( ) reverses the order of the elements in a
list. rotate( )
"rotates" a list, adding the
specified number to the index of each element, and wrapping elements
from the end of the list back to the front of the list. (Specifying a
negative rotation rotates the list in the other direction.)
shuffle( ) randomizes the order of elements in a
list, using either an internal source of randomness or the
Random pseudorandom number generator you provide.
In Java 5.0, the addAll( ) method adds the
specified elements to the specified collection. This method is a
varargs method and allows elements to be specified in an array or
listed individually in the argument list.
Finally,
Collections defines methods (in addition to the
binarySearch( ) methods described above) that
search the elements of a collection: min( ) and
max( ) methods search an unordered
Collection for the minimum and maximum elements,
according either to a specified Comparator or to
the natural order defined by the Comparable
elements themselves. indexOfSubList( ) and
lastIndexOfSubList( ) search a specified list
forward or backward for a subsequence of elements that match (using
equals( )) the elements the a second specified
list. They return the start index of any such matching sublist, or
return -1 if no match was found. These methods are like the
indexOf( ) and lastIndexOf( )
methods of String, and do not require the
List to be sorted, as the binarySearch(
) methods do. In Java 5.0, frequency( )
returns the number of occurences of a specified element in a
specified collection, and disjoint( ) determines
whether two collections are entirely disjointwhether they have
no elements in common.
public class Collections {
// No Constructor
// Public Constants
public static final List EMPTY_LIST;
1.3 public static final Map EMPTY_MAP;
public static final Set EMPTY_SET;
// Public Class Methods
5.0 public static <T> boolean addAll(Collection<? super T> c, T ... a);
public static <T> int binarySearch(List<? extends Comparable<? super T>> list, T key);
public static <T> int binarySearch(List<? extends T> list, T key, Comparator<? super T> c);
5.0 public static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type);
5.0 public static <E> List<E> checkedList(List<E> list, Class<E> type);
5.0 public static <K,V> Map<K,V> checkedMap(Map<K,V> m, Class<K> keyType, Class<V> valueType);
5.0 public static <E> Set<E> checkedSet(Set<E> s, Class<E> type);
5.0 public static <K,V> SortedMap<K,V> checkedSortedMap(SortedMap<K,V> m, Class<K> keyType,
Class<V> valueType);
5.0 public static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s, Class<E> type);
public static <T> void copy(List<? super T> dest, List<? extends T> src);
5.0 public static boolean disjoint(Collection<?> c1, Collection<?> c2);
5.0 public static final <T> List<T> emptyList( );
5.0 public static final <K,V> Map<K,V> emptyMap( );
5.0 public static final <T> Set<T> emptySet( );
public static <T> Enumeration<T> enumeration(Collection<T> c);
public static <T> void fill(List<? super T> list, T obj);
5.0 public static int frequency(Collection<?> c, Object o);
1.4 public static int indexOfSubList(List<?> source, List<?> target);
1.4 public static int lastIndexOfSubList(List<?> source, List<?> target);
1.4 public static <T> ArrayList<T> list(Enumeration<T> e);
public static <T extends Object&Comparable<? super T>> T max(Collection<? extends T> coll);
public static <T> T max(Collection<? extends T> coll, Comparator<? super T> comp);
public static <T extends Object&Comparable<? super T>> T min(Collection<? extends T> coll);
public static <T> T min(Collection<? extends T> coll, Comparator<? super T> comp);
public static <T> List<T> nCopies(int n, T o);
1.4 public static <T> boolean replaceAll(List<T> list, T oldVal, T newVal);
public static void reverse(List<?> list);
public static <T> Comparator<T> reverseOrder( );
5.0 public static <T> Comparator<T> reverseOrder(Comparator<T> cmp);
1.4 public static void rotate(List<?> list, int distance);
public static void shuffle(List<?> list);
public static void shuffle(List<?> list, Random rnd);
public static <T> Set<T> singleton(T o);
1.3 public static <T> List<T> singletonList(T o);
1.3 public static <K,V> Map<K,V> singletonMap(K key, V value);
public static <T extends Comparable<? super T>> void sort(List<T> list);
public static <T> void sort(List<T> list, Comparator<? super T> c);
1.4 public static void swap(List<?> list, int i, int j);
public static <T> Collection<T> synchronizedCollection(Collection<T> c);
public static <T> List<T> synchronizedList(List<T> list);
public static <K,V> Map<K,V> synchronizedMap(Map<K,V> m);
public static <T> Set<T> synchronizedSet(Set<T> s);
public static <K,V> SortedMap<K,V> synchronizedSortedMap(SortedMap<K,V> m);
public static <T> SortedSet<T> synchronizedSortedSet(SortedSet<T> s);
public static <T> Collection<T> unmodifiableCollection(Collection<? extends T> c);
public static <T> List<T> unmodifiableList(List<? extends T> list);
public static <K,V> Map<K,V> unmodifiableMap(Map<? extends K,? extends V> m);
public static <T> Set<T> unmodifiableSet(Set<? extends T> s);
public static <K,V> SortedMap<K,V> unmodifiableSortedMap(SortedMap<K,? extends V> m);
public static <T> SortedSet<T> unmodifiableSortedSet(SortedSet<T> s);
}
