List接口英文注释翻译

    一个有序的容器（也被称为序列）。接口使用者可以精确控制列表中每个元素的插入位置。用户可以通过整数索引
（列表中的位置）访问元素，还能查找列表中的元素。   
   
    不像集合，列表通常允许重复元素。更正式点的说法是，列表通常允许满足e1.equals(e2)这样的e1和e2元素对，
另外如果允许空元素通常也会允许多个空元素。有人想通过当使用者尝试插入重复元素时抛出运行时异常的方式，来实
现禁止重复元素的列表，这并非不可思议，但我们希望这种用法很少见。

    List接口在迭代、添加、删除、相等、哈希值方法的契约上，除了在Collection中已经指定的规定，还附加了额外
的规定。为了方便，这里还包含了其他继承方法的声明。 
  
    列表提供了四种位置（索引）访问列表元素的方法。列表（就像java数组）基于0.注意下在一些实现中，这些操作
执行的时间与索引值成正比（比如LinkedList类）。因此，如果调用者不知道实现，在一个列表中迭代元素通常比进行
索引更好。

    List接口提供了一个特殊的迭代器，叫做ListIterator，它除了Iterator接口提供的普通操作，还允许元素插入、
替换和双向访问。提供了一个方法，可以获取从列表指定位置开始的列表迭代器。

    List接口提供了两个方法查找一个特定对象。从性能角度触发，这些方法应该被慎重使用。在很多实现中，他们会
执行代价高的线性查找。

    List接口提供了两个高效的在列表随机位置插入和删除多个元素的方法。

    注意：虽然列表允许将自己当成元素包含，但是建议要极其谨慎：equals和hashcode方法在这样的列表中将不再有
效。

    一些列表实现对他们可能要包含的元素有严格限制。例如，一些实现禁止空元素，一些对他们的元素类型严格限制
。当尝试添加一个不合格的元素，会抛出未检查异常，通常是NullPointerException或ClassCastException。当尝试查
询一个不合格元素是否存在，可能抛出一个异常，或者可能仅仅返回false；一些实现将展现前一种行为（备注：抛出
一个异常），另一些则展现后者(返回false)。更普遍地，当尝试对一个不合格元素进行操作，完成该操作不会导致不
合格元素被插入到列表中，可能会抛出异常，也可能成功(备注：不是真正成功,只是不报错)，由实现决定。根据实现
的选择。此类异常在这个接口被标记为"可选的"。




/**
    返回列表中元素的数量。 如果这个列表包含比Integer.MAX_VALUE还多的元素，则返回Integer.MAX_VALUE
**/
int size();



/**
    如果这个列表没有元素返回true
**/
boolean isEmpty();



/**
    如果列表包含指定的元素则返回true。更正式地说，当且仅当这个列表包含至少一个这样的e元素，满足：
o == null ? e == null : o.equals(e)

@param o 检验在这个列表中是否存在的元素
@throws 如果指定元素的类型与这个列表不兼容抛出ClassCastException
@throws 如果指定元素是空并且这个列表不允许空元素抛出NullPointerException
**/
boolean contains(Object o);



/**
    以固定顺序返回列表元素的迭代器
**/
Iterator<E> iterator();



/**
    返回一个以固定顺序包含列表中所有元素的数组（从第一个到最后一个元素）。
    返回的数组是安全的，因为这个列表不会保留对它的引用（换句话说，这个方法必须分配一个新的数组，即使这个
列表由数组支持）。因此调用者可以自由修改返回的数组。
    这个方法充当基于数组和基于容器的api的桥梁
**/
Object[] toArray();


