Java方法总结1——List

一、方法综述

public interface List<E>extends Collection<E>

       有序的 collection（也称为序列）。此接口的用户可以对列表中每个元素的插入位置进行精确地控制。用户可以根据元素的整数索引（在列表中的位置）访问元素，并搜索列表中的元素。

       与 set 不同，列表通常允许重复的元素。更确切地讲，列表通常允许满足 e1.equals(e2) 的元素对 e1 和 e2，并且如果列表本身允许 null 元素的话，通常它们允许多个 null 元素。难免有人希望通过在用户尝试插入重复元素时抛出运行时异常的方法来禁止重复的列表，但我们希望这种用法越少越好。

        List 接口在 iterator、add、remove、equals 和 hashCode 方法的协定上加了一些其他约定，超过了 Collection 接口中指定的约定。为方便起见，这里也包括了其他继承方法的声明。

        List 接口提供了 4 种对列表元素进行定位（索引）访问方法。列表（像 Java 数组一样）是基于 0 的。注意，这些操作可能在和某些实现（例如 LinkedList 类）的索引值成比例的时间内执行。因此，如果调用者不知道实现，那么在列表元素上迭代通常优于用索引遍历列表。

        List 接口提供了特殊的迭代器，称为 ListIterator，除了允许 Iterator 接口提供的正常操作外，该迭代器还允许元素插入和替换，以及双向访问。还提供了一个方法来获取从列表中指定位置开始的列表迭代器。

        List 接口提供了两种搜索指定对象的方法。从性能的观点来看，应该小心使用这些方法。在很多实现中，它们将执行高开销的线性搜索。

        List 接口提供了两种在列表的任意位置高效插入和移除多个元素的方法。

        注意：尽管列表允许把自身作为元素包含在内，但建议要特别小心：在这样的列表上，equals 和 hashCode 方法不再是定义良好的。

二、方法详细信息

	size
	int size()
	返回列表中的元素数。如果列表包含多于 Integer.MAX_VALUE 个元素，则返回 Integer.MAX_VALUE。
指定者	接口 Collection<E> 中的size
返回	列表中的元素数

	isEmpty
	boolean isEmpty()
	如果列表不包含元素，则返回true
指定者	接口 Collection<E> 中的isEmpty
返回	如果列表不包含元素，则返回true

	contains
	boolean contains(Object o)
	如果列表包含指定的元素，则返回 true。更确切地讲，当且仅当列表包含满足 (o==null ? e==null : o.equals(e)) 的元素 e 时才返回 true。
指定者	接口 Collection<E> 中的 contains
参数	o - 要测试列表中是否存在的元素
返回	如果列表包含指定的元素，则返回 true
抛出	ClassCastException- 如果指定元素的类型和此列表不兼容（可选） NullPointerException- 如果指定的元素为 null，并且此列表不允许 null 元素（可选）

	iterator
	Iterator<E> iterator()
	返回按适当顺序在列表的元素上进行迭代的迭代器
指定者	接口 Collection<E> 中的 iterator
指定者	接口 Iterable<E> 中的 iterator
返回	返回按适当顺序在列表的元素上进行迭代的迭代器

	add
	boolean add(E e)
	向列表的尾部添加指定的元素（可选操作）。
	支持该操作的列表可能对列表可以添加的元素有一些限制。特别是某些列表将拒绝添加 null 元素，其他列表将在可能添加的元素类型上施加限制。List 类应该在它们的文档中明确指定有关添加元素的所有限制。
指定者	接口 Collection<E> 中的 add
参数	e - 要添加到列表的元素
返回	true
抛出	UnsupportedOperationException - 如果列表不支持 add 操作 ClassCastException - 如果指定元素的类不允许它添加到此列表 NullPointerException - 如果指定的元素为 null，并且此列表不允许 null 元素 IllegalArgumentException - 如果此元素的某些属性不允许它添加到此列表

	remove
	boolean remove (Object o)
	从此列表中移除第一次出现的指定元素（如果存在）（可选操作）。如果列表不包含元素，则不更改列表。更确切地讲，移除满足 (o==null ? get(i)==null : o.equals(get(i))) 的最低索引 i 的元素（如果存在这样的元素）。如果此列表已包含指定元素（或者此列表由于调用而发生更改），则返回 true。
指定者	接口 Collection<E> 中的 remove
参数	o - 要从该列表中移除的元素，如果存在的话
返回	如果操作成功的话，返回 true
抛出	ClassCastException - 如果指定元素的类型和此列表不兼容（可选） NullPointerException - 如果指定的元素是 null，并且此列表不允许 null 元素（可选） UnsupportedOperationException- 如果列表不支持 remove 操作

	containsAll
	boolean containsAll(Collection<?> c)
	如果列表包含指定 collection 的所有元素，则返回 true
