Android APIs
public class

Collections

extends Object
java.lang.Object
   ↳ java.util.Collections

Class Overview

Collections contains static methods which operate on Collection classes.

Summary

Fields
public static final List EMPTY_LIST An empty immutable instance of List.
public static final Map EMPTY_MAP An empty immutable instance of Map.
public static final Set EMPTY_SET An empty immutable instance of Set.
Public Methods
static <T> boolean addAll(Collection<? super T> c, T... a)
Adds all the specified elements to the specified collection.
static <T> Queue<T> asLifoQueue(Deque<T> deque)
Returns a last-in, first-out queue as a view of deque.
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.
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.
static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type)
Returns a dynamically typesafe view of the specified collection.
static <E> List<E> checkedList(List<E> list, Class<E> type)
Returns a dynamically typesafe view of the specified list.
static <K, V> Map<K, V> checkedMap(Map<K, V> m, Class<K> keyType, Class<V> valueType)
Returns a dynamically typesafe view of the specified map.
static <E> Set<E> checkedSet(Set<E> s, Class<E> type)
Returns a dynamically typesafe view of the specified set.
static <K, V> SortedMap<K, V> checkedSortedMap(SortedMap<K, V> m, Class<K> keyType, Class<V> valueType)
Returns a dynamically typesafe view of the specified sorted map.
static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s, Class<E> type)
Returns a dynamically typesafe view of the specified sorted set.
static <T> void copy(List<? super T> destination, List<? extends T> source)
Copies the elements from the source list to the destination list.
static boolean disjoint(Collection<?> c1, Collection<?> c2)
Returns whether the specified collections have no elements in common.
static <T> Enumeration<T> emptyEnumeration()
Returns an enumeration containing no elements.
static <T> Iterator<T> emptyIterator()
Returns an iterator containing no elements.
final static <T> List<T> emptyList()
Returns a type-safe empty, immutable List.
static <T> ListIterator<T> emptyListIterator()
Returns a list iterator containing no elements.
final static <K, V> Map<K, V> emptyMap()
Returns a type-safe empty, immutable Map.
final static <T> Set<T> emptySet()
Returns a type-safe empty, immutable Set.
static <T> Enumeration<T> enumeration(Collection<T> collection)
Returns an Enumeration on the specified collection.
static <T> void fill(List<? super T> list, T object)
Fills the specified list with the specified element.
static int frequency(Collection<?> c, Object o)
Returns the number of elements in the Collection that match the Object passed.
static int indexOfSubList(List<?> list, List<?> sublist)
Searches the list for sublist and returns the beginning index of the first occurrence.
static int lastIndexOfSubList(List<?> list, List<?> sublist)
Searches the list for sublist and returns the beginning index of the last occurrence.
static <T> ArrayList<T> list(Enumeration<T> enumeration)
Returns an ArrayList with all the elements in the enumeration.
static <T extends Object & Comparable<? super T>> T max(Collection<? extends T> collection)
Searches the specified collection for the maximum element.
static <T> T max(Collection<? extends T> collection, Comparator<? super T> comparator)
Searches the specified collection for the maximum element using the specified comparator.
static <T> T min(Collection<? extends T> collection, Comparator<? super T> comparator)
Searches the specified collection for the minimum element using the specified comparator.
static <T extends Object & Comparable<? super T>> T min(Collection<? extends T> collection)
Searches the specified collection for the minimum element.
static <T> List<T> nCopies(int length, T object)
Returns a list containing the specified number of the specified element.
static <E> Set<E> newSetFromMap(Map<E, Boolean> map)
Returns a set backed by map.
static <T> boolean replaceAll(List<T> list, T obj, T obj2)
Replaces all occurrences of Object obj in list with newObj.
static void reverse(List<?> list)
Modifies the specified List by reversing the order of the elements.
static <T> Comparator<T> reverseOrder()
A comparator which reverses the natural order of the elements.
static <T> Comparator<T> reverseOrder(Comparator<T> c)
Returns a Comparator that reverses the order of the Comparator passed.
static void rotate(List<?> lst, int dist)
Rotates the elements in list by the distance dist

