collections.html

j2se5-api-zh,java文档的中文版本

<A NAME="sort(java.util.List, java.util.Comparator)"><!-- --></A><H3>
sort</H3>
<PRE>
public static &lt;T&gt; void <B>sort</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;T&gt;&nbsp;list,
                            <A HREF="Comparator.html" title="java.util 中的接口">Comparator</A>&lt;? super T&gt;&nbsp;c)</PRE>
<DL>
<DD>根据指定比较器产生的顺序对指定列表进行排序。此列表内的所有元素都必须是使用指定比较器<i>可相互比较的</i>（也就是说，对于列表中的任何 <tt>e1</tt> 和 <tt>e2</tt> 元素，<tt>c.compare(e1, e2)</tt> 不得抛出 <tt>ClassCastException</tt>）。<p>

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

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

指定列表必须是可修改的，但不必是可大小调整的。此实现将指定列表转储到一个数组中，并对数组进行排序，在重置数组中相应位置处每个元素的列表上进行迭代。这避免了由于试图对适当位置上的链接列表进行排序而产生的 n<sup>2</sup> log(n) 性能。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>list</CODE> - 要排序的列表。<DD><CODE>c</CODE> - 确定列表顺序的比较器。<tt>null</tt> 值指示应该使用的元素的<i>自然顺序</i>。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/ClassCastException.html" title="java.lang 中的类">ClassCastException</A></CODE> - 如果列表中包含使用指定的比较器不<i>可相互比较的</i> 的元素。
<DD><CODE><A HREF="../lang/UnsupportedOperationException.html" title="java.lang 中的类">UnsupportedOperationException</A></CODE> - 如果指定列表的列表迭代器不支持 <tt>set</tt> 操作。<DT><B>另请参见：</B><DD><A HREF="Comparator.html" title="java.util 中的接口"><CODE>Comparator</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="binarySearch(java.util.List,java.lang.Object)"><!-- --></A><A NAME="binarySearch(java.util.List, T)"><!-- --></A><H3>
binarySearch</H3>
<PRE>
public static &lt;T&gt; int <B>binarySearch</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;? extends <A HREF="../lang/Comparable.html" title="java.lang 中的接口">Comparable</A>&lt;? super T&gt;&gt;&nbsp;list,
                                   T&nbsp;key)</PRE>
<DL>
<DD>使用二进制搜索算法来搜索指定列表，以获得指定对象。在进行此调用之前，必须根据列表元素的<i>自然顺序</i> 对列表进行升序排序（通过上面的 <tt>sort(List)</tt> 方法）。如果没有对列表进行排序，则结果是不明确的。如果列表包含多个等于指定对象的元素，则无法保证找到的是哪一个。<p>

此方法对“随机访问”的列表运行 log(n) 次（它提供了一个接近固定时间的位置访问）。如果指定列表没有实现 <A HREF="RandomAccess.html" title="java.util 中的接口"><CODE>RandomAccess</CODE></A> 接口并且是一个大型列表，则此方法将执行基于迭代器的二进制搜索，执行 O(n) 次链接遍历和 O(log n) 次元素比较。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>list</CODE> - 要搜索的列表。<DD><CODE>key</CODE> - 要搜索的键。
<DT><B>返回：</B><DD>如果搜索键包含在列表中，则返回搜索键的索引；否则返回 <tt>(-(<i>插入点</i>) - 1)</tt>。<i>插入点</i> 被定义为将键插入列表的那一点：即第一个大于此键的元素索引，或者如果列表中的所有元素都小于指定的键，则为 <tt>list.size()</tt>。注意，这保证了当且仅当此键被找到时，返回的值将 &gt;= 0。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/ClassCastException.html" title="java.lang 中的类">ClassCastException</A></CODE> - 如果列表中包含不<i>可相互比较</i> 的元素（例如，字符串和整数），或者搜索键无法与列表的元素进行相互比较。<DT><B>另请参见：</B><DD><A HREF="../lang/Comparable.html" title="java.lang 中的接口"><CODE>Comparable</CODE></A>, 
<A HREF="Collections.html#sort(java.util.List)"><CODE>sort(List)</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="binarySearch(java.util.List,java.lang.Object,java.util.Comparator)"><!-- --></A><A NAME="binarySearch(java.util.List, T, java.util.Comparator)"><!-- --></A><H3>
binarySearch</H3>
<PRE>
public static &lt;T&gt; int <B>binarySearch</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;? extends T&gt;&nbsp;list,
                                   T&nbsp;key,
                                   <A HREF="Comparator.html" title="java.util 中的接口">Comparator</A>&lt;? super T&gt;&nbsp;c)</PRE>
