Class Collections

java.lang.Object
java.util.Collections
public class Collections extends Object

Collections contains static methods which operate on Collection classes.

Since

1.2

  • Field Summary

    Fields
    Modifier and Type
    Field
    Description
    static final List
    EMPTY_LIST
    An empty immutable instance of List.
    static final Map
    EMPTY_MAP
    An empty immutable instance of Map.
    static final Set
    EMPTY_SET
    An empty immutable instance of Set.

  • Method Summary

    Modifier and Type
    Method
    Description
    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)
    Answers a LIFO Queue as a view of a 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 <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 final <T> List<T>
    emptyList()
    Returns a type-safe empty, immutable List.
    static final <K,V> Map<K,V>
    emptyMap()
    Returns a type-safe empty, immutable Map.
    static final <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 extends Object & Comparable<? super T>>
    T
    min(Collection<? extends T> collection)
    Searches the specified collection for the minimum element.
    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> 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)
    Answers a set backed by a 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
    static void
    shuffle(List<?> list)
    Moves every element of the list to a random new position in the list.
    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 <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 extends Comparable<? super T>>
    void
    sort(List<T> list)
    Sorts the specified list in ascending natural order.
    static <T> void
    sort(List<T> list, Comparator<? super T> comparator)
    Sorts the specified list using the specified comparator.
    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.

    Methods inherited from class Object

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

  • Field Details

    • EMPTY_LIST

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

    • EMPTY_SET

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

    • EMPTY_MAP

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

  • Method Details

    • binarySearch

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

      Performs a binary search for the specified element in the specified sorted list. The list needs to be already sorted in natural sorting order. Searching in an unsorted array has an undefined result. It's also undefined which element is found if there are multiple occurrences of the same element.

      Parameters

      • list: the sorted list to search.

      • object: the element to find.

      Returns
      Returns:

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

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

    • binarySearch

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

      Performs a binary search for the specified element in the specified sorted list using the specified comparator. The list needs to be already sorted according to the comparator passed. Searching in an unsorted array has an undefined result. It's also undefined which element is found if there are multiple occurrences of the same element.

      Parameters

      • The: element type

      • list: the sorted List to search.

      • object: the element to find.

      • comparator: @param comparator the comparator. If the comparator is null then the search uses the objects' natural ordering.

      Returns
      Returns:

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

      Throws
      • ClassCastException: @throws ClassCastException when an element in the list and the searched element cannot be compared to each other using the comparator.

    • copy

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

      Copies the elements from the source list to the destination list. At the end both lists will have the same objects at the same index. If the destination array is larger than the source list, the elements in the destination list with index >= source.size() will be unchanged.

      Parameters

      • destination: the list whose elements are set from the source list.

      • source: the list with the elements to be copied into the destination.

      Throws

      • IndexOutOfBoundsException: when the destination list is smaller than the source list.

      • UnsupportedOperationException: @throws UnsupportedOperationException when replacing an element in the destination list is not supported.

    • enumeration

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

      Returns an Enumeration on the specified collection.

      Parameters
      • collection: the collection to enumerate.
      Returns

      an Enumeration.

    • fill

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

      Fills the specified list with the specified element.

      Parameters

      • list: the list to fill.

      • object: the element to fill the list with.

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

    • max

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

      Searches the specified collection for the maximum element.

      Parameters
      • collection: the collection to search.
      Returns

      the maximum element in the Collection.

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

    • max

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

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

      Parameters

      • collection: the collection to search.

      • comparator: the comparator.

      Returns

      the maximum element in the Collection.

      Throws
      • ClassCastException: @throws ClassCastException when elements in the collection cannot be compared to each other using the Comparator.

    • min

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

      Searches the specified collection for the minimum element.

      Parameters
      • collection: the collection to search.
      Returns

      the minimum element in the collection.

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

    • min

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

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

      Parameters

      • collection: the collection to search.

      • comparator: the comparator.

      Returns

      the minimum element in the collection.

      Throws
      • ClassCastException: @throws ClassCastException when elements in the collection cannot be compared to each other using the Comparator.

    • nCopies

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

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

      Parameters

      • length: the size of the returned list.

      • object: the element to be added length times to a list.

      Returns

      a list containing length copies of the element.

      Throws
      • IllegalArgumentException: when length < 0.

    • reverse

      public static void reverse(List<?> list)

      Modifies the specified List by reversing the order of the elements.

      Parameters
      • list: the list to reverse.
      Throws
      • UnsupportedOperationException: when replacing an element in the List is not supported.

    • reverseOrder

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

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

      Returns

      a Comparator instance.

      See also

      • Comparator

      • Comparable

      • Serializable

    • reverseOrder

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

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

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

      Parameters
      • c: the Comparator to reverse or null.
      Returns

      a Comparator instance.

      Since

      1.5

      See also
      • Comparator

    • shuffle

      public static void shuffle(List<?> list)

      Moves every element of the list to a random new position in the list.

      Parameters
      • list: the List to shuffle.
      Throws
      • UnsupportedOperationException: when replacing an element in the List is not supported.

    • shuffle

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

      Moves every element of the list to a random new position in the list using the specified random number generator.

      Parameters

      • list: the list to shuffle.

      • random: the random number generator.

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

    • singleton

      public static <E> Set<E> singleton(E object)

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

      Parameters
      • object: the element.
      Returns

      a set containing the element.

    • singletonList

      public static <E> List<E> singletonList(E object)

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

      Parameters
      • object: the element.
      Returns

      a list containing the element.

    • singletonMap

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

      Returns a Map containing the specified key and value. The map cannot be modified. The map is serializable.

      Parameters

      • key: the key.

      • value: the value.

      Returns

      a Map containing the key and value.

    • sort

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

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

      Parameters
      • list: the list to be sorted.
      Throws
      • ClassCastException: @throws ClassCastException when an element in the List does not implement Comparable or elements cannot be compared to each other.

    • sort

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

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

      Parameters

      • list: the list to be sorted.

      • comparator: the comparator.

      Throws
      • ClassCastException: @throws ClassCastException when elements in the list cannot be compared to each other using the comparator.

    • swap

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

      Swaps the elements of list list at indices index1 and index2.

      Parameters

      • list: the list to manipulate.

      • index1: @param index1 position of the first element to swap with the element in index2.

      • index2: position of the other element.

      Throws
      • IndexOutOfBoundsException: if index1 or index2 is out of range of this list.
      Since

      1.4

    • replaceAll

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

      Replaces all occurrences of Object obj in list with newObj. If the obj is null, then all occurrences of null are replaced with newObj.

      Parameters

      • list: the list to modify.

      • obj: the object to find and replace occurrences of.

      • obj2: @param obj2 the object to replace all occurrences of obj in list.

      Returns
      Returns:

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

      Throws
      • UnsupportedOperationException: if the list does not support setting elements.

    • rotate

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

      Rotates the elements in list by the distance dist

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

      Parameters

      • lst: the list whose elements are to be rotated.

      • dist: @param dist is the distance the list is rotated. This can be any valid integer. Negative values rotate the list backwards.

    • indexOfSubList

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

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

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

      Parameters

      • list: the List to search sublist in.

      • sublist: the List to search in list.

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

    • lastIndexOfSubList

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

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

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

      Parameters

      • list: the list to search sublist in.

      • sublist: the list to search in list.

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

    • list

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

      Returns an ArrayList with all the elements in the enumeration. The elements in the returned ArrayList are in the same order as in the enumeration.

      Parameters
      • enumeration: the source Enumeration.
      Returns

      an ArrayList from enumeration.

    • synchronizedCollection

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

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

      Parameters
      • collection: the Collection to wrap in a synchronized collection.
      Returns

      a synchronized Collection.

    • synchronizedList

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

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

      Parameters
      • list: the List to wrap in a synchronized list.
      Returns

      a synchronized List.

    • synchronizedMap

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

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

      Parameters
      • map: the map to wrap in a synchronized map.
      Returns

      a synchronized Map.

    • synchronizedSet

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

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

      Parameters
      • set: the set to wrap in a synchronized set.
      Returns

      a synchronized set.

    • synchronizedSortedMap

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

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

      Parameters
      • map: the sorted map to wrap in a synchronized sorted map.
      Returns

      a synchronized sorted map.

    • synchronizedSortedSet

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

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

      Parameters
      • set: the sorted set to wrap in a synchronized sorted set.
      Returns

      a synchronized sorted set.

    • unmodifiableCollection

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

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

      Parameters
      • collection: the collection to wrap in an unmodifiable collection.
      Returns

      an unmodifiable collection.

    • unmodifiableList

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

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

      Parameters
      • list: the list to wrap in an unmodifiable list.
      Returns

      an unmodifiable List.

    • unmodifiableMap

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

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

      Parameters
      • map: the map to wrap in an unmodifiable map.
      Returns

      a unmodifiable map.

    • unmodifiableSet

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

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

      Parameters
      • set: the set to wrap in an unmodifiable set.
      Returns

      a unmodifiable set

    • unmodifiableSortedMap

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

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

      Parameters
      • map: the sorted map to wrap in an unmodifiable sorted map.
      Returns

      a unmodifiable sorted map

    • unmodifiableSortedSet

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

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

      Parameters
      • set: the sorted set to wrap in an unmodifiable sorted set.
      Returns

      a unmodifiable sorted set.

    • frequency

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

      Returns the number of elements in the Collection that match the Object passed. If the Object is null, then the number of null elements is returned.

      Parameters

      • c: the Collection to search.

      • o: the Object to search for.

      Returns

      the number of matching elements.

      Throws
      • NullPointerException: if the Collection parameter is null.
      Since

      1.5

    • emptyList

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

      Returns a type-safe empty, immutable List.

      Returns

      an empty List.

      Since

      1.5

      See also
      • #EMPTY_LIST

    • emptySet

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

      Returns a type-safe empty, immutable Set.

      Returns

      an empty Set.

      Since

      1.5

      See also
      • #EMPTY_SET

    • emptyMap

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

      Returns a type-safe empty, immutable Map.

      Returns

      an empty Map.

      Since

      1.5

      See also
      • #EMPTY_MAP

    • checkedCollection

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

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

      Parameters

      • c: the collection to be wrapped in a typesafe collection.

      • type: the type of the elements permitted to insert.

      Returns

      a typesafe collection.

    • addAll

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

      Adds all the specified elements to the specified collection.

      Parameters

      • c: the collection the elements are to be inserted into.

      • a: the elements to insert.

      Returns

      true if the collection changed during insertion.

      Throws

      • UnsupportedOperationException: when the method is not supported.

      • NullPointerException: @throws NullPointerException when c or a is null, or a contains one or more null elements and c doesn't support null elements.

      • IllegalArgumentException: @throws IllegalArgumentException if at least one of the elements can't be inserted into the collection.

    • disjoint

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

      Returns whether the specified collections have no elements in common.

      Parameters

      • c1: the first collection.

      • c2: the second collection.

      Returns
      Returns:

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

      Throws
      • NullPointerException: if one of the collections is null.

    • newSetFromMap

      public static <E> Set<E> newSetFromMap(Map<E,Boolean> map)
      Answers a set backed by a map. And the map must be empty when this method is called.
      Parameters:
      type -

      of elements in set

      Parameters
      • map: the backing map
      Returns

      the set from the map

      Throws
      • IllegalArgumentException: if the map is not empty
      Since

      1.6

    • asLifoQueue

      public static <T> Queue<T> asLifoQueue(Deque<T> deque)
      Answers a LIFO Queue as a view of a Deque. Methods in the returned Queue need to be re-written to implement the LIFO feature.
      Parameters:
      type -

      of elements

      Parameters
      • deque: the Deque
      Returns

      the LIFO Queue

      Since

      1.6