e.g.

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.
static void shuffle(List<?> list)
Moves every element of the list to a random new position in the list.
static <E> Set<E> singleton(E object)
Returns a set containing the specified element.
static <E> List<E> singletonList(E object)
Returns a list containing the specified element.
static <K, V> Map<K, V> singletonMap(K key, V value)
Returns a Map containing the specified key and value.
static <T> void sort(List<T> list, Comparator<? super T> comparator)
Sorts the given list using the given comparator.
static <T extends Comparable<? super T>> void sort(List<T> list)
Sorts the given list in ascending natural order.
static void swap(List<?> list, int index1, int index2)
Swaps the elements of list list at indices index1 and index2.
static <T> Collection<T> synchronizedCollection(Collection<T> collection)
Returns a wrapper on the specified collection which synchronizes all access to the collection.
static <T> List<T> synchronizedList(List<T> list)
Returns a wrapper on the specified List which synchronizes all access to the List.
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.
static <E> Set<E> synchronizedSet(Set<E> set)
Returns a wrapper on the specified set which synchronizes all access to the set.
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.
static <E> SortedSet<E> synchronizedSortedSet(SortedSet<E> set)
Returns a wrapper on the specified sorted set which synchronizes all access to the sorted set.
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.
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.
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.
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.
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.
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.
[Expand]
Inherited Methods
From class java.lang.Object

Fields

public static final List EMPTY_LIST

Added in API level 1

An empty immutable instance of List.

public static final Map EMPTY_MAP

Added in API level 1

An empty immutable instance of Map.

public static final Set EMPTY_SET

Added in API level 1

An empty immutable instance of Set.

Public Methods

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

Added in API level 1

Adds all the specified elements to the specified collection.

Parameters
c Collection: the collection the elements are to be inserted into.
a T: the elements to insert.
Returns
boolean 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.

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

Added in API level 9

Returns a last-in, first-out queue as a view of deque.

Parameters
deque Deque
Returns
Queue<T>

public static int binarySearch (List<? extends Comparable<? super T>> list, T object)

Added in API level 1

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: the sorted list to search.
object T: the element to find.
Returns
int 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.

public static int binarySearch (List<? extends T> list, T object, Comparator<? super T> comparator)

Added in API level 1

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: the sorted List to search.
object T: the element to find.
comparator Comparator: the comparator. If the comparator is null then the search uses the objects' natural ordering.
Returns
int 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.

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

Added in API level 1

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: the collection to be wrapped in a typesafe collection.
type Class: the type of the elements permitted to insert.
Returns
Collection<E> a typesafe collection.

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

Added in API level 1

Returns a dynamically typesafe view of the specified list. Trying to insert an element of the wrong type into this list throws a ClassCastException. At creation time the types in list are not checked for correct type.

Parameters
list List: the list to be wrapped in a typesafe list.
type Class: the type of the elements permitted to insert.
Returns
List<E> a typesafe list.

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

Added in API level 1

Returns a dynamically typesafe view of the specified map. Trying to insert an element of the wrong type into this map throws a ClassCastException. At creation time the types in m are not checked for correct type.

Parameters
m Map: the map to be wrapped in a typesafe map.
keyType Class: the type of the keys permitted to insert.
valueType Class: the type of the values permitted to insert.
Returns
Map<K, V> a typesafe map.

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

Added in API level 1

Returns a dynamically typesafe view of the specified set. Trying to insert an element of the wrong type into this set throws a ClassCastException. At creation time the types in s are not checked for correct type.

Parameters
s Set: the set to be wrapped in a typesafe set.
type Class: the type of the elements permitted to insert.
Returns
Set<E> a typesafe set.

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

Added in API level 1

Returns a dynamically typesafe view of the specified sorted map. Trying to insert an element of the wrong type into this sorted map throws a ClassCastException. At creation time the types in m are not checked for correct type.

