Question

java.lang.Object
  └java.util.Collections

---

public class Collections

extends Object

此类完全由在 collection 上进行操作或返回 collection 的静态方法组成。它包含在 collection 上操作的多态算法，即“包装器”，包装器返回由指定 collection 支持的新 collection，以及少数其他内容。

如果为此类的方法所提供的 collection 或类对象为 null，则这些方法都会抛出 NullPointerException 。

此类中所含多态算法的文档通常都包括对实现 的简短描述。应该将这类实现视为实现注意事项，而不是将它们视为规范 的一部分。实现者应该可以随意使用其他算法替代，只要遵循规范本身即可。（例如， sort 使用的算法不一定是一个合并排序算法，但它必须是稳定的。）

如果该 collection 不支持适当的可变基元，比如 set 方法，则此类中包含的“破坏性”算法，即可修改其所操作的 collection 的算法，被指定抛出 UnsupportedOperationException 。如果调用不会对 collection 产生任何影响，那么这些算法可能（但不一定）抛出此异常。例如，在已经排序的、不可修改列表上调用 sort 方法可能会（也可能不会）抛出 UnsupportedOperationException 。

此类是 Java Collections Framework 的成员。

从以下版本开始：

1.2

另请参见：

Collection , Set , List , Map

---

字段摘要
staticList	EMPTY_LIST 空的列表（不可变的）。
staticMap	EMPTY_MAP 空的映射（不可变的）。
staticSet	EMPTY_SET 空的 set（不可变的）。

方法摘要
static <T> boolean	addAll(Collection<? super T>c, T...a) 将所有指定元素添加到指定 collection 中。
static <T> int	binarySearch(List<? extends Comparable<? super T>>list, Tkey) 使用二进制搜索算法来搜索指定列表，以获得指定对象。
static <T> int	binarySearch(List<? extends T>list, Tkey, Comparator<? super T>c) 使用二进制搜索算法来搜索指定列表，以获得指定对象。
static <E> Collection<E>	checkedCollection(Collection<E>c, Class<E>type) 返回指定 collection 的一个动态类型安全视图。
static <E> List<E>	checkedList(List<E>list, Class<E>type) 返回指定列表的一个动态类型安全视图。
static <K,V> Map<K,V>	checkedMap(Map<K,V>m, Class<K>keyType, Class<V>valueType) 返回指定映射的一个动态类型安全视图。
static <E> Set<E>	checkedSet(Set<E>s, Class<E>type) 返回指定 set 的一个动态类型安全视图。
static <K,V> SortedMap<K,V>	checkedSortedMap(SortedMap<K,V>m, Class<K>keyType, Class<V>valueType) 返回指定有序映射的一个动态类型安全视图。
static <E> SortedSet<E>	checkedSortedSet(SortedSet<E>s, Class<E>type) 返回指定有序 set 的一个动态类型安全视图。
static <T> void	copy(List<? super T>dest, List<? extends T>src) 将所有元素从一个列表复制到另一个列表。
staticboolean	disjoint(Collection<?>c1, Collection<?>c2) 如果两个指定 collection 中没有相同的元素，则返回 true 。
static <T> List<T>	emptyList() 返回空的列表（不可变的）。
static <K,V> Map<K,V>	emptyMap() 返回空的映射（不可变的）。
static <T> Set<T>	emptySet() 返回空的 set（不可变的）。
static <T> Enumeration<T>	enumeration(Collection<T>c) 返回一个指定 collection 上的枚举。
static <T> void	fill(List<? super T>list, Tobj) 使用指定元素替换指定列表中的所有元素。
staticint	frequency(Collection<?>c, Objecto) 返回指定 collection 中等于指定对象的元素数。
staticint	indexOfSubList(List<?>source, List<?>target) 返回指定源列表中第一次出现指定目标列表的起始位置，如果没有出现这样的列表，则返回 -1。
staticint	lastIndexOfSubList(List<?>source, List<?>target) 返回指定源列表中最后一次出现指定目标列表的起始位置，如果没有出现这样的列表，则返回 -1。
static <T> ArrayList<T>	list(Enumeration<T>e) 返回一个数组列表，它按照枚举返回元素的顺序包含指定枚举返回的元素。
static <T extends Object & Comparable<? super T>> T	max(Collection<? extends T>coll) 根据元素的自然顺序，返回给定 collection 的最大元素。
static <T> T	max(Collection<? extends T>coll, Comparator<? super T>comp) 根据指定比较器产生的顺序，返回给定 collection 的最大元素。
static <T extends Object & Comparable<? super T>> T	min(Collection<? extends T>coll) 根据元素的自然顺序 返回给定 collection 的最小元素。
static <T> T	min(Collection<? extends T>coll, Comparator<? super T>comp) 根据指定比较器产生的顺序，返回给定 collection 的最小元素。
static <T> List<T>	nCopies(intn, To) 返回由指定对象的 n 个副本组成的不可变列表。
static <T> boolean	replaceAll(List<T>list, ToldVal, TnewVal) 使用另一个值替换列表中出现的所有某一指定值。
staticvoid	reverse(List<?>list) 反转指定列表中元素的顺序。
static <T> Comparator<T>	reverseOrder() 返回一个比较器，它强行反转实现 Comparable 接口那些对象 collection 上的自然顺序。
static <T> Comparator<T>	reverseOrder(Comparator<T>cmp) 返回一个比较器，它强行反转指定比较器的顺序。
staticvoid	rotate(List<?>list, intdistance) 根据指定的距离循环移动指定列表中的元素。
staticvoid	shuffle(List<?>list) 使用默认随机源随机更改指定列表的序列。
staticvoid	shuffle(List<?>list, Randomrnd) 使用指定的随机源随机更改指定列表的序列。
static <T> Set<T>	singleton(To) 返回一个只包含指定对象的不可变 set。
static <T> List<T>	singletonList(To) 返回一个只包含指定对象的不可变列表。
static <K,V> Map<K,V>	singletonMap(Kkey, Vvalue) 返回一个不可变的映射，它只将指定键映射到指定值。
static <T extends Comparable<? super T>> void	sort(List<T>list) 根据元素的自然顺序 对指定列表按升序进行排序。
static <T> void	sort(List<T>list, Comparator<? super T>c) 根据指定比较器产生的顺序对指定列表进行排序。
staticvoid	swap(List<?>list, inti, intj) 在指定列表的指定位置处交换元素。
static <T> Collection<T>	synchronizedCollection(Collection<T>c) 返回由指定 collection 支持的同步（线程安全的）collection。
static <T> List<T>	synchronizedList(List<T>list) 返回由指定列表支持的同步（线程安全的）列表。
static <K,V> Map<K,V>	synchronizedMap(Map<K,V>m) 返回由指定映射支持的同步（线程安全的）映射。
static <T> Set<T>	synchronizedSet(Set<T>s) 返回由指定 set 支持的同步（线程安全的）set。
static <K,V> SortedMap<K,V>	synchronizedSortedMap(SortedMap<K,V>m) 返回由指定有序映射支持的同步（线程安全的）有序映射。
static <T> SortedSet<T>	synchronizedSortedSet(SortedSet<T>s) 返回由指定有序 set 支持的同步（线程安全的）有序 set。
static <T> Collection<T>	unmodifiableCollection(Collection<? extends T>c) 返回指定 collection 的不可修改视图。
static <T> List<T>	unmodifiableList(List<? extends T>list) 返回指定列表的不可修改视图。
static <K,V> Map<K,V>	unmodifiableMap(Map<? extends K,? extends V>m) 返回指定映射的不可修改视图。
static <T> Set<T>	unmodifiableSet(Set<? extends T>s) 返回指定 set 的不可修改视图。
static <K,V> SortedMap<K,V>	unmodifiableSortedMap(SortedMap<K,? extends V>m) 返回指定有序映射的不可修改视图。
static <T> SortedSet<T>	unmodifiableSortedSet(SortedSet<T>s) 返回指定有序 set 的不可修改视图。