指定者	接口 Collection<E> 中的 containsAll
参数	c - 要在列表中检查包含性的 collection
返回	如果列表包含指定 collection 的所有元素，则返回true
抛出	ClassCsatException- 如果指定 collection 中的一个或多个元素的类型和此列表不兼容（可选） NullPointerException - 如果指定的 collection 包含一个或多个 null 元素，并且此列表不允许 null 元素（可选），或者指定的 collection 为 null

	addAll
	boolean addAll(Collection<? extends E> c)
	添加指定 collection 中的所有元素到此列表的结尾，顺序是指定 collection 的迭代器返回这些元素的顺序（可选操作）。如果在操作正在进行中修改了指定的 collection，那么此操作的行为是不确定的（注意，如果指定的 collection 是此列表，并且它是非空的，则会发生这种情况。）
指定者	接口 Collection<E> 中的 addAll
参数	c - 包含要添加到此列表的元素的 collection
返回	如果此次列表由于调用而发生改变，则返回true

	addAll
	boolean addAll (int index, Collection<? extends E> c)
	将指定 collection 中的所有元素都插入到列表中的指定位置（可选操作）。将当前处于该位置的元素（如果有的话）和所有后续元素向右移动（增加其索引）。新元素将按照它们通过指定 collection 的迭代器所返回的顺序出现在此列表中。如果在操作正在进行中修改了指定的 collection，那么该操作的行为是不确定的（注意，如果指定的 collection 是此列表，并且它是非空的，则会发生这种情况。）
参数	index - 将指定 collection 的第一个元素所插入位置的索引 c - 包含要添加到此列表的元素的 collection
返回	如果此列表由于调用而发生更改，则返回 true

	removeAll
	boolean removeAll(Collection<?> c)
	从列表中移除指定 collection 中包含的其所有元素（可选操作）。
指定者	接口 Collection<E> 中的 removeAll
参数	c - 包含从此列表中移除元素的 collection
返回	如果此列表由于调用而发生更改，则返回 true

	retainAll
	boolean retainAll(Collection<?> c)
	仅在列表中保留指定 collection 中所包含的元素（可选操作）。换句话说，该方法从列表中移除未包含在指定 collection 中的所有元素。
指定者	接口 Collection<E> 中的 retainAll
参数	c - 包含将保留在此列表中的元素的 collection
返回	如果此列表由于调用而发生更改，则返回 true

	clear
	void clear()
	从列表中移除所有元素（可选操作）。此调用返回后该列表将是空的。
指定者	接口 Collection<E> 中的 clear

	equals
	boolean equals(Object o)
	比较指定的对象与列表是否相等。当且仅当指定的对象也是一个列表、两个列表有相同的大小，并且两个列表中的所有相应的元素对相等 时才返回 true（ 如果 (e1==null ? e2==null :e1.equals(e2))，则两个元素 e1 和 e2 是相等 的）。换句话说，如果所定义的两个列表以相同的顺序包含相同的元素，那么它们是相等的。该定义确保了 equals 方法在 List 接口的不同实现间正常工作。
指定者	接口 Collection <E> 中的 equals
覆盖	类 Object 中的 equals
参数	o - 要与此列表进行相等性比较的对象
返回	如果指定对象与此列表相等，则返回 true

	hashCode
	int hashCode()
	返回列表的哈希码值。列表的哈希码定义为以下计算的结果： int hashCode = 1; Iterator<E> i = list.iterator(); while (i.hasNext()) { E obj = i.next(); hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode()); }
	这确保了 list1.equals(list2) 意味着对于任何两个列表 list1 和 list2 而言，可实现 list1.hashCode()==list2.hashCode()，正如 Object.hashCode() 的常规协定所要求的。
指定者	接口 Collection <E> 中的 hashCode
覆盖	类 Object 中的 hashCode
返回	此列表的哈希值

	get
	E get(int index)
	返回列表中指定位置的元素
参数	index - 要返回元素的索引
返回	列表中指定位置的元素

	set
	E set(int index, E element)
	用指定元素替换列表中指定位置的元素（可选操作）。
参数	index - 要替换的元素的索引 element - 要在指定位置存储的元素
返回	以前在指定位置的元素

	add
	void add(int index, E element)
	在列表的指定位置插入指定元素（可选操作）。将当前处于该位置的元素（如果有的话）和所有后续元素向右移动（在其索引中加 1）。
参数	index - 要在其中插入指定元素处的索引 element - 要插入的元素

	remove
	E remove (int index)
	移除列表中指定位置的元素（可选操作）。将所有的后续元素向左移动（将其索引减 1）。返回从列表中移除的元素。
参数	index - 要移除的元素的索引
返回	以前在指定位置的元素

	indexOf
	int indexOf(Object o)
	返回此列表中第一次出现的指定元素的索引；如果此列表不包含该元素，则返回 -1。更确切地讲，返回满足 (o==null ? get(i)==null : o.equals(get(i))) 的最低索引 i；如果没有这样的索引，则返回 -1。
参数	o - 要搜索的元素
返回	此列表中第一次出现的指定元素的索引，如果列表不包含该元素，则返回 -1

	lastIndexOf
	int lastIndexOf(Object o)
	返回此列表中最后出现的指定元素的索引；如果列表不包含此元素，则返回 -1。更确切地讲，返回满足 (o==null ? get(i)==null : o.equals(get(i))) 的最高索引 i；如果没有这样的索引，则返回 -1。
参数	o - 要搜索的元素
返回	列表中最后出现的指定元素的索引；如果列表不包含此元素，则返回 -1