<DL>
<DD>使用二进制搜索算法来搜索指定列表，以获得指定对象。在进行此调用之前，必须根据指定的比较器（通过上面的 <tt>Sort(List, Comparator)</tt> 方法）对列表进行升序排序。如果没有对列表进行排序，则结果是不明确的。如果列表包含多个等于指定对象的元素，则无法保证找到的是哪一个。<p>

此方法对“随机访问”的列表运行 log(n) 次（这提供了一个接近固定时间的位置访问）。如果指定列表没有实现 <A HREF="RandomAccess.html" title="java.util 中的接口"><CODE>RandomAccess</CODE></A> 接口并且是一个大型列表，则此方法将执行基于迭代器的二进制搜索，执行 O(n) 次链接遍历和 O(log n) 次元素比较。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>list</CODE> - 要搜索的列表。<DD><CODE>key</CODE> - 要搜索的键。<DD><CODE>c</CODE> - 排序列表的比较器。<tt>null</tt> 值指示应该使用的元素的<i>自然顺序</i>。
<DT><B>返回：</B><DD>如果搜索键包含在列表中，则返回搜索键的索引；否则返回 <tt>(-(<i>插入点</i>) - 1)</tt>。<i>插入点</i> 被定义为将键插入列表的那一点：即第一个大于此键的元素索引，或者如果列表中的所有元素都小于指定的键，则为 <tt>list.size()</tt>。注意，这保证了当且仅当此键被找到时，返回的值将 &gt;= 0。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/ClassCastException.html" title="java.lang 中的类">ClassCastException</A></CODE> - 如果列表中包含使用指定的比较器不<i>可相互比较</i> 的元素，或者使用此比较器无法相互比较搜索键与列表的元素。<DT><B>另请参见：</B><DD><A HREF="../lang/Comparable.html" title="java.lang 中的接口"><CODE>Comparable</CODE></A>, 
<A HREF="Collections.html#sort(java.util.List, java.util.Comparator)"><CODE>sort(List, Comparator)</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="reverse(java.util.List)"><!-- --></A><H3>
reverse</H3>
<PRE>
public static void <B>reverse</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;?&gt;&nbsp;list)</PRE>
<DL>
<DD>反转指定列表中元素的顺序。<p>

此方法以线性时间运行。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>list</CODE> - 元素反转的列表。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/UnsupportedOperationException.html" title="java.lang 中的类">UnsupportedOperationException</A></CODE> - 如果指定列表或其列表迭代器不支持 <tt>set</tt> 方法。</DL>
</DD>
</DL>
<HR>

<A NAME="shuffle(java.util.List)"><!-- --></A><H3>
shuffle</H3>
<PRE>
public static void <B>shuffle</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;?&gt;&nbsp;list)</PRE>
<DL>
<DD>使用默认随机源随机更改指定列表的序列。所有序列更改发生的可能性都是大致相等的。<p>

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

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

此方法以线性时间运行。如果指定列表没有实现 <A HREF="RandomAccess.html" title="java.util 中的接口"><CODE>RandomAccess</CODE></A> 接口并且是一个大型列表，则此实现在改组列表前将指定列表转储到数组中，并将改组后的数组转储回列表中。这避免了二次型行为，该行为是因为在适当位置改组一个“有序访问”列表而引起的。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>list</CODE> - 要改组的列表。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/UnsupportedOperationException.html" title="java.lang 中的类">UnsupportedOperationException</A></CODE> - 如果指定列表或其列表迭代器不支持 <tt>set</tt> 方法。</DL>
</DD>
</DL>
<HR>

<A NAME="shuffle(java.util.List, java.util.Random)"><!-- --></A><H3>
shuffle</H3>
<PRE>
public static void <B>shuffle</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;?&gt;&nbsp;list,
                           <A HREF="Random.html" title="java.util 中的类">Random</A>&nbsp;rnd)</PRE>
<DL>
<DD>使用指定的随机源随机更改指定列表的序列。所有序列更改发生的可能性都是相等的，假定随机源是公平的。<p>

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