/**
    返回以固定顺序包含列表中所有元素的数组（从第一个元素到最后一个元素）；返回数组的运行时类型就是指定数
组的类型。如果列表适合指定数组，则返回该数组。否则，用指定数组的运行时类型和这个列表长度分配新的数组。
    如果列表适合指定数组，并有多余空间（比如：数组比列表有更多元素），数组中紧跟在集合末尾之后的元素会立
即被设置为null。（仅当调用者知道列表不包含任何空元素，对确定列表的长度很有用）。
    就像toArray()方法，这个方法充当了基于数组和基于容器的api之间的桥梁。更进一步，这个方法允许对输出数组
的运行时类型进行精确控制，在某些情况下，被用来节省分配成本。（备注：当列表长度小于指定数组时，可以重复
使用指定数组接收输出数组, 而toArray()方法每次都需要重新分配Object数组）
    假设x是一个已知的仅包含字符串的列表。下面的代码被用来将列表转入到一个新分配的字符串数组中。
 
    String[] y = x.toArray(new String[0]);
 
    注意 toArray(new Object[0]) 在功能上与toArray()相同
 
 
 @param 如果它足够大，则为要将列表中元素存储到其中的数组；否则，为此要分配相同运行时类型的新数组
 @throws 如果指定数组的运行时类型不是列表中每个元素的父类，抛出ArrayStoreException 
 @throws 如果指定数组是空抛出NullPointerException

**/
T[] toArray(T[] a)



/**
    将指定元素添加到这个列表的末尾（可选操作）
    支持这个操作的列表可能对什么样的元素被添加到这个列表中有限制，尤其，一些列表不能添加空元素，其他的对
被添加的元素类型有强制限制。列表类应该在他们文档中清楚指明限制哪些元素可以被添加。
 
 @param e 被添加到列表中的元素
 @throws 如果add操作不被这个列表支持,则抛出UnsupportedOperationException
 @throws 如果指定元素的类不被允许添加到这个元素，则抛出ClassCastException
 @throws 如果指定元素为空，而且这个列表不允许空元素时，抛出NullPointerException
 @throws 如果元素中的一些属性不被允许添加到这个列表

**/
boolean add(E e);



/**
    如果存在的话，从列表中删除指定元素的第一个匹配元素。如果这个列表不包含此元素，它不会被改变。 更正式地
，删除满足(o==null ? get(i)==null : o.equals(get(i))) 最小索引i的元素（如果存在这样一个元素）。如果这个
列表包含指定的元素则返回true（或者等效，如果列表由于此调用而改变了）

 @param o 如果存在，为被从这个列表删除的元素
 @throws 如果指定元素的类型和这个列表不兼容抛出ClassCastException
 @throws 如果指定元素为空，并且这个列表不允许空元素抛出NullPointerException
 @throws 如果删除操作不被这个列表支持。
**/

boolean remove(Object o);



/**
    如果这个列表包含指定容器的所有元素则返回true。
  
 @param c 在此列表中检查是否包含的容器
 @throws ClassCastException 如果指定容器中的一个或多个元素的类型与这个列表不兼容
 @throws NullPointerException 如果指定容器包含一个或多个元素，而这个列表不支持空元素或者指定容器为空

**/
boolean containsAll(Collection<?> c);



/**
    按照指定容器迭代的顺序，将指定容器中的所有元素添加到这个列表的末尾（可选操作）。如果指定容器在操作过
程中被改变了，这个操作行为将不明确。（注意如果指定容器是这个列表，并且非空，这个将会发生）
 
 @param c 包含要被添加到这个列表的容器
 @throws UnsupportedOperationException 如果addAll操作不被这个列表支持
 @throws ClassCastException 如果指定容器中一个元素的类不支持被添加到这个列表
 @throws NullPointerException 如果指定容器包含一个或多个元素，而这个列表不支持空元素或者指定容器为空
 @throws IllegalArgumentException 如果指定容器中一个元素的一些属性不支持添加到这个列表中

**/
boolean addAll(Collection<? extends E> c);



