List 源碼翻譯-jdk1.8
翻譯來自 AI 大模型。
全部源碼翻譯下載
/** 版權所有 (c) 1997, 2014, Oracle 和/或其附屬公司。保留所有權利。* ORACLE 專有/機密。使用受許可條款約束。*********************/package java.util;import java.util.function.UnaryOperator;/*** 有序集合(也稱為<i>序列</i>)。此接口的用戶可以精確控制列表中每個元素的插入位置。用戶可以通過整數索引(列表中的位置)訪問元素,并在列表中搜索元素。<p>** 與集合不同,列表通常允許重復元素。更正式地說,列表通常允許存在兩個元素 <tt>e1</tt> 和 <tt>e2</tt> 使得 <tt>e1.equals(e2)</tt>,并且如果允許 null 元素,通常也允許多個 null 元素。雖然可以想象有人可能希望實現一個禁止重復的列表,通過在用戶嘗試插入重復元素時拋出運行時異常,但我們預計這種用法很少見。<p>** <tt>List</tt> 接口在 <tt>Collection</tt> 接口指定的合同之外,對 <tt>iterator</tt>、<tt>add</tt>、<tt>remove</tt>、<tt>equals</tt> 和 <tt>hashCode</tt> 方法的合同提出了額外的要求。為了方便起見,這里也包括了其他繼承方法的聲明。<p>** <tt>List</tt> 接口提供了四種方法來按位置(索引)訪問列表元素。列表(如 Java 數組)是基于零的。請注意,對于某些實現,這些操作的執行時間可能與索引值成正比(例如 <tt>LinkedList</tt> 類)。因此,如果調用者不知道實現,通常遍歷列表中的元素比通過索引訪問它更可取。<p>** <tt>List</tt> 接口提供了一種特殊的迭代器,稱為 <tt>ListIterator</tt>,除了 <tt>Iterator</tt> 接口提供的正常操作外,還允許元素插入和替換以及雙向訪問。提供了一種方法來獲取從列表中指定位置開始的列表迭代器。<p>** <tt>List</tt> 接口提供了兩種方法來搜索指定的對象。從性能角度來看,應謹慎使用這些方法。在許多實現中,它們將執行代價高昂的線性搜索。<p>** <tt>List</tt> 接口提供了兩種方法來高效地在列表的任意點插入和刪除多個元素。<p>** 注意:雖然列表可以包含自身作為元素,但強烈建議謹慎使用:在這種列表上的 <tt>equals</tt> 和 <tt>hashCode</tt> 方法將不再明確定義。** <p>某些列表實現對其可能包含的元素有特定限制。例如,某些實現禁止 null 元素,而某些實現對其元素的類型有限制。嘗試添加不合格的元素將拋出未檢查的異常,通常是 <tt>NullPointerException</tt> 或 <tt>ClassCastException</tt>。嘗試查詢不合格元素的存在可能會拋出異常,或者簡單地返回 false;一些實現將表現出前者的行為,而一些實現將表現出后者的行為。更一般地說,嘗試對不合格元素執行不會導致將不合格元素插入列表的操作可能會拋出異常,或者可能會成功,具體取決于實現。此類異常在本接口的規范中被標記為“可選”。** <p>此接口是* <a href="{@docRoot}/../technotes/guides/collections/index.html">* Java Collections Framework</a> 的成員。** @param <E> 此列表中的元素類型** @author Josh Bloch* @author Neal Gafter* @see Collection* @see Set* @see ArrayList* @see LinkedList* @see Vector* @see Arrays#asList(Object[])* @see Collections#nCopies(int, Object)* @see Collections#EMPTY_LIST* @see AbstractList* @see AbstractSequentialList* @since 1.2*/public interface List<E> extends Collection<E> {// 查詢操作/*** 返回此列表中的元素數量。如果此列表包含的元素超過 <tt>Integer.MAX_VALUE</tt>,則返回 <tt>Integer.MAX_VALUE</tt>。** @return 此列表中的元素數量*/int size();/*** 如果此列表不包含任何元素,則返回 <tt>true</tt>。** @return 如果此列表不包含任何元素,則返回 <tt>true</tt>*/boolean isEmpty();/*** 如果此列表包含指定的元素,則返回 <tt>true</tt>。更正式地說,如果且僅當此列表包含至少一個元素 <tt>e</tt> 使得* <tt>(o==null ? e==null : o.equals(e))</tt>,則返回 <tt>true</tt>。** @param o 要測試其在此列表中是否存在性的元素* @return 如果此列表包含指定的元素,則返回 <tt>true</tt>* @throws ClassCastException 如果指定元素的類型與此列表不兼容* (<a href="Collection.html#optional-restrictions">可選</a>)* @throws NullPointerException 如果指定的元素為 null 且此列表不允許 null 元素* (<a href="Collection.html#optional-restrictions">可選</a>)*/boolean contains(Object o);/*** 返回一個迭代器,按正確順序遍歷此列表中的元素。** @return 按正確順序遍歷此列表中的元素的迭代器*/Iterator<E> iterator();/*** 返回一個包含此列表中所有元素的數組(從第一個到最后一個元素)。** <p>返回的數組將是“安全的”,即此列表不會維護對它的任何引用。(換句話說,即使此列表由數組支持,此方法也必須分配一個新數組)。因此,調用者可以自由地修改返回的數組。** <p>此方法充當基于數組的 API 和基于集合的 API 之間的橋梁。** @return 包含此列表中所有元素的數組* @see Arrays#asList(Object[])*/Object[] toArray();/*** 返回一個包含此列表中所有元素的數組(從第一個元素到最后一個元素);返回數組的運行時類型是指定數組的類型。如果列表適合指定的數組,則返回該數組。否則,將分配一個新的數組,其運行時類型是指定數組的類型,大小為列表的大小。** <p>如果列表適合指定的數組并且有剩余空間(即,數組的元素比列表多),則數組中緊跟在列表末尾的元素被設置為 <tt>null</tt>。* (這僅在調用者知道列表中不包含任何 null 元素時,用于確定列表的長度是有用的。)** <p>像 {@link #toArray()} 方法一樣,此方法充當基于數組和基于集合的 API 之間的橋梁。此外,此方法允許對輸出數組的運行時類型進行精確控制,并且在某些情況下,可以用來節省分配成本。** <p>假設 <tt>x</tt> 是一個已知僅包含字符串的列表。以下代碼可用于將列表轉儲到新分配的 <tt>String</tt> 數組中:** <pre>{@code* String[] y = x.toArray(new String[0]);* }</pre>** 請注意,<tt>toArray(new Object[0])</tt> 在功能上與 <tt>toArray()</tt> 相同。** @param a 如果足夠大,則將此列表中的元素存儲到此數組中;否則,為此目的分配一個新的相同運行時類型的數組。* @return 包含此列表中元素的數組* @throws ArrayStoreException 如果指定數組的運行時類型不是此列表中每個元素的運行時類型的超類型* @throws NullPointerException 如果指定的數組為 null*/<T> T[] toArray(T[] a);// 修改操作/*** 將指定的元素添加到此列表的末尾(可選操作)。** <p>支持此操作的列表可能對可以添加到此列表中的元素施加限制。特別是,某些列表將拒絕添加 null 元素,而其他列表將對可以添加的元素類型施加限制。列表類應在文檔中明確指定對可以添加的元素的任何限制。** @param e 要添加到此列表的元素* @return <tt>true</tt>(如 {@link Collection#add} 所指定)* @throws UnsupportedOperationException 如果此列表不支持 <tt>add</tt> 操作* @throws ClassCastException 如果指定元素的類阻止其被添加到此列表* @throws NullPointerException 如果指定的元素為 null 而此列表不允許 null 元素* @throws IllegalArgumentException 如果此元素的某些屬性阻止其被添加到此列表*/boolean add(E e);/*** 如果存在,則從此列表中移除指定元素的第一個出現(可選操作)。如果此列表不包含該元素,則列表不變。更正式地說,移除索引 <tt>i</tt> 最低的元素,使得* <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>* (如果存在這樣的元素)。如果此列表包含指定的元素(或等效地,如果此列表因調用而改變),則返回 <tt>true</tt>。** @param o 要從此列表中移除的元素(如果存在)* @return <tt>true</tt> 如果此列表包含指定的元素* @throws ClassCastException 如果指定元素的類型與此列表不兼容* (<a href="Collection.html#optional-restrictions">可選</a>)* @throws NullPointerException 如果指定的元素為 null 而此列表不允許 null 元素* (<a href="Collection.html#optional-restrictions">可選</a>)* @throws UnsupportedOperationException 如果此列表不支持 <tt>remove</tt> 操作*/boolean remove(Object o);// 批量修改操作/*** 如果此列表包含指定集合中的所有元素,則返回 <tt>true</tt>。** @param c 要檢查是否包含在此列表中的集合* @return <tt>true</tt> 如果此列表包含指定集合中的所有元素* @throws ClassCastException 如果指定集合中的一個或多個元素的類型與此列表不兼容* (<a href="Collection.html#optional-restrictions">可選</a>)* @throws NullPointerException 如果指定的集合包含一個或多個 null 元素而此列表不允許 null 元素* (<a href="Collection.html#optional-restrictions">可選</a>),或指定的集合為 null* @see #contains(Object)*/boolean containsAll(Collection<?> c);/*** 將指定集合中的所有元素按指定集合的迭代器返回的順序添加到此列表的末尾(可選操作)。如果在操作進行過程中修改了指定的集合,此操作的行為是未定義的。(請注意,如果指定的集合是此列表,并且它非空,則會發生這種情況。)** @param c 包含要添加到此列表的元素的集合* @return <tt>true</tt> 如果此列表因調用而改變* @throws UnsupportedOperationException 如果此列表不支持 <tt>addAll</tt> 操作* @throws ClassCastException 如果指定集合中的元素的類阻止其被添加到此列表* @throws NullPointerException 如果指定的集合包含一個或多個 null 元素而此列表不允許 null 元素,或指定的集合為 null* @throws IllegalArgumentException 如果指定集合中的元素的某些屬性阻止其被添加到此列表* @see #add(Object)*/boolean addAll(Collection<? extends E> c);/*** 將指定集合中的所有元素插入到此列表的指定位置(可選操作)。將當前位置(如果有)及其后續元素向右移動(增加它們的索引)。新元素將按照指定集合的迭代器返回的順序出現在此列表中。如果在操作進行過程中修改了指定的集合,則此操作的行為是未定義的。(注意,如果指定的集合是此列表,并且它非空,則會發生這種情況。)** @param index 指定集合中的第一個元素要插入的位置* @param c 包含要添加到此列表的元素的集合* @return 如果此列表因調用而改變,則返回 <tt>true</tt>* @throws UnsupportedOperationException 如果此列表不支持 <tt>addAll</tt> 操作* @throws ClassCastException 如果指定集合中元素的類阻止它被添加到此列表* @throws NullPointerException 如果指定集合包含一個或多個 null 元素且此列表不允許 null 元素,或者指定的集合為 null* @throws IllegalArgumentException 如果指定集合中元素的某些屬性阻止它被添加到此列表* @throws IndexOutOfBoundsException 如果索引超出范圍* (<tt>index < 0 || index > size()</tt>)*/boolean addAll(int index, Collection<? extends E> c);/*** 從此列表中移除所有包含在指定集合中的元素(可選操作)。** @param c 包含要從此列表中移除的元素的集合* @return 如果此列表因調用而改變,則返回 <tt>true</tt>* @throws UnsupportedOperationException 如果此列表不支持 <tt>removeAll</tt> 操作* @throws ClassCastException 如果此列表中元素的類與指定集合不兼容* (<a href="Collection.html#optional-restrictions">可選</a>)* @throws NullPointerException 如果此列表包含 null 元素且指定集合不允許 null 元素* (<a href="Collection.html#optional-restrictions">可選</a>),* 或者指定的集合為 null* @see #remove(Object)* @see #contains(Object)*/boolean removeAll(Collection<?> c);/*** 僅保留此列表中包含在指定集合中的元素(可選操作)。換句話說,從此列表中移除所有不包含在指定集合中的元素。** @param c 包含要在此列表中保留的元素的集合* @return 如果此列表因調用而改變,則返回 <tt>true</tt>* @throws UnsupportedOperationException 如果此列表不支持 <tt>retainAll</tt> 操作* @throws ClassCastException 如果此列表中元素的類與指定集合不兼容* (<a href="Collection.html#optional-restrictions">可選</a>)* @throws NullPointerException 如果此列表包含 null 元素且指定集合不允許 null 元素* (<a href="Collection.html#optional-restrictions">可選</a>),* 或者指定的集合為 null* @see #remove(Object)* @see #contains(Object)*/boolean retainAll(Collection<?> c);/*** 將此列表中的每個元素替換為應用操作符后得到的結果。操作符拋出的錯誤或運行時異常將傳遞給調用者。** @implSpec* 默認實現等效于,對于此 {@code list}:* <pre>{@code* final ListIterator<E> li = list.listIterator();* while (li.hasNext()) {* li.set(operator.apply(li.next()));* }* }</pre>** 如果列表的列表迭代器不支持 {@code set} 操作,則在替換第一個元素時將拋出 {@code UnsupportedOperationException}。** @param operator 要應用于每個元素的操作符* @throws UnsupportedOperationException 如果此列表不可修改。* 實現可能在元素無法被替換或通常不支持修改時拋出此異常* @throws NullPointerException 如果指定的操作符為 null 或操作符結果為 null 值且此列表不允許 null 元素* (<a href="Collection.html#optional-restrictions">可選</a>)* @since 1.8*/default void replaceAll(UnaryOperator<E> operator) {Objects.requireNonNull(operator);final ListIterator<E> li = this.listIterator();while (li.hasNext()) {li.set(operator.apply(li.next()));}}/*** 根據指定的 {@link Comparator} 確定的順序對此列表進行排序。** <p>此列表中的所有元素必須使用指定的比較器 <i>相互可比較</i>(即,對于列表中的任何元素 {@code e1} 和 {@code e2},{@code c.compare(e1, e2)} 不應拋出 {@code ClassCastException})。** <p>如果指定的比較器為 {@code null},則此列表中的所有元素必須實現 {@link Comparable} 接口,并且應使用元素的 {@linkplain Comparable 自然順序}。** <p>此列表必須是可修改的,但不必是可調整大小的。** @implSpec* 默認實現獲取包含此列表中所有元素的數組,對數組進行排序,并迭代此列表,從數組的相應位置重置每個元素。(這避免了嘗試就地對鏈表進行排序時可能導致的 n<sup>2</sup> log(n) 性能。)** @implNote* 此實現是一個穩定的、適應性的、迭代的歸并排序,當輸入數組部分排序時,所需的比較次數遠少于 n lg(n),而當輸入數組隨機排序時,提供傳統歸并排序的性能。如果輸入數組幾乎已排序,實現所需的比較次數大約為 n。臨時存儲需求從幾乎已排序的輸入數組的小常數到隨機排序的輸入數組的 n/2 對象引用不等。** <p>實現同樣利用輸入數組中的升序和降序,并且可以利用同一輸入數組中不同部分的升序和降序。它非常適合合并兩個或多個已排序的數組:只需將數組連接起來并排序結果數組。** <p>實現改編自 Tim Peters 為 Python 編寫的列表排序* (<a href="http://svn.python.org/projects/python/trunk/Objects/listsort.txt">* TimSort</a>)。它使用了 Peter McIlroy 的 "Optimistic Sorting and Information Theoretic Complexity" 中的技術,該文發表在第四屆年度 ACM-SIAM 離散算法研討會論文集,第 467-474 頁,1993 年 1 月。** @param c 用于比較列表元素的 {@code Comparator}。* {@code null} 值表示應使用元素的 {@linkplain Comparable 自然順序}* @throws ClassCastException 如果列表包含使用指定比較器 <i>相互不可比較</i> 的元素* @throws UnsupportedOperationException 如果列表的列表迭代器不支持 {@code set} 操作* @throws IllegalArgumentException* (<a href="Collection.html#optional-restrictions">可選</a>)* 如果發現比較器違反了 {@link Comparator} 合約* @since 1.8*/@SuppressWarnings({"unchecked", "rawtypes"})default void sort(Comparator<? super E> c) {Object[] a = this.toArray();Arrays.sort(a, (Comparator) c);ListIterator<E> i = this.listIterator();for (Object e : a) {i.next();i.set((E) e);}}/*** 從此列表中移除所有元素(可選操作)。* 調用此方法后,列表將為空。** @throws UnsupportedOperationException 如果此列表不支持 <tt>clear</tt> 操作*/void clear();// 比較和哈希/*** 將指定對象與此列表進行相等性比較。僅當指定對象也是一個列表,兩個列表具有相同的大小,并且兩個列表中所有對應的元素對都是 <i>相等</i> 時,返回 <tt>true</tt>。* (兩個元素 <tt>e1</tt> 和 <tt>e2</tt> 是 <i>相等</i> 的,如果 <tt>(e1==null ? e2==null : e1.equals(e2))</tt>。)換句話說,* 兩個列表如果包含相同順序的相同元素,則定義為相等。此定義確保 <tt>equals</tt> 方法在 <tt>List</tt> 接口的不同實現之間正確工作。** @param o 要與此列表進行相等性比較的對象* @return 如果指定對象與此列表相等,則返回 <tt>true</tt>*/boolean equals(Object o);/*** 返回此列表的哈希碼值。列表的哈希碼定義為以下計算的結果:* <pre>{@code* int hashCode = 1;* for (E e : list)* hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());* }</pre>* 這確保了對于任何兩個列表 <tt>list1</tt> 和 <tt>list2</tt>,<tt>list1.equals(list2)</tt> 意味著 <tt>list1.hashCode()==list2.hashCode()</tt>,* 符合 {@link Object#hashCode} 的一般約定。** @return 此列表的哈希碼值* @see Object#equals(Object)* @see #equals(Object)*/int hashCode();// 位置訪問操作/*** 返回此列表中指定位置的元素。** @param index 要返回的元素的索引* @return 此列表中指定位置的元素* @throws IndexOutOfBoundsException 如果索引超出范圍* (<tt>index < 0 || index >= size()</tt>)*/E get(int index);/*** 用指定元素替換此列表中指定位置的元素(可選操作)。** @param index 要替換的元素的索引* @param element 要存儲在指定位置的元素* @return 之前位于指定位置的元素* @throws UnsupportedOperationException 如果此列表不支持 <tt>set</tt> 操作* @throws ClassCastException 如果指定元素的類阻止其被添加到此列表* @throws NullPointerException 如果指定元素為 null 且此列表不允許 null 元素* @throws IllegalArgumentException 如果指定元素的某些屬性阻止其被添加到此列表* @throws IndexOutOfBoundsException 如果索引超出范圍* (<tt>index < 0 || index >= size()</tt>)*/E set(int index, E element);/*** 在此列表的指定位置插入指定元素(可選操作)。將當前位置(如果有)和后續元素向右移動(索引加一)。** @param index 要插入指定元素的位置* @param element 要插入的元素* @throws UnsupportedOperationException 如果此列表不支持 <tt>add</tt> 操作* @throws ClassCastException 如果指定元素的類阻止其被添加到此列表* @throws NullPointerException 如果指定元素為 null 且此列表不允許 null 元素* @throws IllegalArgumentException 如果指定元素的某些屬性阻止其被添加到此列表* @throws IndexOutOfBoundsException 如果索引超出范圍* (<tt>index < 0 || index > size()</tt>)*/void add(int index, E element);/*** 從此列表中移除指定位置的元素(可選操作)。將后續元素向左移動(索引減一)。返回被移除的元素。** @param index 要移除的元素的索引* @return 之前位于指定位置的元素* @throws UnsupportedOperationException 如果此列表不支持 <tt>remove</tt> 操作* @throws IndexOutOfBoundsException 如果索引超出范圍* (<tt>index < 0 || index >= size()</tt>)*/E remove(int index);// 搜索操作/*** 返回此列表中第一次出現的指定元素的索引,如果此列表不包含該元素,則返回 -1。* 更正式地說,返回最低的索引 <tt>i</tt>,使得 <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,* 如果沒有這樣的索引,則返回 -1。** @param o 要搜索的元素* @return 此列表中第一次出現的指定元素的索引,如果此列表不包含該元素,則返回 -1* @throws ClassCastException 如果指定元素的類型與此列表不兼容* (<a href="Collection.html#optional-restrictions">可選</a>)* @throws NullPointerException 如果指定元素為 null 且此列表不允許 null 元素* (<a href="Collection.html#optional-restrictions">可選</a>)*/int indexOf(Object o);/*** 返回此列表中最后一次出現的指定元素的索引,如果此列表不包含該元素,則返回 -1。* 更正式地說,返回最高的索引 <tt>i</tt>,使得 <tt>(o==null ? get(i)==null : o.equals(get(i)))</tt>,* 如果沒有這樣的索引,則返回 -1。** @param o 要搜索的元素* @return 此列表中最后一次出現的指定元素的索引,如果此列表不包含該元素,則返回 -1* @throws ClassCastException 如果指定元素的類型與此列表不兼容* (<a href="Collection.html#optional-restrictions">可選</a>)* @throws NullPointerException 如果指定元素為 null 且此列表不允許 null 元素* (<a href="Collection.html#optional-restrictions">可選</a>)*/int lastIndexOf(Object o);// 列表迭代器/*** 返回一個迭代器,用于遍歷此列表中的元素(按正確的順序)。** @return 一個迭代器,用于遍歷此列表中的元素(按正確的順序)*/ListIterator<E> listIterator();/*** 返回一個迭代器,用于從列表中指定位置開始遍歷元素(按正確的順序)。* 指定的索引表示通過初始調用 {@link ListIterator#next next} 將返回的第一個元素。* 通過初始調用 {@link ListIterator#previous previous} 將返回指定索引減一的元素。** @param index 列表迭代器返回的第一個元素的索引(通過調用 {@link ListIterator#next next})* @return 一個迭代器,用于從列表中指定位置開始遍歷元素(按正確的順序)* @throws IndexOutOfBoundsException 如果索引超出范圍* ({@code index < 0 || index > size()})*/ListIterator<E> listIterator(int index);// 視圖/*** 返回此列表中指定的 <tt>fromIndex</tt>(包含)到 <tt>toIndex</tt>(不包含)之間的部分視圖。* (如果 <tt>fromIndex</tt> 和 <tt>toIndex</tt> 相等,返回的列表為空。)* 返回的列表由這個列表支持,因此返回列表中的非結構化更改會反映在這個列表中,反之亦然。* 返回的列表支持此列表支持的所有可選列表操作。<p>** 此方法消除了顯式范圍操作的需要(通常數組中存在此類操作)。* 任何期望列表的操作都可以通過傳遞子列表視圖而不是整個列表來作為范圍操作使用。* 例如,以下慣用法從列表中移除一個范圍的元素:* <pre>{@code* list.subList(from, to).clear();* }</pre>* 類似的慣用法可以為 <tt>indexOf</tt> 和 <tt>lastIndexOf</tt> 構建,* 并且 <tt>Collections</tt> 類中的所有算法都可以應用于子列表。<p>** 如果此列表(即支持列表)以任何方式被 <i>結構化修改</i>,除了通過返回的列表,* 返回列表的語義將變得未定義。(結構化修改是指改變此列表大小或以其他方式干擾列表,* 使得正在進行的迭代可能產生不正確的結果。)** @param fromIndex 子列表的低端點(包含)* @param toIndex 子列表的高端點(不包含)* @return 此列表中指定范圍的視圖* @throws IndexOutOfBoundsException 對于非法的端點索引值* (<tt>fromIndex < 0 || toIndex > size ||* fromIndex > toIndex</tt>)*/List<E> subList(int fromIndex, int toIndex);/*** 創建一個 {@link Spliterator} 用于遍歷此列表中的元素。** <p>此 {@code Spliterator} 報告 {@link Spliterator#SIZED} 和* {@link Spliterator#ORDERED}。實現應記錄額外的特征值。** @implSpec* 默認實現從列表的 {@code Iterator} 創建一個* <em><a href="Spliterator.html#binding">延遲綁定</a></em> 的 {@code Spliterator}。* 該 {@code Spliterator} 繼承了列表迭代器的 <em>快速失敗</em> 屬性。** @implNote* 創建的 {@code Spliterator} 另外報告* {@link Spliterator#SUBSIZED}。** @return 一個遍歷此列表中元素的 {@code Spliterator}* @since 1.8*/@Overridedefault Spliterator<E> spliterator() {return Spliterators.spliterator(this, Spliterator.ORDERED);}
}