从类 java.lang.Object 继承的方法
clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

字段详细信息

EMPTY_SET

public static final Set EMPTY_SET

空的 set（不可变的）。此 set 是可序列化的。

另请参见：

emptySet()

---

EMPTY_LIST

public static final List EMPTY_LIST

空的列表（不可变的）。此列表是可序列化的。

另请参见：

emptyList()

---

EMPTY_MAP

public static final Map EMPTY_MAP

空的映射（不可变的）。此映射是可序列化的。

从以下版本开始：

1.3

另请参见：

emptyMap()

方法详细信息

sort

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

根据元素的自然顺序 对指定列表按升序进行排序。列表中的所有元素都必须实现 Comparable 接口。此外，列表中的所有元素都必须是可相互比较的（也就是说，对于列表中的任何 e1 和 e2 元素， e1.compareTo(e2) 不得抛出 ClassCastException ）。

此排序被保证是稳定的：不会因调用 sort 方法而对相等的元素进行重新排序。

指定列表必须是可修改的，但不必是大小可调整的。

该排序算法是一个经过修改的合并排序算法（其中，如果低子列表中的最高元素小于高子列表中的最低元素，则忽略合并）。此算法提供可保证的 n log(n) 性能。

此实现将指定列表转储到一个数组中，并对数组进行排序，在重置数组中相应位置处每个元素的列表上进行迭代。这避免了由于试图对适当位置上的链接列表进行排序而产生的 n² log(n) 性能。

参数：

list - 要排序的列表。

抛出：

ClassCastException - 如果列表包含不可相互比较的 的元素（例如，字符串和整数）。

UnsupportedOperationException - 如果指定列表的列表迭代器不支持 set 操作。

另请参见：

Comparable

---

sort

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

根据指定比较器产生的顺序对指定列表进行排序。此列表内的所有元素都必须是使用指定比较器可相互比较的（也就是说，对于列表中的任何 e1 和 e2 元素， c.compare(e1, e2) 不得抛出 ClassCastException ）。

此排序被保证是稳定的：不会因调用 sort 方法而对相等的元素进行重新排序。

排序算法是一个经过修改的合并排序算法（其中，如果低子列表中的最高元素小于高子列表中的最低元素，则忽略合并）。此算法提供可保证的 n log(n) 性能。

指定列表必须是可修改的，但不必是可大小调整的。此实现将指定列表转储到一个数组中，并对数组进行排序，在重置数组中相应位置处每个元素的列表上进行迭代。这避免了由于试图对适当位置上的链接列表进行排序而产生的 n² log(n) 性能。

参数：

list - 要排序的列表。

c - 确定列表顺序的比较器。 null 值指示应该使用的元素的自然顺序。

抛出：

ClassCastException - 如果列表中包含使用指定的比较器不可相互比较的 的元素。

UnsupportedOperationException - 如果指定列表的列表迭代器不支持 set 操作。

另请参见：

Comparator

---

binarySearch

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

使用二进制搜索算法来搜索指定列表，以获得指定对象。在进行此调用之前，必须根据列表元素的自然顺序 对列表进行升序排序（通过上面的 sort(List) 方法）。如果没有对列表进行排序，则结果是不明确的。如果列表包含多个等于指定对象的元素，则无法保证找到的是哪一个。

此方法对“随机访问”的列表运行 log(n) 次（它提供了一个接近固定时间的位置访问）。如果指定列表没有实现 RandomAccess 接口并且是一个大型列表，则此方法将执行基于迭代器的二进制搜索，执行 O(n) 次链接遍历和 O(log n) 次元素比较。

参数：

list - 要搜索的列表。

key - 要搜索的键。

返回：