/**
    将指定容器中所有元素插入到这个列表中的指定位置。将当前在该位置（如果有的话）的元素和后面元素向右移动
(增加他们的下标)。新的元素将以指定容器迭代返回的顺序出现在这个列表中。如果指定容器在操作过程中被改变了，
这个操作将不明确。（注意如果指定容器是这个列表，并且非空，这个将会发生）

 @param c 包含要被添加到这个列表的容器
 @throws 如果addAll操作不被这个列表支持，抛出UnsupportedOperationException 
 @throws 如果指定容器中一个元素的类不被允许添加到这个列表，抛出ClassCastException
 @throws NullPointerException 如果指定容器包含一个或多个空元素，而这个列表不支持空元素或者指定容器为空
 @throws IllegalArgumentException 如果指定容器的元素的一些属性不被允许添加到这个列表中
 @throws IndexOutOfBoundsException 如果下标超出了范围
 
**/
boolean addAll(int index, Collection<? extends E> c);



/**
    从列表中删除指定容器中的所有元素(可选操作)
 
 @param c 包含要被从这个列表中删除元素的容器
 @return 如果这个列表因为这个调用被修改了, 返回true
 @throws 如果removeAll操作不被这个列表支持，抛出UnsupportedOperationException
 @throws 如果这个列表中一个元素的类与指定容器不兼容(可选)， 抛出ClassCastException
 @throws NullPointerException 如果这个列表包含空元素，而指定容器不容许空元素,或者指定元素是空元素
 **/
boolean removeAll(Collection<?> c);



/**
    只保留列表中包含在指定容器的元素(可选操作)。换句话，从这个列表中删除没有包含在指定容器的元素。
 
 @param c 包含要保留在这个列表元素的容器
 @return true 如果这个列表因为这个调用而被改变了
 @throws UnsupportedOperationException 如果retainAll操作不被这个列表支持
 @throws ClassCastException 如果这个列表中一个元素的类与指定容器不兼容(可选)
 @throws NullPointerException 如果这个列表包含空元素，而指定容器不容许空元素,或者指定元素是空元素
**/
boolean retainAll(Collection<?> c);



/**
    删除这个列表中所有元素(可选操作).在这个调用返回之后，这个列表将被清空
  
 @throws UnsupportedOperationException 如果clear操作不被这个列表支持

**/
void clear();



//  比较和hash

/**
    将指定对象和这个列表进行相等性比较. 当且仅当指定对象也是一个列表，两个列表有相同的大小，两个列表
中所有对应的元素对都是相等的。(两个元素e1和e2如果满足e1==null ? e2==null : e1.equals(e2)，那么e1
和e2相等)。换句话说，如果两个元素包含相同顺序的相同元素，那么他们被定义为相等。这个定义保证了equals
方法适用于List接口不同实现。

 @param o 被用于与这个列表进行相等性比较的对象
 @return true 如果指定对象与这个列表相等 
**/
boolean equals(Object o);



/**
    返回这个列表的hash码值。这个列表的hash值被定义为下面的计算结果：
    int hashCode = 1;
    for (E e : list)
         hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());	
    按照hashCode的通常约定，这个保证了对于任何两个列表list1和list2，list1.equals(list2)意味着
list1.hashCode()==list2.hashCode()
		 
	@return 返回这个列表的hash码值
**/
int hashCode();



/**
    返回这个列表中指定位置的元素
 
 @param index 要返回元素的下标
 @return 这个列表指定位置的元素
 @throws IndexOutOfBoundsException 如果下标超出范围（index < 0 || index > size() ）
**/
E get(int index);



/**
    用指定元素替换这个列表中指定位置的元素(可选操作)。
 
 @param index 被替换元素的下标
 @param element 被保存到指定位置的元素
 @return 返回指定位置之前的元素
 @throws UnsupportedOperationException 如果set操作不被这个列表支持
 @throws NullPointerException 如果这个列表包含空元素，而指定容器不容许空元素
 @throws IllegalArgumentException 如果指定元素的一些属性不能被添加到这个列表
 @throws IndexOutOfBoundsException 如果下标超出范围（index < 0 || index > size() ） 
**/
E set(int index, E element);



