站内搜索: 请输入搜索关键词
当前页面: 在线文档首页 > JavaTM 2 Platform Standard Edition 5.0 API 规范中文版

Collections (Java 2 Platform SE 5.0) - JavaTM 2 Platform Standard Edition 5.0 API 规范中文版

JavaTM 2 Platform
Standard Ed. 5.0

java.util
类 Collections

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

字段摘要
static List EMPTY_LIST
          空的列表(不可变的)。
static Map EMPTY_MAP
          空的映射(不可变的)。
static Set EMPTY_SET
          空的 set(不可变的)。
 
方法摘要
static
<T> boolean
addAll(Collection<? super T> c, T... a)
          将所有指定元素添加到指定 collection 中。
static
<T> int
binarySearch(List<? extends Comparable<? super T>> list, T key)
          使用二进制搜索算法来搜索指定列表,以获得指定对象。
static
<T> int
binarySearch(List<? extends T> list, T key, 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)
          将所有元素从一个列表复制到另一个列表。
static boolean 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, T obj)
          使用指定元素替换指定列表中的所有元素。
static int frequency(Collection<?> c, Object o)
          返回指定 collection 中等于指定对象的元素数。
static int indexOfSubList(List<?> source, List<?> target)
          返回指定源列表中第一次出现指定目标列表的起始位置,如果没有出现这样的列表,则返回 -1。
static int 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(int n, T o)
          返回由指定对象的 n 个副本组成的不可变列表。
static
<T> boolean
replaceAll(List<T> list, T oldVal, T newVal)
          使用另一个值替换列表中出现的所有某一指定值。
static void reverse(List<?> list)
          反转指定列表中元素的顺序。
static
<T> Comparator<T>
reverseOrder()
          返回一个比较器,它强行反转实现 Comparable 接口那些对象 collection 上的自然顺序
static
<T> Comparator<T>
reverseOrder(Comparator<T> cmp)
          返回一个比较器,它强行反转指定比较器的顺序。
static void rotate(List<?> list, int distance)
          根据指定的距离循环移动指定列表中的元素。
static void shuffle(List<?> list)
          使用默认随机源随机更改指定列表的序列。
static void shuffle(List<?> list, Random rnd)
          使用指定的随机源随机更改指定列表的序列。
static
<T> Set<T>
singleton(T o)
          返回一个只包含指定对象的不可变 set。
static
<T> List<T>
singletonList(T o)
          返回一个只包含指定对象的不可变列表。
static
<K,V> Map<K,V>
singletonMap(K key, V value)
          返回一个不可变的映射,它只将指定键映射到指定值。
static
<T extends Comparable<? super T>>
void
sort(List<T> list)
          根据元素的自然顺序 对指定列表按升序进行排序。
static
<T> void
sort(List<T> list, Comparator<? super T> c)
          根据指定比较器产生的顺序对指定列表进行排序。
static void swap(List<?> list, int i, int j)
          在指定列表的指定位置处交换元素。
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 接口。此外,列表中的所有元素都必须是可相互比较的(也就是说,对于列表中的任何 e1e2 元素,e1.compareTo(e2) 不得抛出 ClassCastException)。

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

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

该排序算法是一个经过修改的合并排序算法(其中,如果低子列表中的最高元素小于高子列表中的最低元素,则忽略合并)。此算法提供可保证的 n log(n) 性能。 此实现将指定列表转储到一个数组中,并对数组进行排序,在重置数组中相应位置处每个元素的列表上进行迭代。这避免了由于试图对适当位置上的链接列表进行排序而产生的 n2 log(n) 性能。

参数:
list - 要排序的列表。
抛出:
ClassCastException - 如果列表包含不可相互比较的 的元素(例如,字符串和整数)。
UnsupportedOperationException - 如果指定列表的列表迭代器不支持 set 操作。
另请参见:
Comparable

sort

public static <T> void sort(List<T> list,
                            Comparator<? super T> c)
根据指定比较器产生的顺序对指定列表进行排序。此列表内的所有元素都必须是使用指定比较器可相互比较的(也就是说,对于列表中的任何 e1e2 元素,c.compare(e1, e2) 不得抛出 ClassCastException)。

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

排序算法是一个经过修改的合并排序算法(其中,如果低子列表中的最高元素小于高子列表中的最低元素,则忽略合并)。此算法提供可保证的 n log(n) 性能。 指定列表必须是可修改的,但不必是可大小调整的。此实现将指定列表转储到一个数组中,并对数组进行排序,在重置数组中相应位置处每个元素的列表上进行迭代。这避免了由于试图对适当位置上的链接列表进行排序而产生的 n2 log(n) 性能。