如果搜索键包含在列表中，则返回搜索键的索引；否则返回 (-(插入点) - 1) 。插入点 被定义为将键插入列表的那一点：即第一个大于此键的元素索引，或者如果列表中的所有元素都小于指定的键，则为 list.size() 。注意，这保证了当且仅当此键被找到时，返回的值将 >= 0。

抛出：

ClassCastException - 如果列表中包含不可相互比较 的元素（例如，字符串和整数），或者搜索键无法与列表的元素进行相互比较。

另请参见：

Comparable , sort(List)

---

binarySearch

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

使用二进制搜索算法来搜索指定列表，以获得指定对象。在进行此调用之前，必须根据指定的比较器（通过上面的 Sort(List, Comparator) 方法）对列表进行升序排序。如果没有对列表进行排序，则结果是不明确的。如果列表包含多个等于指定对象的元素，则无法保证找到的是哪一个。

此方法对“随机访问”的列表运行 log(n) 次（这提供了一个接近固定时间的位置访问）。如果指定列表没有实现 RandomAccess 接口并且是一个大型列表，则此方法将执行基于迭代器的二进制搜索，执行 O(n) 次链接遍历和 O(log n) 次元素比较。

参数：

list - 要搜索的列表。

key - 要搜索的键。

c - 排序列表的比较器。 null 值指示应该使用的元素的自然顺序。

返回：

如果搜索键包含在列表中，则返回搜索键的索引；否则返回 (-(插入点) - 1) 。插入点 被定义为将键插入列表的那一点：即第一个大于此键的元素索引，或者如果列表中的所有元素都小于指定的键，则为 list.size() 。注意，这保证了当且仅当此键被找到时，返回的值将 >= 0。

抛出：

ClassCastException - 如果列表中包含使用指定的比较器不可相互比较 的元素，或者使用此比较器无法相互比较搜索键与列表的元素。

另请参见：

Comparable , sort(List, Comparator)

---

reverse

public static void reverse(List<?>list)

反转指定列表中元素的顺序。

此方法以线性时间运行。

参数：

list - 元素反转的列表。

抛出：

UnsupportedOperationException - 如果指定列表或其列表迭代器不支持 set 方法。

---

shuffle

public static void shuffle(List<?>list)

使用默认随机源随机更改指定列表的序列。所有序列更改发生的可能性都是大致相等的。

前面描述中使用了不明确的词“大致”，因为随机源大致只是一个独立选择位的公正来源。如果它是一个随机选择位的完美来源，那么算法将选择具有完美一致性的序列更改。

此实现向后遍历列表，从最后一个元素一直到第二个元素，将随机选择的元素重复交换到“当前位置”。元素是从列表中随机选择的，从第一个元素运行到当前位置（包括）。

此方法以线性时间运行。如果指定列表没有实现 RandomAccess 接口并且是一个大型列表，则此实现在改组列表前将指定列表转储到数组中，并将改组后的数组转储回列表中。这避免了二次型行为，该行为是因为在适当位置改组一个“有序访问”列表而引起的。

参数：

list - 要改组的列表。

抛出：

UnsupportedOperationException - 如果指定列表或其列表迭代器不支持 set 方法。

---

shuffle

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

使用指定的随机源随机更改指定列表的序列。所有序列更改发生的可能性都是相等的，假定随机源是公平的。

此实现向后遍历列表，从最后一个元素一直到第二个元素，将随机选择的元素重复交换到“当前位置”。元素是从列表中随机选择的，从第一个元素运行到当前位置（包括）。

此方法以线性时间运行。如果指定列表没有实现 RandomAccess 接口并且是一个大型列表，则此实现在改组列表前将指定列表转储到该数组中，并将改组后的数组转储回列表中。这避免了二次型行为，该行为是因为在适当位置改组一个“有序访问”列表而引起的。

参数：

list - 要改组的列表。

rnd - 用来改组列表的随机源。

抛出：

UnsupportedOperationException - 如果指定列表或其列表迭代器不支持 set 操作。

---

swap

public static void swap(List<?>list,
                        inti,
                        intj)

在指定列表的指定位置处交换元素。（如果指定位置相同，则调用此方法不会更改列表。）

参数：

list - 进行元素交换的列表。

i - 要交换的一个元素的索引。

j - 要交换的另一个元素的索引。

抛出：

IndexOutOfBoundsException - 如果 i 或 j 超出范围 (i < 0 || i >= list.size() || j < 0 || j >= list.size())。

从以下版本开始：

1.4

---

fill

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

使用指定元素替换指定列表中的所有元素。

此方法以线性时间运行。

参数：

list - 使用指定元素所填充的列表。

obj - 用来填充指定列表的元素。

抛出：

UnsupportedOperationException - 如果指定列表或其列表迭代器不支持 set 操作。

---

copy

public static <T> void copy(List<? super T>dest,
                            List<? extends T>src)

将所有元素从一个列表复制到另一个列表。执行此操作后，目标列表中每个已复制元素的索引将等同于源列表中该元素的索引。目标列表至少必须和源列表一样长。如果目标列表更长一些，则不影响目标列表中的其余元素。

此方法以线性时间运行。

参数：

dest - 目标列表。

src - 源列表。

抛出：

IndexOutOfBoundsException - 如果目标列表太小而无法包含整个源列表。

UnsupportedOperationException - 如果目标列表的列表迭代器不支持 set 操作。

---

min

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

根据元素的自然顺序 返回给定 collection 的最小元素。collection 中的所有元素都必须实现 Comparable 接口。此外，collection 中的所有元素都必须是可相互比较的（也就是说，对于 collection 中的任何 e1 和 e2 元素， e1.compareTo(e2) 不得抛出 ClassCastException ）。

此方法在整个 collection 上进行迭代，所以它需要的时间与 collection 的大小成正比。

参数：

coll - 将确定其最小元素的 collection。

返回：

根据元素的自然顺序，返回给定 collection 的最小元素。

抛出：

