Build 1.0_r1(from source)

java.util
Class Collections

java.lang.Object
  extended by java.util.Collections

public class Collections
extends Object

Collections contains static methods which operate on Collection classes.

Since:
1.2

Nested Class Summary
(package private) static class Collections.SynchronizedCollection<E>
           
(package private) static class Collections.SynchronizedList<E>
           
(package private) static class Collections.SynchronizedMap<K,V>
           
(package private) static class Collections.SynchronizedRandomAccessList<E>
           
(package private) static class Collections.SynchronizedSet<E>
           
(package private) static class Collections.SynchronizedSortedMap<K,V>
           
(package private) static class Collections.SynchronizedSortedSet<E>
           
 
Field Summary
static List EMPTY_LIST
           
static Map EMPTY_MAP
           
static Set EMPTY_SET
           
 
Method Summary
static
<T> boolean
addAll(Collection<? super T> c, T... a)
          Adds all the specified elements to the specified collection
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.
(package private) static
<E> E
checkType(E obj, Class<E> type)
          Checks if specified object is instance of specified class.
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 true if the collections have no elements in common
static
<T> List<T>
emptyList()
          Returns a type-safe empty, immutable List.
static
<K,V> Map<K,V>
emptyMap()
          Returns a type-safe empty, immutable Map.
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 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
<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)
          Returns the supplied List with the order of its contained elements reversed.
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 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 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 SortedMap which synchronizes all access to the SortedMap.
static
<E> SortedSet<E>
synchronizedSortedSet(SortedSet<E> set)
          Returns a wrapper on the specified SortedSet which synchronizes all access to the SortedSet.
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 SortedMap which throws an UnsupportedOperationException whenever an attempt is made to modify the SortedMap.
static
<E> SortedSet<E>
unmodifiableSortedSet(SortedSet<E> set)
          Returns a wrapper on the specified SortedSet which throws an UnsupportedOperationException whenever an attempt is made to modify the SortedSet.
 
Methods inherited from class java.lang.Object
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Field Detail

EMPTY_LIST

public static final List EMPTY_LIST

EMPTY_SET

public static final Set EMPTY_SET

EMPTY_MAP

public static final Map EMPTY_MAP
Method Detail

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.

Parameters:
list - the sorted List to search
object - the element to find
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 - when 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.

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

Parameters:
destination -
source -
Throws:
IndexOutOfBoundsException - when the destination List is smaller than the source List
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 fill element
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 - 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 - 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 - 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 - 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.

Parameters:
length - the size of the returned List
object - the element
Returns:
a List containing length copies of the element
Throws:
IllegalArgumentException - when length <>

reverse

public static void reverse(List<?> list)
Returns the supplied List with the order of its contained elements reversed.

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.

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.

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.

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 order.

Parameters:
list - the List to be sorted
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.

Parameters:
list - the List to be sorted
comparator - the Comparator
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 on
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

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 is replaced with newObj.

Parameters:
list - the List to modify
obj - the Object to find and replace occurrences of.
obj2 - the Object to replace all occurrences of obj in list
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 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 -
dist - It can be any integer: 0, positive, negative, larger than the list size

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:
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:
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 - Enumeration
Returns:
and ArrayList

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
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
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
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
Returns:
a synchronized Set

synchronizedSortedMap

public static <K,V> SortedMap<K,V> synchronizedSortedMap(SortedMap<K,V> map)
Returns a wrapper on the specified SortedMap which synchronizes all access to the SortedMap.

Parameters:
map - the SortedMap
Returns:
a synchronized SortedMap

synchronizedSortedSet

public static <E> SortedSet<E> synchronizedSortedSet(SortedSet<E> set)
Returns a wrapper on the specified SortedSet which synchronizes all access to the SortedSet.

Parameters:
set - the SortedSet
Returns:
a synchronized SortedSet

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
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
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
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
Returns:
a unmodifiable Set

unmodifiableSortedMap

public static <K,V> SortedMap<K,V> unmodifiableSortedMap(SortedMap<K,? extends V> map)
Returns a wrapper on the specified SortedMap which throws an UnsupportedOperationException whenever an attempt is made to modify the SortedMap.

Parameters:
map - the SortedMap
Returns:
a unmodifiable SortedMap

unmodifiableSortedSet

public static <E> SortedSet<E> unmodifiableSortedSet(SortedSet<E> set)
Returns a wrapper on the specified SortedSet which throws an UnsupportedOperationException whenever an attempt is made to modify the SortedSet.

Parameters:
set - the SortedSet
Returns:
a unmodifiable SortedSet

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.

Parameters:
c - the collection
type - the type of the elements permitted to insert
Returns:
a typesafe collection

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 specified map.

Parameters:
m - the map
keyType - the type of the keys permitted to insert
valueType - the type of the values permitted to insert
Returns:
a typesafe map

checkedList

public static <E> List<E> checkedList(List<E> list,
                                      Class<E> type)
Returns a dynamically typesafe view of the specified list.

Parameters:
list - the list
type - the type of the elements permitted to insert
Returns:
a typesafe list

checkedSet

public static <E> Set<E> checkedSet(Set<E> s,
                                    Class<E> type)
Returns a dynamically typesafe view of the specified set.

Parameters:
s - the set
type - the type of the elements permitted to insert
Returns:
a typesafe set

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 specified sorted map.

Parameters:
m - the sorted map
keyType - the type of the keys permitted to insert
valueType - the type of the values permitted to insert
Returns:
a typesafe sorted map

checkedSortedSet

public static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s,
                                                Class<E> type)
Returns a dynamically typesafe view of the specified sorted set.

Parameters:
s - the sorted set
type - the type of the elements permitted to insert
Returns:
a typesafe sorted set

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 - when c or elements is null, or elements contains one or more null elements and c doesn't support null elements

disjoint

public static boolean disjoint(Collection<?> c1,
                               Collection<?> c2)
Returns true if the collections have no elements in common

Parameters:
c1 - the first collection
c2 - the second collection
Returns:
true if the collections have no elements in common
Throws:
NullPointerException - if one of the collections is null

checkType

static <E> E checkType(E obj,
                       Class<E> type)
Checks if specified object is instance of specified class. Used for a dynamically typesafe view of the collections.

Parameters:
obj - - object is to be checked
type - - class of object that should be
Returns:
specified object

Build 1.0_r1(from source)

Please submit a feedback, bug or feature