/**
    在这个列表的指定位置插入指定元素.当前位置的元素(如果有的话)和后面序列的元素都向右移动
(下标会加一)

 @param index 被插入指定元素的下标
 @param element 被插入的元素
 @throws UnsupportedOperationException 如果set操作不被这个列表支持
 @throws ClassCastException 如果指定元素的类不能被添加到这个列表中
 @throws NullPointerException 如果这个列表包含空元素，而指定容器不容许空元素
 @throws IllegalArgumentException 如果指定元素的一些属性不能被添加到这个列表
 @throws IndexOutOfBoundsException 如果下标超出范围（index < 0 || index > size() ） 

**/
void add(int index, E element);



/**
    删除这个列表中指定位置的元素(可选操作).后序元素会向左移动(索引减1)。返回被从列表中删除
的元素

 @param 被删除元素的下标
 @return 指定位置之前的元素
 @throws UnsupportedOperationException 如果remove不被这个列表支持
 @throws IndexOutOfBoundsException 如果下标超出范围（index < 0 || index > size() ）
 
**/
E remove(int index);



/**
    返回指定元素在列表中第一次匹配的下标。如果这个列表不包含元素返回-1。更正式地，返回最小下标i,
满足(o==null ? get(i) == null : o.equals(get(i)))，如果没有此下标返回-1

 @param o 要查找的元素
 @return 指定元素在列表中第一次匹配的下标。如果这个列表不包含元素返回-1
 @throws ClassCastException 如果指定元素的类型和这个列表不兼容（可选）
 @throws NullPointerException 如果指定元素是空，而这个列表不允许空元素(可选)

**/
int indexOf(Object o);



/**
    返回指定元素在列表中最后一次匹配的下标。如果这个列表不包含元素返回-1。更正式地，返回最小下标i,
满足(o==null ? get(i) == null : o.equals(get(i)))，如果没有此下标返回-1

 @param o 要查找的元素
 @return 指定元素在列表中第一次匹配的下标。如果这个列表不包含元素返回-1
 @throws ClassCastException 如果指定元素的类型和这个列表不兼容（可选）
 @throws NullPointerException 如果指定元素是空，而这个列表不允许空元素(可选)

**/
int lastIndexOf(Object o);



/**
    返回列表元素的列表迭代器
 
 @return 返回列表元素的列表迭代器(固定顺序)

**/
ListIterator<E> listIterator();



/**
    返回列表中指定位置开始的元素迭代器(固定顺序)。指定下标指明了ListIterator的next方法初始调用返回
的第一个元素。ListIterator的previous方法初始调用将返回执行减1的元素。

 @param 从列表迭代器中返回的第一个元素的下标（即ListIterator的next方法调用）
 @return 返回列表中指定位置开始的元素迭代器(固定顺序)
 @throws IndexOutOfBoundsException 如果下标超出范围（index < 0 || index > size() ） 
 
**/
ListIterator<E> listIterator(int index);



/**
    返回指定下标fromIndex（包含）到toIndex（不包含）之间的部分列表的视图。（如果fromIndex和toIndex是
相等的，返回的列表为空。）返回的列表基于这个列表，所以返回列表有非结构性改变也会反映到这个列表，反
之亦然。返回列表同样支持这个列表支持的所有可选列表操作。
    这个方法消除了显示范围操作的需求（这样的通常存在于数组）。任何需要列表的操作都可以通过传递subList
视图用作范围操作，而不是整个列表。例如：下面列表范围元素的惯用语法:
    list.subList(from, to).clear();
    可以为indexOf和lastIndexOf构造相似的惯用语法，Collections类的所有算法都能应用到subList。
    如果背后的列表不仅仅通过返回列表被结构性改变，返回列表的语义将不明确（结构改变指改变列表大小，或者
以正在迭代中的形式干扰，可能产生不正确的结果）
 
 @param fromIndex subList的低端（包含）
 @param toIndex subList的高端（不包含）
 @return 返回这个列表指定范围的视图
 @throws IndexOutOfBoundsException 非法的端下标值（fromIndex <0 || toIndex > size || fromIndex > toIndex）

**/
List<E> subList(int fromIndex, int toIndex);

 👉👉👉 自己搭建的租房网站：全网租房助手，m.kuairent.com，每天新增 500+房源