ClassCastException - 如果 collection 包含不可相互比较的 的元素（例如，字符串和整数）。

NoSuchElementException - 如果 collection 为空。

另请参见：

Comparable

---

min

public static <T> T min(Collection<? extends T>coll,
                        Comparator<? super T>comp)

根据指定比较器产生的顺序，返回给定 collection 的最小元素。collection 中的所有元素都必须是通过指定比较器可相互比较的（也就是说，对于 collection 中的任何 e1 和 e2 元素， comp.compare(e1, e2) 不得抛出 ClassCastException ）。

此方法在整个 collection 上进行迭代，所以它需要的时间与 collection 的大小成正比。

参数：

coll - 将确定其最小元素的 collection。

comp - 用来确定最小元素的比较器。 null 值指示应该使用的元素的自然顺序。

返回：

根据指定比较器返回给定 collection 的最小元素。

抛出：

ClassCastException - 如果 collection 中包含使用指定的比较器不可相互比较的 的元素。

NoSuchElementException - 如果 collection 为空。

另请参见：

Comparable

---

max

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

根据元素的自然顺序，返回给定 collection 的最大元素。collection 中的所有元素都必须实现 Comparable 接口。此外，collection 中的所有元素都必须是可相互比较的（也就是说，对于 collection 中的任何 e1 和 e2 元素， e1.compareTo(e2) 不得抛出 ClassCastException ）。

此方法在整个 collection 上进行迭代，所以它需要的时间与 collection 的大小成正比。

参数：

coll - 将确定其最大元素的 collection。

返回：

根据元素的自然顺序 返回给定 collection 的最大元素。

抛出：

ClassCastException - 如果 collection 包含不可相互比较的 的元素（例如，字符串和整数）。

NoSuchElementException - 如果 collection 为空。

另请参见：

Comparable

---

max

public static <T> T max(Collection<? extends T>coll,
                        Comparator<? super T>comp)

根据指定比较器产生的顺序，返回给定 collection 的最大元素。collection 中的所有元素都必须是通过指定比较器可相互比较的（也就是说，对于 collection 中的任何 e1 和 e2 元素， comp.compare(e1, e2) 不得抛出 ClassCastException ）。

此方法在整个 collection 上进行迭代，所以它需要的时间与 collection 的大小成正比。

参数：

coll - 将确定其最大元素的 collection。

comp - 用来确定最大元素的比较器。 null 值指示应该使用的元素的自然顺序。

返回：

根据指定比较器返回给定 collection 的最大元素。

抛出：

ClassCastException - 如果 collection 中包含使用指定的比较器不可相互比较的 的元素。

NoSuchElementException - 如果 collection 为空。

另请参见：

Comparable

---

rotate

public static void rotate(List<?>list,
                          intdistance)

根据指定的距离循环移动指定列表中的元素。调用此方法后，对于在 0 和 list.size()-1 （包括）之间的所有 i 值，索引 i 处的元素将是以前位于索引 (i - distance) mod list.size() 处的元素。（此方法对列表的大小没有任何影响。）

例如，假设 list 包含 [t, a, n, k, s] 。在调用 Collections.rotate(list, 1) （或 Collections.rotate(list, -4) ）之后， list 将包含 [s, t, a, n, k] 。

注意，此方法用于子列表时非常有用，可以在保留其余元素顺序的同时，在列中移动一个或多个元素。例如，以下语句可以将索引 j 处的元素向前移动到位置 k 上（它必须大于或等于 j ）：

     Collections.rotate(list.subList(j, k+1), -1);

为了具体说明这一点，假设 list 包含 [a, b, c, d, e] 。要将索引 1 处的元素（ b ）向前移动两个位置，请执行以下调用：

     Collections.rotate(l.subList(1, 4), -1);

得到的列表是 [a, c, d, b, e] 。

要将多个元素向前移动，则需要增加循环移动距离的绝对值。要将元素向前移动，请使用一个正的移动位数。

如果指定列表是一个小型列表，或者它实现了 RandomAccess 接口，则此实现会将第一个元素交换到它应该去的位置上，然后重复执行交换操作，将替换的元素交换到它们应该去的位置上，直到替换的元素交换成第一个元素。如有必要，需要在第二个或后续的元素上重复这个过程，直到完成循环移动。如果指定的列表是大型列表并且没有实现 RandomAccess 接口，则此实现会将列表拆分成位于 -distance mod size 索引两边的两个子列表视图。然后在每个子列表视图上调用 reverse(List) 方法，并最终在整个列表上调用此方法。有关这两种算法更为完整的描述，请参阅 Jon Bentley 撰写的《Programming Pearls》(Addison-Wesley, 1986) 一书中的第 2.3 小节。

参数：

list - 要循环移动的列表。

distance - 列表循环移动的距离。在该值上没有任何限制；它可以是零、负数或大于 list.size() 的数。

抛出：

UnsupportedOperationException - 如果指定列表或其列表迭代器不支持 set 方法。

从以下版本开始：

1.4

---

replaceAll

public static <T> boolean replaceAll(List<T>list,
                                     ToldVal,
                                     TnewVal)

使用另一个值替换列表中出现的所有某一指定值。更正式地说，使用 newVal 替换 list 中满足 (oldVal==null ? e==null : oldVal.equals(e)) 的每个 e 元素。（此方法对列表的大小没有任何影响。）

参数：

list - 在其中进行替换的列表。

oldVal - 将被替换的原值。

newVal - 替换 oldVal 的新值。

返回：

如果 list 包含一个或多个满足 (oldVal==null ? e==null : oldVal.equals(e)) 的 e 元素，则返回 true 。

抛出：

UnsupportedOperationException - 如果指定列表或其列表迭代器不支持 set 方法。

从以下版本开始：

1.4

---

indexOfSubList

public static int indexOfSubList(List<?>source,
                                 List<?>target)

