1 *java.util.Collections* *Collections* This class consists exclusively of static
3 public class Collections
4 extends |java.lang.Object|
6 |java.util.Collections_Description|
7 |java.util.Collections_Fields|
8 |java.util.Collections_Constructors|
9 |java.util.Collections_Methods|
11 ================================================================================
13 *java.util.Collections_Fields*
14 |java.util.List_java.util.Collections.EMPTY_LIST|
15 |java.util.Map_java.util.Collections.EMPTY_MAP|
16 |java.util.Set_java.util.Collections.EMPTY_SET|
18 *java.util.Collections_Methods*
19 |java.util.Collections.addAll(Collection,T[])|Adds all of the specified element
20 |java.util.Collections.binarySearch(List,T)|Searches the specified list for the
21 |java.util.Collections.binarySearch(List,T,Comparator)|Searches the specified l
22 |java.util.Collections.checkedCollection(Collection,Class)|Returns a dynamicall
23 |java.util.Collections.checkedList(List,Class)|Returns a dynamically typesafe v
24 |java.util.Collections.checkedMap(Map,Class,Class)|Returns a dynamically typesa
25 |java.util.Collections.checkedSet(Set,Class)|Returns a dynamically typesafe vie
26 |java.util.Collections.checkedSortedMap(SortedMap,Class,Class)|Returns a dynami
27 |java.util.Collections.checkedSortedSet(SortedSet,Class)|Returns a dynamically
28 |java.util.Collections.copy(List,List)|Copies all of the elements from one list
29 |java.util.Collections.disjoint(Collection,Collection)|Returns true if the two
30 |java.util.Collections.emptyList()|Returns the empty list (immutable).
31 |java.util.Collections.emptyMap()|Returns the empty map (immutable).
32 |java.util.Collections.emptySet()|Returns the empty set (immutable).
33 |java.util.Collections.enumeration(Collection)|Returns an enumeration over the
34 |java.util.Collections.fill(List,T)|Replaces all of the elements of the specifi
35 |java.util.Collections.frequency(Collection,Object)|Returns the number of eleme
36 |java.util.Collections.indexOfSubList(List,List)|Returns the starting position
37 |java.util.Collections.lastIndexOfSubList(List,List)|Returns the starting posit
38 |java.util.Collections.list(Enumeration)|Returns an array list containing the e
39 |java.util.Collections.max(Collection)|Returns the maximum element of the given
40 |java.util.Collections.max(Collection,Comparator)|Returns the maximum element o
41 |java.util.Collections.min(Collection)|Returns the minimum element of the given
42 |java.util.Collections.min(Collection,Comparator)|Returns the minimum element o
43 |java.util.Collections.nCopies(int,T)|Returns an immutable list consisting of n
44 |java.util.Collections.replaceAll(List,T,T)|Replaces all occurrences of one spe
45 |java.util.Collections.reverse(List)|Reverses the order of the elements in the
46 |java.util.Collections.reverseOrder()|Returns a comparator that imposes the rev
47 |java.util.Collections.reverseOrder(Comparator)|Returns a comparator that impos
48 |java.util.Collections.rotate(List,int)|Rotates the elements in the specified l
49 |java.util.Collections.shuffle(List)|Randomly permutes the specified list using
50 |java.util.Collections.shuffle(List,Random)|Randomly permute the specified list
51 |java.util.Collections.singleton(T)|Returns an immutable set containing only th
52 |java.util.Collections.singletonList(T)|Returns an immutable list containing on
53 |java.util.Collections.singletonMap(K,V)|Returns an immutable map, mapping only
54 |java.util.Collections.sort(List)|Sorts the specified list into ascending order
55 |java.util.Collections.sort(List,Comparator)|Sorts the specified list according
56 |java.util.Collections.swap(List,int,int)|Swaps the elements at the specified p
57 |java.util.Collections.synchronizedCollection(Collection)|Returns a synchronize
58 |java.util.Collections.synchronizedList(List)|Returns a synchronized (thread-sa
59 |java.util.Collections.synchronizedMap(Map)|Returns a synchronized (thread-safe
60 |java.util.Collections.synchronizedSet(Set)|Returns a synchronized (thread-safe
61 |java.util.Collections.synchronizedSortedMap(SortedMap)|Returns a synchronized
62 |java.util.Collections.synchronizedSortedSet(SortedSet)|Returns a synchronized
63 |java.util.Collections.unmodifiableCollection(Collection)|Returns an unmodifiab
64 |java.util.Collections.unmodifiableList(List)|Returns an unmodifiable view of t
65 |java.util.Collections.unmodifiableMap(Map)|Returns an unmodifiable view of the
66 |java.util.Collections.unmodifiableSet(Set)|Returns an unmodifiable view of the
67 |java.util.Collections.unmodifiableSortedMap(SortedMap)|Returns an unmodifiable
68 |java.util.Collections.unmodifiableSortedSet(SortedSet)|Returns an unmodifiable
70 *java.util.Collections_Description*
72 This class consists exclusively of static methods that operate on or return
73 collections. It contains polymorphic algorithms that operate on collections,
74 "wrappers", which return a new collection backed by a specified collection, and
75 a few other odds and ends.
77 The methods of this class all throw a NullPointerException if the collections
78 or class objects provided to them are null.
80 The documentation for the polymorphic algorithms contained in this class
81 generally includes a brief description of the implementation. Such descriptions
82 should be regarded as implementation notes, rather than parts of the
83 specification. Implementors should feel free to substitute other algorithms, so
84 long as the specification itself is adhered to. (For example, the algorithm
85 used by sort does not have to be a mergesort, but it does have to be stable.)
87 The "destructive" algorithms contained in this class, that is, the algorithms
88 that modify the collection on which they operate, are specified to throw
89 UnsupportedOperationException if the collection does not support the
90 appropriate mutation primitive(s), such as the set method. These algorithms
91 may, but are not required to, throw this exception if an invocation would have
92 no effect on the collection. For example, invoking the sort method on an
93 unmodifiable list that is already sorted may or may not throw
94 UnsupportedOperationException.
96 This class is a member of the <a href="/../guide/collections/index.html"> Java
97 Collections Framework.
100 *java.util.List_java.util.Collections.EMPTY_LIST*
102 This class consists exclusively of static methods that operate on or return
103 collections. It contains polymorphic algorithms that operate on collections,
104 "wrappers", which return a new collection backed by a specified collection, and
105 a few other odds and ends.
107 The methods of this class all throw a NullPointerException if the collections
108 or class objects provided to them are null.
110 The documentation for the polymorphic algorithms contained in this class
111 generally includes a brief description of the implementation. Such descriptions
112 should be regarded as implementation notes, rather than parts of the
113 specification. Implementors should feel free to substitute other algorithms, so
114 long as the specification itself is adhered to. (For example, the algorithm
115 used by sort does not have to be a mergesort, but it does have to be stable.)
117 The "destructive" algorithms contained in this class, that is, the algorithms
118 that modify the collection on which they operate, are specified to throw
119 UnsupportedOperationException if the collection does not support the
120 appropriate mutation primitive(s), such as the set method. These algorithms
121 may, but are not required to, throw this exception if an invocation would have
122 no effect on the collection. For example, invoking the sort method on an
123 unmodifiable list that is already sorted may or may not throw
124 UnsupportedOperationException.
126 This class is a member of the <a href="/../guide/collections/index.html"> Java
127 Collections Framework.
130 *java.util.Map_java.util.Collections.EMPTY_MAP*
132 This class consists exclusively of static methods that operate on or return
133 collections. It contains polymorphic algorithms that operate on collections,
134 "wrappers", which return a new collection backed by a specified collection, and
135 a few other odds and ends.
137 The methods of this class all throw a NullPointerException if the collections
138 or class objects provided to them are null.
140 The documentation for the polymorphic algorithms contained in this class
141 generally includes a brief description of the implementation. Such descriptions
142 should be regarded as implementation notes, rather than parts of the
143 specification. Implementors should feel free to substitute other algorithms, so
144 long as the specification itself is adhered to. (For example, the algorithm
145 used by sort does not have to be a mergesort, but it does have to be stable.)
147 The "destructive" algorithms contained in this class, that is, the algorithms
148 that modify the collection on which they operate, are specified to throw
149 UnsupportedOperationException if the collection does not support the
150 appropriate mutation primitive(s), such as the set method. These algorithms
151 may, but are not required to, throw this exception if an invocation would have
152 no effect on the collection. For example, invoking the sort method on an
153 unmodifiable list that is already sorted may or may not throw
154 UnsupportedOperationException.
156 This class is a member of the <a href="/../guide/collections/index.html"> Java
157 Collections Framework.
160 *java.util.Set_java.util.Collections.EMPTY_SET*
162 This class consists exclusively of static methods that operate on or return
163 collections. It contains polymorphic algorithms that operate on collections,
164 "wrappers", which return a new collection backed by a specified collection, and
165 a few other odds and ends.
167 The methods of this class all throw a NullPointerException if the collections
168 or class objects provided to them are null.
170 The documentation for the polymorphic algorithms contained in this class
171 generally includes a brief description of the implementation. Such descriptions
172 should be regarded as implementation notes, rather than parts of the
173 specification. Implementors should feel free to substitute other algorithms, so
174 long as the specification itself is adhered to. (For example, the algorithm
175 used by sort does not have to be a mergesort, but it does have to be stable.)
177 The "destructive" algorithms contained in this class, that is, the algorithms
178 that modify the collection on which they operate, are specified to throw
179 UnsupportedOperationException if the collection does not support the
180 appropriate mutation primitive(s), such as the set method. These algorithms
181 may, but are not required to, throw this exception if an invocation would have
182 no effect on the collection. For example, invoking the sort method on an
183 unmodifiable list that is already sorted may or may not throw
184 UnsupportedOperationException.
186 This class is a member of the <a href="/../guide/collections/index.html"> Java
187 Collections Framework.
191 *java.util.Collections.addAll(Collection,T[])*
193 public static boolean addAll(
194 java.util.Collection c,
195 java.lang.Object[] a)
197 Adds all of the specified elements to the specified collection. Elements to be
198 added may be specified individually or as an array. The behavior of this
199 convenience method is identical to that of c.addAll(Arrays.asList(elements)),
200 but this method is likely to run significantly faster under most
203 When elements are specified individually, this method provides a convenient way
204 to add a few elements to an existing collection:
206 Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
208 c - the collection into which elements are to be inserted
209 a - the elements to insert into c
211 Returns: true if the collection changed as a result of the call
212 *java.util.Collections.binarySearch(List,T)*
214 public static int binarySearch(
216 java.lang.Object key)
218 Searches the specified list for the specified object using the binary search
219 algorithm. The list must be sorted into ascending order according to the
220 natural ordering of its elements (as by the sort(List) method, above) prior to
221 making this call. If it is not sorted, the results are undefined. If the list
222 contains multiple elements equal to the specified object, there is no guarantee
223 which one will be found.
225 This method runs in log(n) time for a "random access" list (which provides
226 near-constant-time positional access). If the specified list does not implement
227 the (|java.util.RandomAccess|) interface and is large, this method will do an
228 iterator-based binary search that performs O(n) link traversals and O(log n)
231 list - the list to be searched.
232 key - the key to be searched for.
234 Returns: index of the search key, if it is contained in the list; otherwise,
235 (-(insertion point) - 1). The insertion point is defined as the
236 point at which the key would be inserted into the list: the index
237 of the first element greater than the key, or list.size(), if all
238 elements in the list are less than the specified key. Note that
239 this guarantees that the return value will be >= 0 if and only if
241 *java.util.Collections.binarySearch(List,T,Comparator)*
243 public static int binarySearch(
245 java.lang.Object key,
246 java.util.Comparator c)
248 Searches the specified list for the specified object using the binary search
249 algorithm. The list must be sorted into ascending order according to the
250 specified comparator (as by the Sort(List, Comparator) method, above), prior to
251 making this call. If it is not sorted, the results are undefined. If the list
252 contains multiple elements equal to the specified object, there is no guarantee
253 which one will be found.
255 This method runs in log(n) time for a "random access" list (which provides
256 near-constant-time positional access). If the specified list does not implement
257 the (|java.util.RandomAccess|) interface and is large, this method will do an
258 iterator-based binary search that performs O(n) link traversals and O(log n)
261 list - the list to be searched.
262 key - the key to be searched for.
263 c - the comparator by which the list is ordered. A null value indicates that the
264 elements' natural ordering should be used.
266 Returns: index of the search key, if it is contained in the list; otherwise,
267 (-(insertion point) - 1). The insertion point is defined as the
268 point at which the key would be inserted into the list: the index
269 of the first element greater than the key, or list.size(), if all
270 elements in the list are less than the specified key. Note that
271 this guarantees that the return value will be >= 0 if and only if
273 *java.util.Collections.checkedCollection(Collection,Class)*
275 public static |java.util.Collection| checkedCollection(
276 java.util.Collection c,
277 java.lang.Class type)
279 Returns a dynamically typesafe view of the specified collection. Any attempt to
280 insert an element of the wrong type will result in an immediate
281 ClassCastException. Assuming a collection contains no incorrectly typed
282 elements prior to the time a dynamically typesafe view is generated, and that
283 all subsequent access to the collection takes place through the view, it is
284 guaranteed that the collection cannot contain an incorrectly typed element.
286 The generics mechanism in the language provides compile-time (static) type
287 checking, but it is possible to defeat this mechanism with unchecked casts.
288 Usually this is not a problem, as the compiler issues warnings on all such
289 unchecked operations. There are, however, times when static type checking alone
290 is not sufficient. For example, suppose a collection is passed to a third-party
291 library and it is imperative that the library code not corrupt the collection
292 by inserting an element of the wrong type.
294 Another use of dynamically typesafe views is debugging. Suppose a program fails
295 with a ClassCastException, indicating that an incorrectly typed element was put
296 into a parameterized collection. Unfortunately, the exception can occur at any
297 time after the erroneous element is inserted, so it typically provides little
298 or no information as to the real source of the problem. If the problem is
299 reproducible, one can quickly determine its source by temporarily modifying the
300 program to wrap the collection with a dynamically typesafe view. For example,
303 Collection<String> c = new HashSet<String>();
305 may be replaced temporarily by this one:
307 Collection<String> c = Collections.checkedCollection( new HashSet<String>(),
310 Running the program again will cause it to fail at the point where an
311 incorrectly typed element is inserted into the collection, clearly identifying
312 the source of the problem. Once the problem is fixed, the modified declaration
313 may be reverted back to the original.
315 The returned collection does not pass the hashCode and equals operations
316 through to the backing collection, but relies on Object's equals and hashCode
317 methods. This is necessary to preserve the contracts of these operations in the
318 case that the backing collection is a set or a list.
320 The returned collection will be serializable if the specified collection is
323 c - the collection for which a dynamically typesafe view is to be returned
324 type - the type of element that c is permitted to hold
326 Returns: a dynamically typesafe view of the specified collection
327 *java.util.Collections.checkedList(List,Class)*
329 public static |java.util.List| checkedList(
331 java.lang.Class type)
333 Returns a dynamically typesafe view of the specified list. Any attempt to
334 insert an element of the wrong type will result in an immediate
335 ClassCastException. Assuming a list contains no incorrectly typed elements
336 prior to the time a dynamically typesafe view is generated, and that all
337 subsequent access to the list takes place through the view, it is guaranteed
338 that the list cannot contain an incorrectly typed element.
340 A discussion of the use of dynamically typesafe views may be found in the
341 documentation for the checkedCollection(|java.util.Collections|) method.
343 The returned list will be serializable if the specified list is serializable.
345 list - the list for which a dynamically typesafe view is to be returned
346 type - the type of element that list is permitted to hold
348 Returns: a dynamically typesafe view of the specified list
349 *java.util.Collections.checkedMap(Map,Class,Class)*
351 public static |java.util.Map| checkedMap(
353 java.lang.Class keyType,
354 java.lang.Class valueType)
356 Returns a dynamically typesafe view of the specified map. Any attempt to insert
357 a mapping whose key or value have the wrong type will result in an immediate
358 ClassCastException. Similarly, any attempt to modify the value currently
359 associated with a key will result in an immediate ClassCastException, whether
360 the modification is attempted directly through the map itself, or through a
361 (|java.util.Map.Entry|) instance obtained from the map's entry
362 set(|java.util.Map|) view.
364 Assuming a map contains no incorrectly typed keys or values prior to the time a
365 dynamically typesafe view is generated, and that all subsequent access to the
366 map takes place through the view (or one of its collection views), it is
367 guaranteed that the map cannot contain an incorrectly typed key or value.
369 A discussion of the use of dynamically typesafe views may be found in the
370 documentation for the checkedCollection(|java.util.Collections|) method.
372 The returned map will be serializable if the specified map is serializable.
374 m - the map for which a dynamically typesafe view is to be returned
375 keyType - the type of key that m is permitted to hold
376 valueType - the type of value that m is permitted to hold
378 Returns: a dynamically typesafe view of the specified map
379 *java.util.Collections.checkedSet(Set,Class)*
381 public static |java.util.Set| checkedSet(
383 java.lang.Class type)
385 Returns a dynamically typesafe view of the specified set. Any attempt to insert
386 an element of the wrong type will result in an immediate ClassCastException.
387 Assuming a set contains no incorrectly typed elements prior to the time a
388 dynamically typesafe view is generated, and that all subsequent access to the
389 set takes place through the view, it is guaranteed that the set cannot contain
390 an incorrectly typed element.
392 A discussion of the use of dynamically typesafe views may be found in the
393 documentation for the checkedCollection(|java.util.Collections|) method.
395 The returned set will be serializable if the specified set is serializable.
397 s - the set for which a dynamically typesafe view is to be returned
398 type - the type of element that s is permitted to hold
400 Returns: a dynamically typesafe view of the specified set
401 *java.util.Collections.checkedSortedMap(SortedMap,Class,Class)*
403 public static |java.util.SortedMap| checkedSortedMap(
404 java.util.SortedMap m,
405 java.lang.Class keyType,
406 java.lang.Class valueType)
408 Returns a dynamically typesafe view of the specified sorted map. Any attempt to
409 insert a mapping whose key or value have the wrong type will result in an
410 immediate ClassCastException. Similarly, any attempt to modify the value
411 currently associated with a key will result in an immediate ClassCastException,
412 whether the modification is attempted directly through the map itself, or
413 through a (|java.util.Map.Entry|) instance obtained from the map's entry
414 set(|java.util.Map|) view.
416 Assuming a map contains no incorrectly typed keys or values prior to the time a
417 dynamically typesafe view is generated, and that all subsequent access to the
418 map takes place through the view (or one of its collection views), it is
419 guaranteed that the map cannot contain an incorrectly typed key or value.
421 A discussion of the use of dynamically typesafe views may be found in the
422 documentation for the checkedCollection(|java.util.Collections|) method.
424 The returned map will be serializable if the specified map is serializable.
426 m - the map for which a dynamically typesafe view is to be returned
427 keyType - the type of key that m is permitted to hold
428 valueType - the type of value that m is permitted to hold
430 Returns: a dynamically typesafe view of the specified map
431 *java.util.Collections.checkedSortedSet(SortedSet,Class)*
433 public static |java.util.SortedSet| checkedSortedSet(
434 java.util.SortedSet s,
435 java.lang.Class type)
437 Returns a dynamically typesafe view of the specified sorted set. Any attempt to
438 insert an element of the wrong type will result in an immediate
439 ClassCastException. Assuming a sorted set contains no incorrectly typed
440 elements prior to the time a dynamically typesafe view is generated, and that
441 all subsequent access to the sorted set takes place through the view, it is
442 guaranteed that the sorted set cannot contain an incorrectly typed element.
444 A discussion of the use of dynamically typesafe views may be found in the
445 documentation for the checkedCollection(|java.util.Collections|) method.
447 The returned sorted set will be serializable if the specified sorted set is
450 s - the sorted set for which a dynamically typesafe view is to be returned
451 type - the type of element that s is permitted to hold
453 Returns: a dynamically typesafe view of the specified sorted set
454 *java.util.Collections.copy(List,List)*
456 public static void copy(
460 Copies all of the elements from one list into another. After the operation, the
461 index of each copied element in the destination list will be identical to its
462 index in the source list. The destination list must be at least as long as the
463 source list. If it is longer, the remaining elements in the destination list
466 This method runs in linear time.
468 dest - The destination list.
469 src - The source list.
471 *java.util.Collections.disjoint(Collection,Collection)*
473 public static boolean disjoint(
474 java.util.Collection c1,
475 java.util.Collection c2)
477 Returns true if the two specified collections have no elements in common.
479 Care must be exercised if this method is used on collections that do not comply
480 with the general contract for Collection. Implementations may elect to iterate
481 over either collection and test for containment in the other collection (or to
482 perform any equivalent computation). If either collection uses a nonstandard
483 equality test (as does a (|java.util.SortedSet|) whose ordering is not
484 compatible with equals, or the key set of an (|java.util.IdentityHashMap|) ),
485 both collections must use the same nonstandard equality test, or the result of
486 this method is undefined.
488 Note that it is permissible to pass the same collection in both parameters, in
489 which case the method will return true if and only if the collection is empty.
494 *java.util.Collections.emptyList()*
496 public static final |java.util.List| emptyList()
498 Returns the empty list (immutable). This list is serializable.
500 This example illustrates the type-safe way to obtain an empty list:
502 List<String> s = Collections.emptyList();
504 Implementation note: Implementations of this method need not create a separate
505 List object for each call. Using this method is likely to have comparable cost
506 to using the like-named field. (Unlike this method, the field does not provide
510 *java.util.Collections.emptyMap()*
512 public static final |java.util.Map| emptyMap()
514 Returns the empty map (immutable). This map is serializable.
516 This example illustrates the type-safe way to obtain an empty set:
518 Map<String, Date> s = Collections.emptyMap();
520 Implementation note: Implementations of this method need not create a separate
521 Map object for each call. Using this method is likely to have comparable cost
522 to using the like-named field. (Unlike this method, the field does not provide
526 *java.util.Collections.emptySet()*
528 public static final |java.util.Set| emptySet()
530 Returns the empty set (immutable). This set is serializable. Unlike the
531 like-named field, this method is parameterized.
533 This example illustrates the type-safe way to obtain an empty set:
535 Set<String> s = Collections.emptySet();
537 Implementation note: Implementations of this method need not create a separate
538 Set object for each call. Using this method is likely to have comparable cost
539 to using the like-named field. (Unlike this method, the field does not provide
543 *java.util.Collections.enumeration(Collection)*
545 public static |java.util.Enumeration| enumeration(java.util.Collection c)
547 Returns an enumeration over the specified collection. This provides
548 interoperability with legacy APIs that require an enumeration as input.
550 c - the collection for which an enumeration is to be returned.
552 Returns: an enumeration over the specified collection.
553 *java.util.Collections.fill(List,T)*
555 public static void fill(
557 java.lang.Object obj)
559 Replaces all of the elements of the specified list with the specified element.
561 This method runs in linear time.
563 list - the list to be filled with the specified element.
564 obj - The element with which to fill the specified list.
566 *java.util.Collections.frequency(Collection,Object)*
568 public static int frequency(
569 java.util.Collection c,
572 Returns the number of elements in the specified collection equal to the
573 specified object. More formally, returns the number of elements e in the
574 collection such that (o == null ? e == null : o.equals(e)).
576 c - the collection in which to determine the frequency of o
577 o - the object whose frequency is to be determined
579 *java.util.Collections.indexOfSubList(List,List)*
581 public static int indexOfSubList(
582 java.util.List source,
583 java.util.List target)
585 Returns the starting position of the first occurrence of the specified target
586 list within the specified source list, or -1 if there is no such occurrence.
587 More formally, returns the lowest index i such that source.subList(i,
588 i+target.size()).equals(target), or -1 if there is no such index. (Returns -1
589 if target.size() > source.size().)
591 This implementation uses the "brute force" technique of scanning over the
592 source list, looking for a match with the target at each location in turn.
594 source - the list in which to search for the first occurrence of target.
595 target - the list to search for as a subList of source.
597 Returns: the starting position of the first occurrence of the specified target list
598 within the specified source list, or -1 if there is no such
600 *java.util.Collections.lastIndexOfSubList(List,List)*
602 public static int lastIndexOfSubList(
603 java.util.List source,
604 java.util.List target)
606 Returns the starting position of the last occurrence of the specified target
607 list within the specified source list, or -1 if there is no such occurrence.
608 More formally, returns the highest index i such that source.subList(i,
609 i+target.size()).equals(target), or -1 if there is no such index. (Returns -1
610 if target.size() > source.size().)
612 This implementation uses the "brute force" technique of iterating over the
613 source list, looking for a match with the target at each location in turn.
615 source - the list in which to search for the last occurrence of target.
616 target - the list to search for as a subList of source.
618 Returns: the starting position of the last occurrence of the specified target list
619 within the specified source list, or -1 if there is no such
621 *java.util.Collections.list(Enumeration)*
623 public static |java.util.ArrayList| list(java.util.Enumeration e)
625 Returns an array list containing the elements returned by the specified
626 enumeration in the order they are returned by the enumeration. This method
627 provides interoperability between legacy APIs that return enumerations and new
628 APIs that require collections.
630 e - enumeration providing elements for the returned array list
632 Returns: an array list containing the elements returned by the specified enumeration.
633 *java.util.Collections.max(Collection)*
635 public static |java.lang.Object| max(java.util.Collection coll)
637 Returns the maximum element of the given collection, according to the natural
638 ordering of its elements. All elements in the collection must implement the
639 Comparable interface. Furthermore, all elements in the collection must be
640 mutually comparable (that is, e1.compareTo(e2) must not throw a
641 ClassCastException for any elements e1 and e2 in the collection).
643 This method iterates over the entire collection, hence it requires time
644 proportional to the size of the collection.
646 coll - the collection whose maximum element is to be determined.
648 Returns: the maximum element of the given collection, according to the natural ordering
650 *java.util.Collections.max(Collection,Comparator)*
652 public static |java.lang.Object| max(
653 java.util.Collection coll,
654 java.util.Comparator comp)
656 Returns the maximum element of the given collection, according to the order
657 induced by the specified comparator. All elements in the collection must be
658 mutually comparable by the specified comparator (that is, comp.compare(e1, e2)
659 must not throw a ClassCastException for any elements e1 and e2 in the
662 This method iterates over the entire collection, hence it requires time
663 proportional to the size of the collection.
665 coll - the collection whose maximum element is to be determined.
666 comp - the comparator with which to determine the maximum element. A null value
667 indicates that the elements' natural ordering should be used.
669 Returns: the maximum element of the given collection, according to the specified
671 *java.util.Collections.min(Collection)*
673 public static |java.lang.Object| min(java.util.Collection coll)
675 Returns the minimum element of the given collection, according to the natural
676 ordering of its elements. All elements in the collection must implement the
677 Comparable interface. Furthermore, all elements in the collection must be
678 mutually comparable (that is, e1.compareTo(e2) must not throw a
679 ClassCastException for any elements e1 and e2 in the collection).
681 This method iterates over the entire collection, hence it requires time
682 proportional to the size of the collection.
684 coll - the collection whose minimum element is to be determined.
686 Returns: the minimum element of the given collection, according to the natural ordering
688 *java.util.Collections.min(Collection,Comparator)*
690 public static |java.lang.Object| min(
691 java.util.Collection coll,
692 java.util.Comparator comp)
694 Returns the minimum element of the given collection, according to the order
695 induced by the specified comparator. All elements in the collection must be
696 mutually comparable by the specified comparator (that is, comp.compare(e1, e2)
697 must not throw a ClassCastException for any elements e1 and e2 in the
700 This method iterates over the entire collection, hence it requires time
701 proportional to the size of the collection.
703 coll - the collection whose minimum element is to be determined.
704 comp - the comparator with which to determine the minimum element. A null value
705 indicates that the elements' natural ordering should be used.
707 Returns: the minimum element of the given collection, according to the specified
709 *java.util.Collections.nCopies(int,T)*
711 public static |java.util.List| nCopies(
715 Returns an immutable list consisting of n copies of the specified object. The
716 newly allocated data object is tiny (it contains a single reference to the data
717 object). This method is useful in combination with the List.addAll method to
718 grow lists. The returned list is serializable.
720 n - the number of elements in the returned list.
721 o - the element to appear repeatedly in the returned list.
723 Returns: an immutable list consisting of n copies of the specified object.
724 *java.util.Collections.replaceAll(List,T,T)*
726 public static boolean replaceAll(
728 java.lang.Object oldVal,
729 java.lang.Object newVal)
731 Replaces all occurrences of one specified value in a list with another. More
732 formally, replaces with newVal each element e in list such that (oldVal==null ?
733 e==null : oldVal.equals(e)). (This method has no effect on the size of the
736 list - the list in which replacement is to occur.
737 oldVal - the old value to be replaced.
738 newVal - the new value with which oldVal is to be replaced.
740 Returns: true if list contained one or more elements e such that (oldVal==null ? e==null
742 *java.util.Collections.reverse(List)*
744 public static void reverse(java.util.List list)
746 Reverses the order of the elements in the specified list.
748 This method runs in linear time.
750 list - the list whose elements are to be reversed.
752 *java.util.Collections.reverseOrder()*
754 public static |java.util.Comparator| reverseOrder()
756 Returns a comparator that imposes the reverse of the natural ordering on a
757 collection of objects that implement the Comparable interface. (The natural
758 ordering is the ordering imposed by the objects' own compareTo method.) This
759 enables a simple idiom for sorting (or maintaining) collections (or arrays) of
760 objects that implement the Comparable interface in reverse-natural-order. For
761 example, suppose a is an array of strings. Then:
763 Arrays.sort(a, Collections.reverseOrder());
765 sorts the array in reverse-lexicographic (alphabetical) order.
767 The returned comparator is serializable.
770 Returns: a comparator that imposes the reverse of the natural ordering on a collection
771 of objects that implement the Comparable interface.
772 *java.util.Collections.reverseOrder(Comparator)*
774 public static |java.util.Comparator| reverseOrder(java.util.Comparator cmp)
776 Returns a comparator that imposes the reverse ordering of the specified
777 comparator. If the specified comparator is null, this method is equivalent to
778 (|java.util.Collections|) (in other words, it returns a comparator that imposes
779 the reverse of the natural ordering on a collection of objects that implement
780 the Comparable interface).
782 The returned comparator is serializable (assuming the specified comparator is
783 also serializable or null).
786 Returns: a comparator that imposes the reverse ordering of the specified comparator.
787 *java.util.Collections.rotate(List,int)*
789 public static void rotate(
793 Rotates the elements in the specified list by the specified distance. After
794 calling this method, the element at index i will be the element previously at
795 index (i - distance) mod list.size(), for all values of i between 0 and
796 list.size()-1, inclusive. (This method has no effect on the size of the list.)
798 For example, suppose list comprises [t, a, n, k, s]. After invoking
799 Collections.rotate(list, 1) (or Collections.rotate(list, -4)), list will
800 comprise [s, t, a, n, k].
802 Note that this method can usefully be applied to sublists to move one or more
803 elements within a list while preserving the order of the remaining elements.
804 For example, the following idiom moves the element at index j forward to
805 position k (which must be greater than or equal to j):
807 Collections.rotate(list.subList(j, k+1), -1);
809 To make this concrete, suppose list comprises [a, b, c, d, e]. To move the
810 element at index 1 (b) forward two positions, perform the following invocation:
812 Collections.rotate(l.subList(1, 4), -1);
814 The resulting list is [a, c, d, b, e].
816 To move more than one element forward, increase the absolute value of the
817 rotation distance. To move elements backward, use a positive shift distance.
819 If the specified list is small or implements the (|java.util.RandomAccess|)
820 interface, this implementation exchanges the first element into the location it
821 should go, and then repeatedly exchanges the displaced element into the
822 location it should go until a displaced element is swapped into the first
823 element. If necessary, the process is repeated on the second and successive
824 elements, until the rotation is complete. If the specified list is large and
825 doesn't implement the RandomAccess interface, this implementation breaks the
826 list into two sublist views around index -distance mod size. Then the
827 (|java.util.Collections|) method is invoked on each sublist view, and finally
828 it is invoked on the entire list. For a more complete description of both
829 algorithms, see Section 2.3 of Jon Bentley's Programming Pearls
830 (Addison-Wesley, 1986).
832 list - the list to be rotated.
833 distance - the distance to rotate the list. There are no constraints on this value; it may
834 be zero, negative, or greater than list.size().
836 *java.util.Collections.shuffle(List)*
838 public static void shuffle(java.util.List list)
840 Randomly permutes the specified list using a default source of randomness. All
841 permutations occur with approximately equal likelihood.
843 The hedge "approximately" is used in the foregoing description because default
844 source of randomness is only approximately an unbiased source of independently
845 chosen bits. If it were a perfect source of randomly chosen bits, then the
846 algorithm would choose permutations with perfect uniformity.
848 This implementation traverses the list backwards, from the last element up to
849 the second, repeatedly swapping a randomly selected element into the "current
850 position". Elements are randomly selected from the portion of the list that
851 runs from the first element to the current position, inclusive.
853 This method runs in linear time. If the specified list does not implement the
854 (|java.util.RandomAccess|) interface and is large, this implementation dumps
855 the specified list into an array before shuffling it, and dumps the shuffled
856 array back into the list. This avoids the quadratic behavior that would result
857 from shuffling a "sequential access" list in place.
859 list - the list to be shuffled.
861 *java.util.Collections.shuffle(List,Random)*
863 public static void shuffle(
865 java.util.Random rnd)
867 Randomly permute the specified list using the specified source of randomness.
868 All permutations occur with equal likelihood assuming that the source of
871 This implementation traverses the list backwards, from the last element up to
872 the second, repeatedly swapping a randomly selected element into the "current
873 position". Elements are randomly selected from the portion of the list that
874 runs from the first element to the current position, inclusive.
876 This method runs in linear time. If the specified list does not implement the
877 (|java.util.RandomAccess|) interface and is large, this implementation dumps
878 the specified list into an array before shuffling it, and dumps the shuffled
879 array back into the list. This avoids the quadratic behavior that would result
880 from shuffling a "sequential access" list in place.
882 list - the list to be shuffled.
883 rnd - the source of randomness to use to shuffle the list.
885 *java.util.Collections.singleton(T)*
887 public static |java.util.Set| singleton(java.lang.Object o)
889 Returns an immutable set containing only the specified object. The returned set
892 o - the sole object to be stored in the returned set.
894 Returns: an immutable set containing only the specified object.
895 *java.util.Collections.singletonList(T)*
897 public static |java.util.List| singletonList(java.lang.Object o)
899 Returns an immutable list containing only the specified object. The returned
900 list is serializable.
902 o - the sole object to be stored in the returned list.
904 Returns: an immutable list containing only the specified object.
905 *java.util.Collections.singletonMap(K,V)*
907 public static |java.util.Map| singletonMap(
908 java.lang.Object key,
909 java.lang.Object value)
911 Returns an immutable map, mapping only the specified key to the specified
912 value. The returned map is serializable.
914 key - the sole key to be stored in the returned map.
915 value - the value to which the returned map maps key.
917 Returns: an immutable map containing only the specified key-value mapping.
918 *java.util.Collections.sort(List)*
920 public static void sort(java.util.List list)
922 Sorts the specified list into ascending order, according to the natural
923 ordering of its elements. All elements in the list must implement the
924 Comparable interface. Furthermore, all elements in the list must be mutually
925 comparable (that is, e1.compareTo(e2) must not throw a ClassCastException for
926 any elements e1 and e2 in the list).
928 This sort is guaranteed to be stable: equal elements will not be reordered as a
931 The specified list must be modifiable, but need not be resizable.
933 The sorting algorithm is a modified mergesort (in which the merge is omitted if
934 the highest element in the low sublist is less than the lowest element in the
935 high sublist). This algorithm offers guaranteed n log(n) performance.
937 This implementation dumps the specified list into an array, sorts the array,
938 and iterates over the list resetting each element from the corresponding
939 position in the array. This avoids the n2 log(n) performance that would result
940 from attempting to sort a linked list in place.
942 list - the list to be sorted.
944 *java.util.Collections.sort(List,Comparator)*
946 public static void sort(
948 java.util.Comparator c)
950 Sorts the specified list according to the order induced by the specified
951 comparator. All elements in the list must be mutually comparable using the
952 specified comparator (that is, c.compare(e1, e2) must not throw a
953 ClassCastException for any elements e1 and e2 in the list).
955 This sort is guaranteed to be stable: equal elements will not be reordered as a
958 The sorting algorithm is a modified mergesort (in which the merge is omitted if
959 the highest element in the low sublist is less than the lowest element in the
960 high sublist). This algorithm offers guaranteed n log(n) performance.
962 The specified list must be modifiable, but need not be resizable. This
963 implementation dumps the specified list into an array, sorts the array, and
964 iterates over the list resetting each element from the corresponding position
965 in the array. This avoids the n2 log(n) performance that would result from
966 attempting to sort a linked list in place.
968 list - the list to be sorted.
969 c - the comparator to determine the order of the list. A null value indicates that
970 the elements' natural ordering should be used.
972 *java.util.Collections.swap(List,int,int)*
974 public static void swap(
979 Swaps the elements at the specified positions in the specified list. (If the
980 specified positions are equal, invoking this method leaves the list unchanged.)
982 list - The list in which to swap elements.
983 i - the index of one element to be swapped.
984 j - the index of the other element to be swapped.
986 *java.util.Collections.synchronizedCollection(Collection)*
988 public static |java.util.Collection| synchronizedCollection(java.util.Collection c)
990 Returns a synchronized (thread-safe) collection backed by the specified
991 collection. In order to guarantee serial access, it is critical that all access
992 to the backing collection is accomplished through the returned collection.
994 It is imperative that the user manually synchronize on the returned collection
995 when iterating over it:
997 Collection c = Collections.synchronizedCollection(myCollection); ...
998 synchronized(c) { Iterator i = c.iterator(); // Must be in the synchronized
999 block while (i.hasNext()) foo(i.next()); }
1001 Failure to follow this advice may result in non-deterministic behavior.
1003 The returned collection does not pass the hashCode and equals operations
1004 through to the backing collection, but relies on Object's equals and hashCode
1005 methods. This is necessary to preserve the contracts of these operations in the
1006 case that the backing collection is a set or a list.
1008 The returned collection will be serializable if the specified collection is
1011 c - the collection to be "wrapped" in a synchronized collection.
1013 Returns: a synchronized view of the specified collection.
1014 *java.util.Collections.synchronizedList(List)*
1016 public static |java.util.List| synchronizedList(java.util.List list)
1018 Returns a synchronized (thread-safe) list backed by the specified list. In
1019 order to guarantee serial access, it is critical that all access to the backing
1020 list is accomplished through the returned list.
1022 It is imperative that the user manually synchronize on the returned list when
1025 List list = Collections.synchronizedList(new ArrayList()); ...
1026 synchronized(list) { Iterator i = list.iterator(); // Must be in synchronized
1027 block while (i.hasNext()) foo(i.next()); }
1029 Failure to follow this advice may result in non-deterministic behavior.
1031 The returned list will be serializable if the specified list is serializable.
1033 list - the list to be "wrapped" in a synchronized list.
1035 Returns: a synchronized view of the specified list.
1036 *java.util.Collections.synchronizedMap(Map)*
1038 public static |java.util.Map| synchronizedMap(java.util.Map m)
1040 Returns a synchronized (thread-safe) map backed by the specified map. In order
1041 to guarantee serial access, it is critical that all access to the backing map
1042 is accomplished through the returned map.
1044 It is imperative that the user manually synchronize on the returned map when
1045 iterating over any of its collection views:
1047 Map m = Collections.synchronizedMap(new HashMap()); ... Set s = m.keySet(); //
1048 Needn't be in synchronized block ... synchronized(m) { // Synchronizing on m,
1049 not s! Iterator i = s.iterator(); // Must be in synchronized block while
1050 (i.hasNext()) foo(i.next()); }
1052 Failure to follow this advice may result in non-deterministic behavior.
1054 The returned map will be serializable if the specified map is serializable.
1056 m - the map to be "wrapped" in a synchronized map.
1058 Returns: a synchronized view of the specified map.
1059 *java.util.Collections.synchronizedSet(Set)*
1061 public static |java.util.Set| synchronizedSet(java.util.Set s)
1063 Returns a synchronized (thread-safe) set backed by the specified set. In order
1064 to guarantee serial access, it is critical that all access to the backing set
1065 is accomplished through the returned set.
1067 It is imperative that the user manually synchronize on the returned set when
1070 Set s = Collections.synchronizedSet(new HashSet()); ... synchronized(s) {
1071 Iterator i = s.iterator(); // Must be in the synchronized block while
1072 (i.hasNext()) foo(i.next()); }
1074 Failure to follow this advice may result in non-deterministic behavior.
1076 The returned set will be serializable if the specified set is serializable.
1078 s - the set to be "wrapped" in a synchronized set.
1080 Returns: a synchronized view of the specified set.
1081 *java.util.Collections.synchronizedSortedMap(SortedMap)*
1083 public static |java.util.SortedMap| synchronizedSortedMap(java.util.SortedMap m)
1085 Returns a synchronized (thread-safe) sorted map backed by the specified sorted
1086 map. In order to guarantee serial access, it is critical that all access to the
1087 backing sorted map is accomplished through the returned sorted map (or its
1090 It is imperative that the user manually synchronize on the returned sorted map
1091 when iterating over any of its collection views, or the collections views of
1092 any of its subMap, headMap or tailMap views.
1094 SortedMap m = Collections.synchronizedSortedMap(new HashSortedMap()); ... Set s
1095 = m.keySet(); // Needn't be in synchronized block ... synchronized(m) { //
1096 Synchronizing on m, not s! Iterator i = s.iterator(); // Must be in
1097 synchronized block while (i.hasNext()) foo(i.next()); }
1101 SortedMap m = Collections.synchronizedSortedMap(new HashSortedMap()); SortedMap
1102 m2 = m.subMap(foo, bar); ... Set s2 = m2.keySet(); // Needn't be in
1103 synchronized block ... synchronized(m) { // Synchronizing on m, not m2 or s2!
1104 Iterator i = s.iterator(); // Must be in synchronized block while (i.hasNext())
1107 Failure to follow this advice may result in non-deterministic behavior.
1109 The returned sorted map will be serializable if the specified sorted map is
1112 m - the sorted map to be "wrapped" in a synchronized sorted map.
1114 Returns: a synchronized view of the specified sorted map.
1115 *java.util.Collections.synchronizedSortedSet(SortedSet)*
1117 public static |java.util.SortedSet| synchronizedSortedSet(java.util.SortedSet s)
1119 Returns a synchronized (thread-safe) sorted set backed by the specified sorted
1120 set. In order to guarantee serial access, it is critical that all access to the
1121 backing sorted set is accomplished through the returned sorted set (or its
1124 It is imperative that the user manually synchronize on the returned sorted set
1125 when iterating over it or any of its subSet, headSet, or tailSet views.
1127 SortedSet s = Collections.synchronizedSortedSet(new HashSortedSet()); ...
1128 synchronized(s) { Iterator i = s.iterator(); // Must be in the synchronized
1129 block while (i.hasNext()) foo(i.next()); }
1133 SortedSet s = Collections.synchronizedSortedSet(new HashSortedSet()); SortedSet
1134 s2 = s.headSet(foo); ... synchronized(s) { // Note: s, not s2!!! Iterator i =
1135 s2.iterator(); // Must be in the synchronized block while (i.hasNext())
1138 Failure to follow this advice may result in non-deterministic behavior.
1140 The returned sorted set will be serializable if the specified sorted set is
1143 s - the sorted set to be "wrapped" in a synchronized sorted set.
1145 Returns: a synchronized view of the specified sorted set.
1146 *java.util.Collections.unmodifiableCollection(Collection)*
1148 public static |java.util.Collection| unmodifiableCollection(java.util.Collection c)
1150 Returns an unmodifiable view of the specified collection. This method allows
1151 modules to provide users with "read-only" access to internal collections. Query
1152 operations on the returned collection "read through" to the specified
1153 collection, and attempts to modify the returned collection, whether direct or
1154 via its iterator, result in an UnsupportedOperationException.
1156 The returned collection does not pass the hashCode and equals operations
1157 through to the backing collection, but relies on Object's equals and hashCode
1158 methods. This is necessary to preserve the contracts of these operations in the
1159 case that the backing collection is a set or a list.
1161 The returned collection will be serializable if the specified collection is
1164 c - the collection for which an unmodifiable view is to be returned.
1166 Returns: an unmodifiable view of the specified collection.
1167 *java.util.Collections.unmodifiableList(List)*
1169 public static |java.util.List| unmodifiableList(java.util.List list)
1171 Returns an unmodifiable view of the specified list. This method allows modules
1172 to provide users with "read-only" access to internal lists. Query operations on
1173 the returned list "read through" to the specified list, and attempts to modify
1174 the returned list, whether direct or via its iterator, result in an
1175 UnsupportedOperationException.
1177 The returned list will be serializable if the specified list is serializable.
1178 Similarly, the returned list will implement (|java.util.RandomAccess|) if the
1179 specified list does.
1181 list - the list for which an unmodifiable view is to be returned.
1183 Returns: an unmodifiable view of the specified list.
1184 *java.util.Collections.unmodifiableMap(Map)*
1186 public static |java.util.Map| unmodifiableMap(java.util.Map m)
1188 Returns an unmodifiable view of the specified map. This method allows modules
1189 to provide users with "read-only" access to internal maps. Query operations on
1190 the returned map "read through" to the specified map, and attempts to modify
1191 the returned map, whether direct or via its collection views, result in an
1192 UnsupportedOperationException.
1194 The returned map will be serializable if the specified map is serializable.
1196 m - the map for which an unmodifiable view is to be returned.
1198 Returns: an unmodifiable view of the specified map.
1199 *java.util.Collections.unmodifiableSet(Set)*
1201 public static |java.util.Set| unmodifiableSet(java.util.Set s)
1203 Returns an unmodifiable view of the specified set. This method allows modules
1204 to provide users with "read-only" access to internal sets. Query operations on
1205 the returned set "read through" to the specified set, and attempts to modify
1206 the returned set, whether direct or via its iterator, result in an
1207 UnsupportedOperationException.
1209 The returned set will be serializable if the specified set is serializable.
1211 s - the set for which an unmodifiable view is to be returned.
1213 Returns: an unmodifiable view of the specified set.
1214 *java.util.Collections.unmodifiableSortedMap(SortedMap)*
1216 public static |java.util.SortedMap| unmodifiableSortedMap(java.util.SortedMap m)
1218 Returns an unmodifiable view of the specified sorted map. This method allows
1219 modules to provide users with "read-only" access to internal sorted maps. Query
1220 operations on the returned sorted map "read through" to the specified sorted
1221 map. Attempts to modify the returned sorted map, whether direct, via its
1222 collection views, or via its subMap, headMap, or tailMap views, result in an
1223 UnsupportedOperationException.
1225 The returned sorted map will be serializable if the specified sorted map is
1228 m - the sorted map for which an unmodifiable view is to be returned.
1230 Returns: an unmodifiable view of the specified sorted map.
1231 *java.util.Collections.unmodifiableSortedSet(SortedSet)*
1233 public static |java.util.SortedSet| unmodifiableSortedSet(java.util.SortedSet s)
1235 Returns an unmodifiable view of the specified sorted set. This method allows
1236 modules to provide users with "read-only" access to internal sorted sets. Query
1237 operations on the returned sorted set "read through" to the specified sorted
1238 set. Attempts to modify the returned sorted set, whether direct, via its
1239 iterator, or via its subSet, headSet, or tailSet views, result in an
1240 UnsupportedOperationException.
1242 The returned sorted set will be serializable if the specified sorted set is
1245 s - the sorted set for which an unmodifiable view is to be returned.
1247 Returns: an unmodifiable view of the specified sorted set.