此方法以线性时间运行。如果指定列表没有实现 <A HREF="RandomAccess.html" title="java.util 中的接口"><CODE>RandomAccess</CODE></A> 接口并且是一个大型列表，则此实现在改组列表前将指定列表转储到该数组中，并将改组后的数组转储回列表中。这避免了二次型行为，该行为是因为在适当位置改组一个&ldquo;有序访问&rdquo;列表而引起的。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>list</CODE> - 要改组的列表。<DD><CODE>rnd</CODE> - 用来改组列表的随机源。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/UnsupportedOperationException.html" title="java.lang 中的类">UnsupportedOperationException</A></CODE> - 如果指定列表或其列表迭代器不支持 <tt>set</tt> 操作。</DL>
</DD>
</DL>
<HR>

<A NAME="swap(java.util.List, int, int)"><!-- --></A><H3>
swap</H3>
<PRE>
public static void <B>swap</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;?&gt;&nbsp;list,
                        int&nbsp;i,
                        int&nbsp;j)</PRE>
<DL>
<DD>在指定列表的指定位置处交换元素。（如果指定位置相同，则调用此方法不会更改列表。）
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>list</CODE> - 进行元素交换的列表。<DD><CODE>i</CODE> - 要交换的一个元素的索引。<DD><CODE>j</CODE> - 要交换的另一个元素的索引。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/IndexOutOfBoundsException.html" title="java.lang 中的类">IndexOutOfBoundsException</A></CODE> - 如果 <tt>i</tt> 或 <tt>j</tt> 超出范围 (i &lt; 0 || i &gt;= list.size() || j &lt; 0 || j &gt;= list.size())。<DT><B>从以下版本开始：</B></DT>
  <DD>1.4</DD>
</DL>
</DD>
</DL>
<HR>

<A NAME="fill(java.util.List,java.lang.Object)"><!-- --></A><A NAME="fill(java.util.List, T)"><!-- --></A><H3>
fill</H3>
<PRE>
public static &lt;T&gt; void <B>fill</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;? super T&gt;&nbsp;list,
                            T&nbsp;obj)</PRE>
<DL>
<DD>使用指定元素替换指定列表中的所有元素。 <p>

此方法以线性时间运行。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>list</CODE> - 使用指定元素所填充的列表。<DD><CODE>obj</CODE> - 用来填充指定列表的元素。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/UnsupportedOperationException.html" title="java.lang 中的类">UnsupportedOperationException</A></CODE> - 如果指定列表或其列表迭代器不支持 <tt>set</tt> 操作。</DL>
</DD>
</DL>
<HR>

<A NAME="copy(java.util.List, java.util.List)"><!-- --></A><H3>
copy</H3>
<PRE>
public static &lt;T&gt; void <B>copy</B>(<A HREF="List.html" title="java.util 中的接口">List</A>&lt;? super T&gt;&nbsp;dest,
                            <A HREF="List.html" title="java.util 中的接口">List</A>&lt;? extends T&gt;&nbsp;src)</PRE>
<DL>
<DD>将所有元素从一个列表复制到另一个列表。执行此操作后，目标列表中每个已复制元素的索引将等同于源列表中该元素的索引。目标列表至少必须和源列表一样长。如果目标列表更长一些，则不影响目标列表中的其余元素。<p>

此方法以线性时间运行。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>dest</CODE> - 目标列表。<DD><CODE>src</CODE> - 源列表。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/IndexOutOfBoundsException.html" title="java.lang 中的类">IndexOutOfBoundsException</A></CODE> - 如果目标列表太小而无法包含整个源列表。
<DD><CODE><A HREF="../lang/UnsupportedOperationException.html" title="java.lang 中的类">UnsupportedOperationException</A></CODE> - 如果目标列表的列表迭代器不支持 <tt>set</tt> 操作。</DL>
</DD>
</DL>
<HR>

<A NAME="min(java.util.Collection)"><!-- --></A><H3>
min</H3>
<PRE>
public static &lt;T extends <A HREF="../lang/Object.html" title="java.lang 中的类">Object</A> & <A HREF="../lang/Comparable.html" title="java.lang 中的接口">Comparable</A>&lt;? super T&gt;&gt; T <B>min</B>(<A HREF="Collection.html" title="java.util 中的接口">Collection</A>&lt;? extends T&gt;&nbsp;coll)</PRE>
<DL>
<DD>根据元素的<i>自然顺序</i> 返回给定 collection 的最小元素。collection 中的所有元素都必须实现 <tt>Comparable</tt> 接口。此外，collection 中的所有元素都必须是<i>可相互比较的</i>（也就是说，对于 collection 中的任何 <tt>e1</tt> 和 <tt>e2</tt> 元素，<tt>e1.compareTo(e2)</tt> 不得抛出 <tt>ClassCastException</tt>）。<p>