返回指定源列表中第一次出现指定目标列表的起始位置，如果没有出现这样的列表，则返回 -1。更正式地说，返回满足 source.subList(i, i+target.size()).equals(target) 的最低索引 i ，如果不存在这样的索引，则返回 -1。（如果 target.size() > source.size() ，则返回 -1。）

此实现采用 "brute force" 扫描技术在源列表上进行扫描，依次在每个位置上寻找与目标匹配的列表项。

参数：

source - 在该列表中搜索 target 列表的第一次出现。

target - 作为 source 子列表而被搜索的列表。

返回：

返回指定源列表中第一次出现指定目标列表的起始位置，如果没有出现这样的列表，则返回 -1。

从以下版本开始：

1.4

---

lastIndexOfSubList

public static int lastIndexOfSubList(List<?>source,
                                     List<?>target)

返回指定源列表中最后一次出现指定目标列表的起始位置，如果没有出现这样的列表，则返回 -1。更正式地说，返回满足 source.subList(i, i+target.size()).equals(target) 的最高索引 i ，如果不存在这样的索引，则返回 -1。（如果 target.size() > source.size() ，则返回 -1。）

此实现采用 "brute force" 迭代技术在源列表上进行迭代，依次在每个位置上寻找与目标匹配的列表项。

参数：

source - 在该列表中搜索 target 列表的最后一次出现。

target - 作为 source 子列表而被搜索的列表。

返回：

返回指定源列表中最后一次出现指定目标列表的起始位置，如果没有出现这样的列表，则返回 -1。

从以下版本开始：

1.4

---

unmodifiableCollection

public static <T> Collection<T> unmodifiableCollection(Collection<? extends T>c)

返回指定 collection 的不可修改视图。此方法允许使用模块，为用户提供对内部 collection 的“只读”访问。在返回的 collection 上执行的查询操作将“读完”指定的 collection。试图修改返回的 collection，不管是直接修改还是通过其迭代器进行修改，都将导致抛出 UnsupportedOperationException 。

返回的 collection 并不 将 hashCode 和 equals 操作传递给底层 collection，但这依赖于 Object 的 equals 和 hashCode 方法。在底层 collection 是一个 set 或是一个列表的情况下，有必要遵守这些操作的协定。

如果指定 collection 是可序列化的，则返回的 collection 也将是可序列化的。

参数：

c - 将为其返回一个不可修改视图的 collection。

返回：

指定 collection 的不可修改视图。

---

unmodifiableSet

public static <T> Set<T> unmodifiableSet(Set<? extends T>s)

返回指定 set 的不可修改视图。此方法允许使用模块，为用户提供对内部 set 的“只读”访问。在返回的 set 上执行的查询操作将“读完”指定的 set。试图修改返回的 set，不管是直接修改还是通过其迭代器进行修改，都将导致抛出 UnsupportedOperationException 。

如果指定 set 是可序列化的，则返回的 set 也将是可序列化的。

参数：

s - 将为其返回一个不可修改视图的 set。

返回：

指定 set 的不可修改视图。

---

unmodifiableSortedSet

public static <T> SortedSet<T> unmodifiableSortedSet(SortedSet<T>s)

返回指定有序 set 的不可修改视图。此方法允许使用模块，为用户提供对内部有序 set 的“只读”访问。在返回的有序 set 上执行的查询操作将“读完”指定的有序 set。无论是直接修改、通过其迭代器修改，还是通过其 subSet 、 headSet 或 tailSet 视图修改，试图修改返回的有序 set 都将导致抛出 UnsupportedOperationException 。

如果指定有序 set 是可序列化的，则返回的有序 set 也将是可序列化的。

参数：

s - 将为其返回一个不可修改视图的有序 set。

返回：

指定有序 set 的不可修改视图。

---

unmodifiableList

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

返回指定列表的不可修改视图。此方法允许使用模块，为用户提供对内部列表的“只读”访问。在返回的列表上执行的查询操作将“读完”指定的列表。试图修改返回的列表，不管是直接修改还是通过其迭代器进行修改，都将导致抛出 UnsupportedOperationException 。

如果指定列表是可序列化的，则返回的列表也将是可序列化的。类似地，如果指定列表实现 RandomAccess ，则返回列表也将这样做。

参数：

list - 将为其返回一个不可修改视图的列表。

返回：

指定列表的不可修改视图。

---

unmodifiableMap

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

返回指定映射的不可修改视图。此方法允许使用模块，为用户提供对内部映射的“只读”访问。在返回的映射上执行的查询操作将“读完”指定的映射。试图修改返回的映射，不管是直接修改还是通过其 collection 视图进行修改，都将导致抛出 UnsupportedOperationException 。

如果指定映射是可序列化的，则返回的映射也将是可序列化的。

参数：

m - 将为其返回一个不可修改视图的映射。

返回：

指定映射的不可修改视图。

---

unmodifiableSortedMap

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

返回指定有序映射的不可修改视图。此方法允许使用模块，为用户提供对内部有序映射的“只读”访问。在返回的有序映射上执行的查询操作将“读完”指定的有序映射。无论是直接修改、通过其 collection 视图修改，还是通过其 subMap 、 headMap 或 tailMap 视图修改，试图修改返回的有序映射都将导致抛出 UnsupportedOperationException 。

如果指定的有序映射是可序列化的，则返回的有序映射也将是可序列化的。

参数：

m - 将为其返回一个不可修改视图的有序映射。

返回：

指定有序映射的不可修改视图。

---

synchronizedCollection

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

返回由指定 collection 支持的同步（线程安全的）collection。为了保证按顺序访问，必须通过返回的 collection 完成对底层 collection 的所有访问。

在返回的 collection 上进行迭代时，强制用户手工在返回的 collection 上进行同步：

  Collection c = Collections.synchronizedCollection(myCollection);
     ...
  synchronized(c) {
      Iterator i = c.iterator(); // Must be in the synchronized block
      while (i.hasNext())
         foo(i.next());
  }