Parameters
m SortedMap: the sorted map to be wrapped in a typesafe sorted map.
keyType Class: the type of the keys permitted to insert.
valueType Class: the type of the values permitted to insert.
Returns
SortedMap<K, V> a typesafe sorted map.

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

Added in API level 1

Returns a dynamically typesafe view of the specified sorted set. Trying to insert an element of the wrong type into this sorted set throws a ClassCastException. At creation time the types in s are not checked for correct type.

Parameters
s SortedSet: the sorted set to be wrapped in a typesafe sorted set.
type Class: the type of the elements permitted to insert.
Returns
SortedSet<E> a typesafe sorted set.

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

Added in API level 1

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: the list whose elements are set from the source list.
source List: 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.

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

Added in API level 1

Returns whether the specified collections have no elements in common.

Parameters
c1 Collection: the first collection.
c2 Collection: the second collection.
Returns
boolean true if the collections have no elements in common, false otherwise.
Throws
NullPointerException if one of the collections is null.

public static Enumeration<T> emptyEnumeration ()

Added in API level 19

Returns an enumeration containing no elements.

Returns
Enumeration<T>

public static Iterator<T> emptyIterator ()

Added in API level 19

Returns an iterator containing no elements.

Returns
Iterator<T>

public static final List<T> emptyList ()

Added in API level 1

Returns a type-safe empty, immutable List.

Returns
List<T> an empty List.

See also:

public static ListIterator<T> emptyListIterator ()

Added in API level 19

Returns a list iterator containing no elements.

Returns
ListIterator<T>

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

Added in API level 1

Returns a type-safe empty, immutable Map.

Returns
Map<K, V> an empty Map.

See also:

public static final Set<T> emptySet ()

Added in API level 1

Returns a type-safe empty, immutable Set.

Returns
Set<T> an empty Set.

See also:

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

Added in API level 1

Returns an Enumeration on the specified collection.

Parameters
collection Collection: the collection to enumerate.
Returns
Enumeration<T> an Enumeration.

public static void fill (List<? super T> list, T object)

Added in API level 1

Fills the specified list with the specified element.

Parameters
list List: 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.

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

Added in API level 1

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
int the number of matching elements.
Throws
NullPointerException if the Collection parameter is null.

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

Added in API level 1

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
int the beginning index of the first occurrence of sublist in list, or -1.

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

Added in API level 1

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
int the beginning index of the last occurrence of sublist in list, or -1.

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

Added in API level 1

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: the source Enumeration.
Returns
ArrayList<T> an ArrayList from enumeration.

public static T max (Collection<? extends T> collection)

Added in API level 1

Searches the specified collection for the maximum element.

Parameters
collection Collection: the collection to search.
Returns
T 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.

public static T max (Collection<? extends T> collection, Comparator<? super T> comparator)

Added in API level 1

Searches the specified collection for the maximum element using the specified comparator.

Parameters
collection Collection: the collection to search.
comparator Comparator: the comparator.
Returns
T the maximum element in the Collection.
Throws
ClassCastException when elements in the collection cannot be compared to each other using the Comparator.

public static T min (Collection<? extends T> collection, Comparator<? super T> comparator)

Added in API level 1

Searches the specified collection for the minimum element using the specified comparator.

Parameters
collection Collection: the collection to search.
comparator Comparator: the comparator.
Returns
T the minimum element in the collection.
Throws
ClassCastException when elements in the collection cannot be compared to each other using the Comparator.

public static T min (Collection<? extends T> collection)

Added in API level 1

Searches the specified collection for the minimum element.

Parameters
collection Collection: the collection to search.
Returns
T 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.

public static List<T> nCopies (int length, T object)

Added in API level 1

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
List<T> a list containing length copies of the element.
Throws
IllegalArgumentException when length < 0.

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

Added in API level 9

Returns a set backed by map.

Parameters
map Map
Returns
Set<E>
Throws
IllegalArgumentException if the map is not empty

public static boolean replaceAll (List<T> list, T obj, T obj2)

Added in API level 1

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: 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
boolean true, if at least one occurrence of obj has been found in list.
Throws
UnsupportedOperationException if the list does not support setting elements.