此方法在整个 collection 上进行迭代，所以它需要的时间与 collection 的大小成正比。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>coll</CODE> - 将确定其最小元素的 collection。
<DT><B>返回：</B><DD>根据元素的<i>自然顺序</i>，返回给定 collection 的最小元素。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/ClassCastException.html" title="java.lang 中的类">ClassCastException</A></CODE> - 如果 collection 包含不<i>可相互比较的</i> 的元素（例如，字符串和整数）。
<DD><CODE><A HREF="NoSuchElementException.html" title="java.util 中的类">NoSuchElementException</A></CODE> - 如果 collection 为空。<DT><B>另请参见：</B><DD><A HREF="../lang/Comparable.html" title="java.lang 中的接口"><CODE>Comparable</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="min(java.util.Collection, java.util.Comparator)"><!-- --></A><H3>
min</H3>
<PRE>
public static &lt;T&gt; T <B>min</B>(<A HREF="Collection.html" title="java.util 中的接口">Collection</A>&lt;? extends T&gt;&nbsp;coll,
                        <A HREF="Comparator.html" title="java.util 中的接口">Comparator</A>&lt;? super T&gt;&nbsp;comp)</PRE>
<DL>
<DD>根据指定比较器产生的顺序，返回给定 collection 的最小元素。collection 中的所有元素都必须是通过指定比较器<i>可相互比较的</i>（也就是说，对于 collection 中的任何 <tt>e1</tt> 和 <tt>e2</tt> 元素，<tt>comp.compare(e1, e2)</tt> 不得抛出 <tt>ClassCastException</tt>）。<p>

此方法在整个 collection 上进行迭代，所以它需要的时间与 collection 的大小成正比。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>coll</CODE> - 将确定其最小元素的 collection。<DD><CODE>comp</CODE> - 用来确定最小元素的比较器。<tt>null</tt> 值指示应该使用的元素的<i>自然顺序</i>。
<DT><B>返回：</B><DD>根据指定比较器返回给定 collection 的最小元素。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/ClassCastException.html" title="java.lang 中的类">ClassCastException</A></CODE> - 如果 collection 中包含使用指定的比较器不<i>可相互比较的</i> 的元素。
<DD><CODE><A HREF="NoSuchElementException.html" title="java.util 中的类">NoSuchElementException</A></CODE> - 如果 collection 为空。<DT><B>另请参见：</B><DD><A HREF="../lang/Comparable.html" title="java.lang 中的接口"><CODE>Comparable</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="max(java.util.Collection)"><!-- --></A><H3>
max</H3>
<PRE>
public static &lt;T extends <A HREF="../lang/Object.html" title="java.lang 中的类">Object</A> & <A HREF="../lang/Comparable.html" title="java.lang 中的接口">Comparable</A>&lt;? super T&gt;&gt; T <B>max</B>(<A HREF="Collection.html" title="java.util 中的接口">Collection</A>&lt;? extends T&gt;&nbsp;coll)</PRE>
<DL>
<DD>根据元素的<i>自然顺序</i>，返回给定 collection 的最大元素。collection 中的所有元素都必须实现 <tt>Comparable</tt> 接口。此外，collection 中的所有元素都必须是<i>可相互比较的</i>（也就是说，对于 collection 中的任何 <tt>e1</tt> 和 <tt>e2</tt> 元素，<tt>e1.compareTo(e2)</tt> 不得抛出 <tt>ClassCastException</tt>）。<p>

此方法在整个 collection 上进行迭代，所以它需要的时间与 collection 的大小成正比。
<P>
<DD><DL>
<DT><B>参数：</B><DD><CODE>coll</CODE> - 将确定其最大元素的 collection。
<DT><B>返回：</B><DD>根据元素的<i>自然顺序</i> 返回给定 collection 的最大元素。
<DT><B>抛出：</B>
<DD><CODE><A HREF="../lang/ClassCastException.html" title="java.lang 中的类">ClassCastException</A></CODE> - 如果 collection 包含不<i>可相互比较的</i> 的元素（例如，字符串和整数）。
<DD><CODE><A HREF="NoSuchElementException.html" title="java.util 中的类">NoSuchElementException</A></CODE> - 如果 collection 为空。<DT><B>另请参见：</B><DD><A HREF="../lang/Comparable.html" title="java.lang 中的接口"><CODE>Comparable</CODE></A></DL>
</DD>
</DL>
<HR>

<A NAME="max(java.util.Collection, java.util.Comparator)"><!-- --></A><H3>
max</H3>
<PRE>
public static &lt;T&gt; T <B>max</B>(<A HREF="Collection.htm