不遵从此建议将导致无法确定的行为。

返回的 collection 并不 将 hashCode 和 equals 操作传递给底层 collection，但这依赖于 Object 的 equals 和 hashCode 方法。在底层 collection 是一个 set 或是一个列表的情况下，有必要遵守这些操作的协定。

如果指定 collection 是可序列化的，则返回的 collection 也将是可序列化的。

参数：

c - 被“包装”在同步 collection 中的 collection。

返回：

指定 collection 的同步视图。

---

synchronizedSet

public static <T> Set<T> synchronizedSet(Set<T>s)

返回由指定 set 支持的同步（线程安全的）set。为了保证按顺序访问，必须通过返回的 set 完成对底层 set 的所有访问。

在返回的 set 上进行迭代时，强制用户手工在返回的 set 上进行同步：

  Set s = Collections.synchronizedSet(new HashSet());
      ...
  synchronized(s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }

不遵从此建议将导致无法确定的行为。

如果指定 set 是可序列化的，则返回的 set 也将是可序列化的。

参数：

s - 被“包装”在同步 set 中的 set。

返回：

指定 set 的同步视图。

---

synchronizedSortedSet

public static <T> SortedSet<T> synchronizedSortedSet(SortedSet<T>s)

返回由指定有序 set 支持的同步（线程安全的）有序 set。为了保证按顺序访问，必须通过返回的有序 set（或其视图）完成对底层有序 set 的所有访问。

在返回的有序 set 上或其 subSet 、 headSet 或 tailSet 视图上进行迭代时，强制用户手工在返回的有序 set 上进行同步。

  SortedSet s = Collections.synchronizedSortedSet(new HashSortedSet());
      ...
  synchronized(s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }

或者：

  SortedSet s = Collections.synchronizedSortedSet(new HashSortedSet());
  SortedSet s2 = s.headSet(foo);
      ...
  synchronized(s) {  // Note: s, not s2!!!
      Iterator i = s2.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }

不遵从此建议将导致无法确定的行为。

如果指定的有序 set 是可序列化的，则返回的有序 set 也将是可序列化的。

参数：

s - 被“包装”在同步有序 set 中的有序 set。

返回：

指定有序 set 的同步视图。

---

synchronizedList

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

返回由指定列表支持的同步（线程安全的）列表。为了保证按顺序访问，必须通过返回的列表完成对底层列表的所有访问。

在返回的列表上进行迭代时，强制用户手工在返回的列表上进行同步：

  List list = Collections.synchronizedList(new ArrayList());
      ...
  synchronized(list) {
      Iterator i = list.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }

不遵从此建议将导致无法确定的行为。

如果指定列表是可序列化的，则返回的列表也将是可序列化的。

参数：

list - 被“包装”在同步列表中的列表。

返回：

指定列表的同步视图。

---

synchronizedMap

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

返回由指定映射支持的同步（线程安全的）映射。为了保证按顺序访问，必须通过返回的映射完成对底层映射的所有访问。