参数:
list - 要排序的列表。
c - 确定列表顺序的比较器。null 值指示应该使用的元素的自然顺序
抛出:
ClassCastException - 如果列表中包含使用指定的比较器不可相互比较的 的元素。
UnsupportedOperationException - 如果指定列表的列表迭代器不支持 set 操作。
另请参见:
Comparator

binarySearch

public static <T> int binarySearch(List<? extends Comparable<? super T>> list,
                                   T key)
使用二进制搜索算法来搜索指定列表,以获得指定对象。在进行此调用之前,必须根据列表元素的自然顺序 对列表进行升序排序(通过上面的 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,
                                   T key,
                                   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,
                           Random rnd)
使用指定的随机源随机更改指定列表的序列。所有序列更改发生的可能性都是相等的,假定随机源是公平的。

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

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

参数:
list - 要改组的列表。
rnd - 用来改组列表的随机源。
抛出:
UnsupportedOperationException - 如果指定列表或其列表迭代器不支持 set 操作。

swap

public static void swap(List<?> list,
                        int i,
                        int j)
在指定列表的指定位置处交换元素。(如果指定位置相同,则调用此方法不会更改列表。)

参数:
list - 进行元素交换的列表。
i - 要交换的一个元素的索引。
j - 要交换的另一个元素的索引。
抛出:
IndexOutOfBoundsException - 如果 ij 超出范围 (i < 0 || i >= list.size() || j < 0 || j >= list.size())。
从以下版本开始:
1.4

fill

public static <T> void fill(List<? super T> list,
                            T obj)
使用指定元素替换指定列表中的所有元素。

此方法以线性时间运行。

参数:
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 中的任何 e1e2 元素,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 中的任何 e1e2 元素,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 中的任何 e1e2 元素,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 中的任何 e1e2 元素,comp.compare(e1, e2) 不得抛出 ClassCastException)。

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

参数:
coll - 将确定其最大元素的 collection。
comp - 用来确定最大元素的比较器。null 值指示应该使用的元素的自然顺序
返回:
根据指定比较器返回给定 collection 的最大元素。
抛出:
ClassCastException - 如果 collection 中包含使用指定的比较器不可相互比较的 的元素。
NoSuchElementException - 如果 collection 为空。
另请参见:
Comparable

rotate

public static void rotate(List<?> list,
                          int distance)
根据指定的距离循环移动指定列表中的元素。调用此方法后,对于在 0list.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,
                                     T oldVal,
                                     T newVal)
使用另一个值替换列表中出现的所有某一指定值。更正式地说,使用 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,但这依赖于 ObjectequalshashCode 方法。在底层 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。无论是直接修改、通过其迭代器修改,还是通过其 subSetheadSettailSet 视图修改,试图修改返回的有序 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 视图修改,还是通过其 subMapheadMaptailMap 视图修改,试图修改返回的有序映射都将导致抛出 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 并hashCodeequals 操作传递给底层 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 上或其 subSetheadSettailSet 视图上进行迭代时,强制用户手工在返回的有序 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 视图上进行迭代时,或者在其任何 subMapheadMaptailMap 视图进行迭代时,强制用户手工在该映射上进行同步:

  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,但这依赖于 ObjectequalshashCode 方法。在底层 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(T o)
返回一个只包含指定对象的不可变 set。返回的 set 是可序列化的。

参数:
o - 将存储到返回 set 中的单独对象。
返回:
一个只包含指定对象的不可变 set。

singletonList

public static <T> List<T> singletonList(T o)
返回一个只包含指定对象的不可变列表。返回的列表是可序列化的。

参数:
o - 将存储到返回列表中的单独对象。
返回:
一个只包含指定对象的不可变列表。
从以下版本开始:
1.3

singletonMap

public static <K,V> Map<K,V> singletonMap(K key,
                                          V value)
返回一个不可变的映射,它只将指定键映射到指定值。返回的映射是可序列化的。

参数:
key - 将存储到返回映射中的单独键。
value - 返回的映射将 key 映射到的值。
返回:
只包含指定键-值映射关系的不可变映射。
从以下版本开始:
1.3

nCopies

public static <T> List<T> nCopies(int n,
                                  T o)
返回由指定对象的 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,
                            Object o)
返回指定 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 元素,或者 celementsnull
IllegalArgumentException - 如果 elements 中值的某个方面不允许它添加到 c
从以下版本开始:
1.5
另请参见:
Collection.addAll(Collection)

JavaTM 2 Platform
Standard Ed. 5.0

提交错误或意见
有关更多的 API 参考资料和开发人员文档,请参阅 Java 2 SDK SE 开发人员文档。该文档包含更详细的、面向开发人员的描述,以及总体概述、术语定义、使用技巧和工作代码示例。

版权所有 2004 Sun Microsystems, Inc. 保留所有权利。 请遵守许可证条款。另请参阅文档重新分发政策