public static void reverse (List<?> list)

Added in API level 1

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.

public static Comparator<T> reverseOrder ()

Added in API level 1

A comparator which reverses the natural order of the elements. The Comparator that's returned is Serializable.

Returns
Comparator<T> a Comparator instance.

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

Added in API level 1

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: the Comparator to reverse or null.
Returns
Comparator<T> a Comparator instance.

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

Added in API level 1

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.

public static void shuffle (List<?> list, Random random)

Added in API level 1

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.

public static void shuffle (List<?> list)

Added in API level 1

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.

public static Set<E> singleton (E object)

Added in API level 1

Returns a set containing the specified element. The set cannot be modified. The set is serializable.

Parameters
object E: the element.
Returns
Set<E> a set containing the element.

public static List<E> singletonList (E object)

Added in API level 1

Returns a list containing the specified element. The list cannot be modified. The list is serializable.

Parameters
object E: the element.
Returns
List<E> a list containing the element.

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

Added in API level 1

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
Map<K, V> a Map containing the key and value.

public static void sort (List<T> list, Comparator<? super T> comparator)

Added in API level 1

Sorts the given list using the given comparator. The algorithm is stable which means equal elements don't get reordered.

Parameters
list List
comparator Comparator
Throws
ClassCastException if any element does not implement Comparable, or if compareTo throws for any pair of elements.

public static void sort (List<T> list)

Added in API level 1

Sorts the given list in ascending natural order. The algorithm is stable which means equal elements don't get reordered.

Parameters
list List
Throws
ClassCastException if any element does not implement Comparable, or if compareTo throws for any pair of elements.

public static void swap (List<?> list, int index1, int index2)

Added in API level 1

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.

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

Added in API level 1

Returns a wrapper on the specified collection which synchronizes all access to the collection.

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

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

Added in API level 1

Returns a wrapper on the specified List which synchronizes all access to the List.

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

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

Added in API level 1

Returns a wrapper on the specified map which synchronizes all access to the map.

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

public static Set<E> synchronizedSet (Set<E> set)

Added in API level 1

Returns a wrapper on the specified set which synchronizes all access to the set.

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

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

Added in API level 1

Returns a wrapper on the specified sorted map which synchronizes all access to the sorted map.

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

public static SortedSet<E> synchronizedSortedSet (SortedSet<E> set)

Added in API level 1

Returns a wrapper on the specified sorted set which synchronizes all access to the sorted set.

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

public static Collection<E> unmodifiableCollection (Collection<? extends E> collection)

Added in API level 1

Returns a wrapper on the specified collection which throws an UnsupportedOperationException whenever an attempt is made to modify the collection.

Parameters
collection Collection: the collection to wrap in an unmodifiable collection.
Returns
Collection<E> an unmodifiable collection.

public static List<E> unmodifiableList (List<? extends E> list)

Added in API level 1

Returns a wrapper on the specified list which throws an UnsupportedOperationException whenever an attempt is made to modify the list.

Parameters
list List: the list to wrap in an unmodifiable list.
Returns
List<E> an unmodifiable List.

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

Added in API level 1

Returns a wrapper on the specified map which throws an UnsupportedOperationException whenever an attempt is made to modify the map.

Parameters
map Map: the map to wrap in an unmodifiable map.
Returns
Map<K, V> a unmodifiable map.

public static Set<E> unmodifiableSet (Set<? extends E> set)

Added in API level 1

Returns a wrapper on the specified set which throws an UnsupportedOperationException whenever an attempt is made to modify the set.

Parameters
set Set: the set to wrap in an unmodifiable set.
Returns
Set<E> a unmodifiable set

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

Added in API level 1

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: the sorted map to wrap in an unmodifiable sorted map.
Returns
SortedMap<K, V> a unmodifiable sorted map

public static SortedSet<E> unmodifiableSortedSet (SortedSet<E> set)

Added in API level 1

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: the sorted set to wrap in an unmodifiable sorted set.
Returns
SortedSet<E> a unmodifiable sorted set.