在返回的映射或其任意 collection 视图上进行迭代时，强制用户手工在返回的映射上进行同步：

  Map m = Collections.synchronizedMap(new HashMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized(m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }

不遵从此建议将导致无法确定的行为。

如果指定映射是可序列化的，则返回的映射也将是可序列化的。

参数：

m - 被“包装”在同步映射中的映射。

返回：

指定映射的同步视图。

---

synchronizedSortedMap

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

返回由指定有序映射支持的同步（线程安全的）有序映射。为了保证按顺序访问，必须通过返回的有序映射（或其视图）完成对底层有序映射的所有访问。

当在返回的有序映射的任何 collection 视图上进行迭代时，或者在其任何 subMap 、 headMap 或 tailMap 视图进行迭代时，强制用户手工在该映射上进行同步：

  SortedMap m = Collections.synchronizedSortedMap(new HashSortedMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized(m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }

或者：

  SortedMap m = Collections.synchronizedSortedMap(new HashSortedMap());
  SortedMap m2 = m.subMap(foo, bar);
      ...
  Set s2 = m2.keySet();  // Needn't be in synchronized block
      ...
  synchronized(m) {  // Synchronizing on m, not m2 or s2!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }

不遵从此建议将导致无法确定的行为。

如果指定的有序映射是可序列化的，则返回的有序映射也将是可序列化的。

参数：

m - 被“包装”在同步有序映射中的有序映射。

返回：

指定有序映射的同步视图。

---

checkedCollection

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

返回指定 collection 的一个动态类型安全视图。试图插入一个错误类型的元素将导致立即抛出一个 ClassCastException 。假设在生成动态类型安全视图之前，collection 不包含任何类型不正确的元素，并且对该 collection 的所有后续访问都通过该视图进行，则可以保证 此 collection 不包含类型不正确的元素。

语言中的一般机制提供了编译时（静态）类型检查，但是一些未经检查的强制转换可能会使此机制无效。通常这不是一个问题，因为编译器会在所有这类未经检查的操作上发出警告。但有的时候，只进行单独的静态类型检查并不够。例如，假设将 collection 传递给一个第三方库，并强制库代码不能通过插入一个错误类型的元素来毁坏 collection。

动态类型安全视图的另一个用途是调试。假设某个程序运行失败，抛出一个 ClassCastException ，这指示一个类型不正确的元素被放入已参数化 collection 中。不幸的是，该异常可以发生在插入错误元素之后的任何时间，因此，这通常只能提供很少或无法提供任何关于问题真正来源的信息。如果问题是可再现的，那么可以暂时修改程序，使用一个动态类型安全视图来包装该 collection，通过这种方式可快速确定问题的来源。例如，以下声明：

     Collection<String> c = new HashSet<String>();

可以暂时用下面的声明代替：

     Collection<String> c = Collections.checkedCollection(
         new HashSet<String>(), String.class);

再次运行程序会造成它在将类型不正确的元素插入 collection 的地方失败，从而清楚地识别问题的来源。一旦问题得以解决，就可以将修改后的声明转换回原来的声明。

返回的 collection 并不 将 hashCode 和 equals 操作传递给底层 collection，但这依赖于 Object 的 equals 和 hashCode 方法。在底层 collection 是一个 set 或是一个列表的情况下，有必要遵守这些操作的协定。

如果指定 collection 是可序列化的，则返回的 collection 也将是可序列化的。

参数：

c - 方法基于该 collection 返回动态类型安全视图

type - 允许 c 持有的元素类型

返回：

指定 collection 的一个动态安全类型视图

从以下版本开始：

1.5

---

checkedSet

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

返回指定 set 的一个动态类型安全视图。试图插入一个错误类型的元素将导致立即抛出一个 ClassCastException 。假设在生成动态类型安全视图之前，set 不包含任何类型不正确的元素，并且对该 set 的所有后续访问都通过该视图进行，则可以保证 此 set 不包含类型不正确的元素。

可以在 checkedCollection 方法的文档中找到有关使用动态类型安全视图的讨论。

如果指定 set 是可序列化的，则返回的 set 也将是可序列化的。

参数：

s - 方法基于该 set 返回动态类型安全视图

type - 允许 s 持有的元素类型

返回：

指定 set 的一个动态安全类型视图

从以下版本开始：

1.5

---

checkedSortedSet

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

返回指定有序 set 的一个动态类型安全视图。试图插入一个错误类型的元素将导致立即抛出一个 ClassCastException 。假设在生成动态类型安全视图之前，有序 set 不包含任何类型不正确的元素，并且对该有序 set 的所有后续访问都通过该视图进行，则可以保证 该有序 set 不包含类型不正确的元素。

可以在 checkedCollection 方法的文档中找到有关使用动态类型安全视图的讨论。

如果指定的有序 set 是可序列化的，则返回的有序 set 也将是可序列化的。

参数：

s - 方法基于该有序 set 返回动态类型安全视图

type - 允许 s 持有的元素类型

返回：

指定有序 set 的一个动态安全类型视图

从以下版本开始：

1.5

---

checkedList

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

返回指定列表的一个动态类型安全视图。试图插入一个错误类型的元素将导致立即抛出一个 ClassCastException 。假设在生成动态类型安全视图之前，列表不包含任何类型不正确的元素，并且对该列表的所有后续访问都通过该视图进行，则可以保证 此列表不包含类型不正确的元素。

可以在 checkedCollection 方法的文档中找到有关使用动态类型安全视图的讨论。

如果指定列表是可序列化的，则返回的列表也将是可序列化的。

参数：

list - 方法基于该列表返回动态类型安全视图

type - 允许 list 持有的元素类型

返回：

指定列表的一个动态安全类型视图

从以下版本开始：

1.5

---

checkedMap

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

返回指定映射的一个动态类型安全视图。试图插入一个具有错误类型键或值的映射关系将导致立即抛出一个 ClassCastException 。类似地，无论是直接通过映射自身进行修改，还是通过一个从该映射 项集 视图中获得的 Map.Entry 实例进行修改，试图修改目前与键关联的值都将导致立即抛出 ClassCastException 。

假设在生成动态类型安全视图之前，映射中不包含任何类型不正确的键或值，并且对映射的所有后续访问都通过该视图（或其 collection 视图之一）进行，则可以保证 此映射不包含类型不正确的键或值。

可以在 checkedCollection 方法的文档中找到有关使用动态类型安全视图的讨论。

如果指定映射是可序列化的，则返回的映射也将是可序列化的。

参数：

m - 将为其返回动态类型安全视图的映射

keyType - 允许 m 持有的键类型

valueType - 允许 m 持有的值类型

返回：

指定映射的动态类型安全视图

从以下版本开始：

1.5

---

checkedSortedMap

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

返回指定有序映射的一个动态类型安全视图。试图插入一个具有错误类型键或值的映射关系将导致立即抛出一个 ClassCastException 。类似地，无论是直接通过映射自身进行修改，还是通过一个从该映射 项集 视图中获得的 Map.Entry 实例进行修改，试图修改目前与键管理的值都将导致立即抛出 ClassCastException 。

假设在生成动态类型安全视图之前，映射中不包含任何类型不正确的键或值，并且对映射的所有后续访问都通过该视图（或其 collection 视图之一）进行，则可以保证 此映射不包含类型不正确的键或值。

可以在 checkedCollection 方法的文档中找到有关使用动态类型安全视图的讨论。

如果指定映射是可序列化的，则返回的映射也将是可序列化的。

参数：

m - 将为其返回动态类型安全视图的映射

keyType - 允许 m 持有的键的类型

valueType - 允许 m 持有的值的类型

返回：

指定映射的动态类型安全视图

从以下版本开始：

1.5

---

emptySet

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

返回空的 set（不可变的）。此 set 是可序列化的。与 like-named 字段不同，此方法是参数化的。

以下示例阐释了获得空 set 的类型安全 (type-safe) 方法：

     Set<String> s = Collections.emptySet();

实现注意事项：实现此方法不需要为每次调用创建一个单独的 Set 对象。使用此方法的代价与使用 like-named 字段的代价相当。（与此方法不同，该字段不提供类型安全。）

从以下版本开始：

1.5

另请参见：

EMPTY_SET

---

emptyList

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

返回空的列表（不可变的）。此列表是可序列化的。

以下示例阐释了获得空列表的类型安全方法：

     List<String> s = Collections.emptyList();

实现注意事项：实现此方法不需要为每次调用创建一个单独的 List 对象。使用此方法的代价与使用 like-named 字段的代价相当。（与此方法不同，该字段不提供类型安全。）

从以下版本开始：

1.5

另请参见：

EMPTY_LIST

---

emptyMap

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

返回空的映射（不可变的）。此映射是可序列化的。

以下示例阐释了获得空 set 的类型安全方法：

     Map<String, Date> s = Collections.emptyMap();

实现注意事项：实现此方法不需要为每次调用创建一个单独的 Map 对象。使用此方法的代价与使用 like-named 字段的代价相当。（与此方法不同，该字段不提供类型安全。）

从以下版本开始：

1.5

另请参见：

EMPTY_MAP

---

singleton

public static <T> Set<T> singleton(To)

返回一个只包含指定对象的不可变 set。返回的 set 是可序列化的。

参数：

o - 将存储到返回 set 中的单独对象。

返回：

一个只包含指定对象的不可变 set。

---

singletonList

public static <T> List<T> singletonList(To)

返回一个只包含指定对象的不可变列表。返回的列表是可序列化的。

参数：

o - 将存储到返回列表中的单独对象。

返回：

一个只包含指定对象的不可变列表。

从以下版本开始：

1.3

---

singletonMap

public static <K,V> Map<K,V> singletonMap(Kkey,
                                          Vvalue)

返回一个不可变的映射，它只将指定键映射到指定值。返回的映射是可序列化的。

参数：

key - 将存储到返回映射中的单独键。

value - 返回的映射将 key 映射到的值。

返回：

只包含指定键-值映射关系的不可变映射。

从以下版本开始：

1.3

---

nCopies

public static <T> List<T> nCopies(intn,
                                  To)

返回由指定对象的 n 个副本组成的不可变列表。新分配的数据对象非常小（它只包含一个对该数据对象的引用）。在通过与 List.addAll 方法组合来增大列表的时候，此方法很有用。返回的列表是可序列化的。

参数：

n - 返回列表中的元素数。

o - 重复出现在返回列表中的元素。

返回：

指定对象 n 个副本组成的不可变列表。

抛出：

IllegalArgumentException - 如果 n < 0。

另请参见：

List.addAll(Collection) , List.addAll(int, Collection)

---

reverseOrder

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

返回一个比较器，它强行反转实现 Comparable 接口那些对象 collection 上的自然顺序。（自然顺序是通过对象自身的 compareTo 方法强行排序的。）这允许使用单个语句，以反向自然顺序对实现 Comparable 接口的那些对象的 collection（或数组）进行排序（或维护）。例如，假设 a 是一个字符串数组。那么：

                Arrays.sort(a, Collections.reverseOrder());

将按照反向字典（字母）顺序对数组进行排序。

返回的比较器是可序列化的。

返回：

返回一个比较器，它强行反转实现 Comparable 接口那些对象 collection 上的自然顺序。

另请参见：

Comparable

---

reverseOrder

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

返回一个比较器，它强行反转指定比较器的顺序。如果指定比较器为 null，则此方法等同于 reverseOrder() （换句话说，它返回一个比较器，该比较器将强行反转实现 Comparable 接口那些对象 collection 上的自然顺序）。

返回的比较器是可序列化的（假设指定的比较器也是可序列化的或者为 null）。

返回：

强行反转指定比较器顺序的比较器。

从以下版本开始：

1.5

---

enumeration

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

返回一个指定 collection 上的枚举。这提供了与遗留 API 的互操作性，遗留 API 需要一个作为输入的枚举。

参数：

c - 将为其返回一个枚举的 collection。

返回：

指定 collection 上的一个枚举。

另请参见：

Enumeration

---

list

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

返回一个数组列表，它按照枚举返回元素的顺序包含指定枚举返回的元素。此方法提供了返回枚举的遗留 API 与需要 collection 的新 API 之间的互操作性。

参数：

e - 为返回的数组列表提供元素的枚举

返回：

包含指定枚举返回元素的数组列表。

从以下版本开始：

1.4

另请参见：

Enumeration , ArrayList

---

frequency

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

返回指定 collection 中等于指定对象的元素数。更正式地说，返回满足 (o == null ? e == null : o.equals(e)) 的 collection 中的 e 元素的数量。

参数：

c - 在其中确定 o 的频率的 collection

o - 将确定其频率的对象

抛出：

NullPointerException - 如果 c 为 null

从以下版本开始：

1.5

---

disjoint

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

如果两个指定 collection 中没有相同的元素，则返回 true 。

如果将此方法用在不符合 Collection 常规协定的 collection 上，则必须小心。方法的实现可以在任何一个 collection 上进行迭代，测试元素是否包含在另一个 collection 中（或执行任何等效的计算）。如果任何一个 collection 使用了一个非标准的相等性测试（比如 SortedSet ，它的顺序不是可用等式比较的，或者 IdentityHashMap 的键集），则两个 collection 都必须使用相同的非标准相等性测试，否则此方法的结果是不明确的。

注意，允许在两个参数中传递相同的 collection，在这种情况下，当且仅当 collection 为空时此方法才返回 true。

参数：

c1 - 一个 collection

c2 - 一个 collection

抛出：

NullPointerException - 如果某个 collection 为 null

从以下版本开始：

1.5

---

addAll

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

将所有指定元素添加到指定 collection 中。可以分别指定要添加的元素，或者将它们指定为一个数组。此便捷方法的行为与 c.addAll(Arrays.asList(elements)) 的行为是相同的，但在大多数实现下，此方法运行起来可能要快得多。

在分别指定元素时，此方法提供了将少数元素添加到现有 collection 中的一个便捷方式：

     Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");

参数：

c - elements 所要插入的 collection

a - 插入 c 的元素

返回：

如果 collection 随调用的结果而发生改变，则返回 true

抛出：

UnsupportedOperationException - 如果 c 不支持 add 方法

NullPointerException - 如果 elements 包含一个或多个 null 值并且 c 不支持 null 元素，或者如果 c 或 elements 为 null

IllegalArgumentException - 如果 elements 中值的某个方面不允许它添加到 c 中

从以下版本开始：

1.5

另请参见：

Collection.addAll(Collection)