java.util
インタフェース List<E>

すべてのスーパーインタフェース:

Collection<E>, Iterable<E>

既知の実装クラスの一覧:

AbstractList, AbstractSequentialList, ArrayList, AttributeList, CopyOnWriteArrayList, LinkedList, RoleList, RoleUnresolvedList, Stack, Vector

public interface List<E>
extends Collection<E>

順序付けられたコレクションです。 「シーケンス」とも呼ばれます。このインタフェースのユーザーは、リスト内のどこに各要素が挿入されるかを精密に制御できます。ユーザーは整数値のインデックス (リスト内の位置) によって要素にアクセスしたり、リスト内の要素を検索したりすることができます。

セットとは異なり、通常、リストは重複する要素を許可します。つまり、リストは、通常 e1.equals(e2) となるような、e1 と e2 の要素のペアを許可します。 また、null 要素を許可する場合には、通常は複数の null 要素を許可します。ユーザーが重複する値を挿入しようとしたときに実行時の例外をスローすることにより、重複する値を禁止するリストを実装する場合もありますが、このように使われることはほとんどありません。

List インタフェースは、iterator、add、remove、equals、および hashCode の各メソッドの規約に対して、Collection インタフェースで指定されているものに加えてさらに条項を追加します。便宜上、ほかの継承メソッドの宣言もここに含まれます。

List インタフェースは、位置を指定して (インデックスで) リストの要素にアクセスするための 4 つのメソッドを提供します。Java 配列と同様に、List のインデックスは 0 から始まります。一部の実装 (LinkedList クラスなど) では、これらのオペレーションの実行にはインデックス値に比例した時間がかかる場合があります。このため、呼び出し側がこうした実装について知らない場合は、リストにインデックスを付けるよりも、リスト内の要素の繰り返し処理を行なってください。

List インタフェースは、Iterator インタフェースが提供する通常のオペレーションに加えて、要素の挿入、置換、および双方向アクセスを可能にする、ListIterator という特殊な反復子を提供します。リスト内の指定した位置から開始するリスト反復子を取得するためのメソッドが提供されています。

List インタフェースは、指定したオブジェクトを検索するための 2 つのメソッドを提供します。パフォーマンスの観点からは、これらのメソッドは注意して使用する必要があります。多くの実装でこれらのメソッドは、時間のかかる線形探索を実行します。

リスト内の任意の位置に複数の要素を効率的に挿入および削除するために、List インタフェースは 2 つのメソッドを提供します。

注:リストにリスト自体を要素として格納することも可能ですが、十分注意してください。そのようなリストでは equals メソッドおよび hashCode メソッドの動作は保証されません。

リストの実装には、格納できる要素に制限があるものもあります。たとえば、null 要素を禁止する実装や、null 要素の型に制限がある実装もあります。不適当な要素を追加しようとすると、通常 NullPointerException または ClassCastException のようなチェックされない例外がスローされます。不適当な要素を照会しようとすると、例外がスローされる場合や、ただ false を返す場合もあります。 前の動作を禁止する実装もあれば、後の動作を禁止する実装もあります。もう少し一般的に言うと、リストへの挿入がされない不適当な要素を処理しようとすると、例外がスローされる場合もあれば、処理が有効になる場合もあります。このインタフェースに関するそうした例外は、「任意」の仕様としてマークされます。

このインタフェースは、Java Collections Framework のメンバーです。

導入されたバージョン:

1.2

関連項目:

Collection, Set, ArrayList, LinkedList, Vector, Arrays.asList(Object[]), Collections.nCopies(int, Object), Collections.EMPTY_LIST, AbstractList, AbstractSequentialList

メソッドの概要

boolean	add(E e) 指定された要素をリストの最後に追加します (任意のオペレーション)。
void	add(int index, E element) リスト内の指定された位置に、指定された要素を挿入します (任意のオペレーション)。
boolean	addAll(Collection<? extends E> c) 指定されたコレクション内のすべての要素を、指定されたコレクションの反復子によって返される順序でリストの最後に追加します (任意のオペレーション)。
boolean	addAll(int index, Collection<? extends E> c) 指定されたコレクション内のすべての要素を、リストの指定された位置に挿入します (任意のオペレーション)。
void	clear() すべての要素をリストから削除します (任意のオペレーション)。
boolean	contains(Object o) リストに指定の要素がある場合に true を返します。
boolean	containsAll(Collection<?> c) 指定されたコレクションのすべての要素がリストに含まれている場合に true を返します。
boolean	equals(Object o) 指定されたオブジェクトがリストと等しいかどうかを比較します。
E	get(int index) リスト内の指定された位置にある要素を返します。
int	hashCode() このリストのハッシュコード値を返します。
int	indexOf(Object o) 指定された要素がリスト内で最初に検出された位置のインデックスを返します。
boolean	isEmpty() リストに要素がない場合に true を返します。
Iterator<E>	iterator() このリスト内の要素を適切な順序で繰り返し処理する反復子を返します。
int	lastIndexOf(Object o) 指定された要素がリスト内で最後に検出された位置のインデックスを返します。
ListIterator<E>	listIterator() このリスト内の要素を適切な順序で繰り返し処理するリスト反復子を返します。
ListIterator<E>	listIterator(int index) リスト内の要素を適切な順序で繰り返し処理する、リスト内の指定された位置から開始する反復子を返します。
E	remove(int index) リスト内の指定された位置にある要素を削除します (任意のオペレーション)。
boolean	remove(Object o) 指定された要素がこのリストにあれば、その最初のものをリストから削除します (任意のオペレーション)。
boolean	removeAll(Collection<?> c) このリストから、指定されたコレクションに含まれる要素をすべて削除します (任意のオペレーション)。
boolean	retainAll(Collection<?> c) 指定されたコレクションに格納されている要素だけがリスト内に含まれるようにします (任意のオペレーション)。
E	set(int index, E element) リスト内の指定された位置にある要素を、指定された要素に置き換えます (任意のオペレーション)。
int	size() リスト内にある要素の数を返します。
List<E>	subList(int fromIndex, int toIndex) このリストの、fromIndex (これを含む) から toIndex (これを含まない) の範囲の部分のビューを返します。
Object[]	toArray() リスト内のすべての要素を適切な順序で (最初の要素から最後の要素へ) 格納している配列を返します。
<T> T[]	toArray(T[] a) リスト内のすべての要素を適切な順序で (最初の要素から最後の要素へ) 格納している配列を返します。

メソッドの詳細

size

int size()

リスト内にある要素の数を返します。このリストに Integer.MAX_VALUE より多くの要素がある場合は、Integer.MAX_VALUE を返します。

定義:

インタフェース Collection<E> 内の size

戻り値:

リスト内の要素数

isEmpty

boolean isEmpty()

リストに要素がない場合に true を返します。

定義:

インタフェース Collection<E> 内の isEmpty

戻り値:

リストが要素を 1 つも保持していない場合は true

contains

boolean contains(Object o)

リストに指定の要素がある場合に true を返します。つまり、リストに、(o==null ? e==null : o.equals(e)) となる要素 e が 1 つ以上含まれている場合にだけ true を返します。

定義:

インタフェース Collection<E> 内の contains

パラメータ:

o - リストにあるかどうかを調べる要素

戻り値:

リストが、指定された要素を保持している場合は true

例外:

ClassCastException - 指定された要素の型が、このリストと互換でない場合 (省略可能)

NullPointerException - 指定された要素が null であり、このリストが null 要素を許可しない場合 (省略可能)

iterator

Iterator<E> iterator()

このリスト内の要素を適切な順序で繰り返し処理する反復子を返します。

定義:

インタフェース Collection<E> 内の iterator

定義:

インタフェース Iterable<E> 内の iterator

戻り値:

リスト内の要素を適切な順序で繰り返し処理する反復子

toArray

Object[] toArray()

リスト内のすべての要素を適切な順序で (最初の要素から最後の要素へ) 格納している配列を返します。

返される配列への参照をこのリストが維持しないという点で、この配列は安全です。つまり、このメソッドは、リストが配列に連動している場合でも新しい配列を割り当てます。このため、呼び出し側は、返された配列を自由に変更できます。

メソッドは、配列ベースの API とコレクションベースの API の間の橋渡し役として機能します。

定義:

インタフェース Collection<E> 内の toArray

戻り値:

リスト内のすべての要素を適切な順序で格納している配列

関連項目:

Arrays.asList(Object[])

toArray

<T> T[] toArray(T[] a)

リスト内のすべての要素を適切な順序で (最初の要素から最後の要素へ) 格納している配列を返します。返される配列の実行時の型は、指定された配列の型になります。指定された配列にリストが収まる場合は、その配列に返されます。それ以外の場合は、指定された配列の実行時の型とリストのサイズを使って新しい配列が割り当てられます。

指定された配列にリストが収まり、その配列にさらに余分な領域がある場合、つまり配列にリストより多くの要素がある場合、配列でリストの末尾に続く要素は null に設定されます。(これは、呼び出し側がリストに null 要素が含まれていないことがわかっている場合には、リストの長さを判定するのに利用できる。)

toArray() メソッドと同じように、このメソッドは、配列ベースの API とコレクションベースの API の間の橋渡し役として機能します。さらに、このメソッドでは、出力配列の実行時の型を正確に制御できるため、環境によっては割り当ての手間を抑えることができます。

x が、文字列だけからなるリストであることがわかっていると仮定します。次のコードを使うと、新しく割り当てられた String の配列にリストをダンプできます。

     String[] y = x.toArray(new String[0]);

toArray(new Object[0]) は、機能の点で toArray() と同一です。

定義:

インタフェース Collection<E> 内の toArray

パラメータ:

a - リストの要素の格納先の配列。配列のサイズが十分でない場合は、同じ実行時の型で新しい配列が格納用として割り当てられる

戻り値:

リストの要素が格納されている配列

例外:

ArrayStoreException - 指定された配列の実行時の型が、このリスト内のすべての要素の実行時の型のスーパータイプでない場合

NullPointerException - 指定された配列が null である場合

add

boolean add(E e)

指定された要素をリストの最後に追加します (任意のオペレーション)。

このオペレーションをサポートするリストは、リストに追加できる要素に制限を加える場合があります。特に、リストには null 要素の追加を拒否するものもあれば、追加される要素の型について制限を加えるものもあります。List クラスは、List に追加できる要素について制約があれば、ドキュメントでそれを明確に指定する必要があります。

定義:

インタフェース Collection<E> 内の add

パラメータ:

e - リストに追加される要素

戻り値:

true (Collection.add(E) で指定されているとおり)

例外:

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)

指定されたコレクションのすべての要素がリストに含まれている場合に true を返します。

定義:

インタフェース Collection<E> 内の containsAll

パラメータ:

c - このリストにあるかどうかを調べるコレクション

戻り値:

指定されたコレクションのすべての要素がリストに含まれている場合は true

例外:

ClassCastException - 指定されたコレクションの 1 つ以上の要素の型が、このリストと互換でない場合 (省略可能)

NullPointerException - 指定されたコレクションに 1 つ以上の null 要素が含まれており、このリストが null 要素を許可しない場合 (省略可能)、または指定されたコレクションが null の場合

関連項目:

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

指定されたコレクション内のすべての要素を、指定されたコレクションの反復子によって返される順序でリストの最後に追加します (任意のオペレーション)。オペレーションの進行中に、指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。つまり、指定されたコレクションがこのリストで、しかも空ではない場合に起こります。

定義:

インタフェース Collection<E> 内の addAll

パラメータ:

c - 要素がリストに追加されるコレクション

戻り値:

この呼び出しの結果、このリストが変更された場合は true

例外:

UnsupportedOperationException - addAll オペレーションがこのリストでサポートされない場合

ClassCastException - 指定されたコレクションのある要素のクラスが原因で、このリストにそのコレクションを追加できない場合

NullPointerException - 指定されたコレクションに 1 つ以上の null 要素が含まれており、このリストが null 要素を許可しない場合、または指定されたコレクションが null の場合

IllegalArgumentException - 指定されたコレクションのある要素のある特性が原因で、このリストにそのコレクションを追加できない場合

関連項目:

add(Object)

addAll

boolean addAll(int index,
               Collection<? extends E> c)

指定されたコレクション内のすべての要素を、リストの指定された位置に挿入します (任意のオペレーション)。その位置とそれ以降に要素がある場合は、それらを右に移動して、各要素のインデックスに 1 を加えます。新しい要素は、指定されたコレクションの反復子によって返される順序でリストに挿入されます。オペレーションの進行中に、指定されたコレクションが変更された場合の、このオペレーションの動作は定義されていません。つまり、指定されたコレクションがこのリストで、しかも空ではない場合に起こります。

パラメータ:

index - 指定されたコレクションの最初の要素を挿入する位置のインデックス

c - 要素がリストに追加されるコレクション

戻り値:

この呼び出しの結果、このリストが変更された場合は true

例外:

UnsupportedOperationException - addAll オペレーションがこのリストでサポートされない場合

ClassCastException - 指定されたコレクションのある要素のクラスが原因で、このリストにそのコレクションを追加できない場合

NullPointerException - 指定されたコレクションに 1 つ以上の null 要素が含まれており、このリストが null 要素を許可しない場合、または指定されたコレクションが null の場合

IllegalArgumentException - 指定されたコレクションのある要素のある特性が原因で、このリストにそのコレクションを追加できない場合

IndexOutOfBoundsException - インデックスが範囲外の場合 (index < 0 || index > size())

removeAll

boolean removeAll(Collection<?> c)

このリストから、指定されたコレクションに含まれる要素をすべて削除します (任意のオペレーション)。

定義:

インタフェース Collection<E> 内の removeAll

パラメータ:

c - このリストから削除される要素を含むコレクション

戻り値:

この呼び出しの結果、このリストが変更された場合は true

例外:

UnsupportedOperationException - removeAll オペレーションがこのリストでサポートされない場合

ClassCastException - このリストのある要素のクラスが、指定されたコレクションと互換でない場合 (省略可能)

NullPointerException - このリスト内に null 要素が含まれ、指定されたコレクションが null 要素を許可しない場合 (省略可能)。または指定されたコレクションが null の場合

関連項目:

remove(Object), contains(Object)

retainAll

boolean retainAll(Collection<?> c)

指定されたコレクションに格納されている要素だけがリスト内に含まれるようにします (任意のオペレーション)。つまり、指定されたコレクションに含まれていない要素をリストからすべて削除します。

定義:

インタフェース Collection<E> 内の retainAll

パラメータ:

c - このリストで保持される要素を含むコレクション

戻り値:

この呼び出しの結果、このリストが変更された場合は true

例外:

UnsupportedOperationException - retainAll オペレーションがこのリストでサポートされない場合

ClassCastException - このリストのある要素のクラスが、指定されたコレクションと互換でない場合 (省略可能)

NullPointerException - このリスト内に null 要素が含まれ、指定されたコレクションが null 要素を許可しない場合 (省略可能)。または指定されたコレクションが null の場合

関連項目:

remove(Object), contains(Object)

clear

void clear()

すべての要素をリストから削除します (任意のオペレーション)。この呼び出しが戻ると、このリストは空になります。

定義:

インタフェース Collection<E> 内の clear

例外:

UnsupportedOperationException - clear オペレーションがこのリストでサポートされない場合

equals

boolean equals(Object o)

指定されたオブジェクトがリストと等しいかどうかを比較します。指定されたオブジェクトもリストであり、サイズが同じで、2 つのリストの対応する要素がすべて「等しい」場合にだけ true を返します。2 つの要素 e1 と e2 は、(e1==null ? e2==null :e1.equals(e2)) である場合に等しくなります。つまり 2 つのリストは、同じ要素が同じ順序で含まれている場合に等しいものとして定義されます。この定義により、List インタフェースの実装が異なっても、equals メソッドが正しく動作することが保証されます。

定義:

インタフェース Collection<E> 内の equals

オーバーライド:

クラス Object 内の equals

パラメータ:

o - リストと等しいかどうかを比較するオブジェクト

戻り値:

指定されたオブジェクトがリストと等しい場合は true

関連項目:

Object.hashCode(), Hashtable

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());
  }
 

これにより、Object.hashCode() の一般規約によって要求されるように、任意の 2 つのリスト list1 と list2 で、list1.equals(list2) であれば、list1.hashCode()==list2.hashCode() となることが保証されます。

定義:

インタフェース Collection<E> 内の hashCode

オーバーライド:

クラス Object 内の hashCode

戻り値:

リストのハッシュコード値

関連項目:

Object.equals(Object), equals(Object)

get

E get(int index)

リスト内の指定された位置にある要素を返します。

パラメータ:

index - 返される要素のインデックス

戻り値:

リスト内の指定された位置にある要素

例外:

IndexOutOfBoundsException - インデックスが範囲外の場合 (index < 0 || index >= size())

set

E set(int index,
      E element)

リスト内の指定された位置にある要素を、指定された要素に置き換えます (任意のオペレーション)。

パラメータ:

index - 置換される要素のインデックス

element - 指定された位置に格納される要素

戻り値:

指定された位置に以前あった要素

例外:

UnsupportedOperationException - set オペレーションがこのリストでサポートされない場合

ClassCastException - 指定された要素のクラスが原因で、このリストにその要素を追加できない場合

NullPointerException - 指定された要素が null で、このリストが null 要素を許容しない場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、このリストにその要素を追加できない場合

IndexOutOfBoundsException - インデックスが範囲外の場合 (index < 0 || index >= size())

add

void add(int index,
         E element)

リスト内の指定された位置に、指定された要素を挿入します (任意のオペレーション)。その位置とそれ以降に要素があればそれらを右に移動させ、各要素のインデックスに 1 を加えます。

パラメータ:

index - 指定の要素が挿入される位置のインデックス

element - 挿入される要素

例外:

UnsupportedOperationException - add オペレーションがこのリストでサポートされない場合

ClassCastException - 指定された要素のクラスが原因で、このリストにその要素を追加できない場合

NullPointerException - 指定された要素が null で、このリストが null 要素を許容しない場合

IllegalArgumentException - 指定された要素のあるプロパティーが原因で、このリストにその要素を追加できない場合

IndexOutOfBoundsException - インデックスが範囲外の場合 (index < 0 || index > size())

remove

E remove(int index)

リスト内の指定された位置にある要素を削除します (任意のオペレーション)。後続の要素は左に移動します (インデックス値から 1 を減算)。リストから削除された要素が返されます。

パラメータ:

index - 削除される要素のインデックス

戻り値:

指定された位置に以前あった要素

例外:

UnsupportedOperationException - remove オペレーションがこのリストでサポートされない場合

IndexOutOfBoundsException - インデックスが範囲外の場合 (index < 0 || index >= size())

indexOf

int indexOf(Object o)

指定された要素がリスト内で最初に検出された位置のインデックスを返します。 指定された要素がリストにない場合は -1 を返します。つまり、(o==null ? get(i)==null : o.equals(get(i))) となる、最小のインデックス i を返します。そのようなインデックスが存在しない場合は -1 を返します。

パラメータ:

o - 検索する要素

戻り値:

指定された要素がリスト内で最初に検出された位置のインデックス。その要素がリストにない場合は -1

例外:

ClassCastException - 指定された要素の型が、このリストと互換でない場合 (省略可能)

NullPointerException - 指定された要素が null であり、このリストが null 要素を許可しない場合 (省略可能)

lastIndexOf

int lastIndexOf(Object o)

指定された要素がリスト内で最後に検出された位置のインデックスを返します。 指定された要素がリストにない場合は -1 を返します。つまり、(o==null ? get(i)==null : o.equals(get(i))) となる、最大のインデックス i を返します。そのようなインデックスが存在しない場合は -1 を返します。

パラメータ:

o - 検索する要素

戻り値:

指定された要素がリスト内で最後に検出された位置のインデックス。その要素がリストにない場合は -1

例外:

ClassCastException - 指定された要素の型が、このリストと互換でない場合 (省略可能)

NullPointerException - 指定された要素が null であり、このリストが null 要素を許可しない場合 (省略可能)

listIterator

ListIterator<E> listIterator()

このリスト内の要素を適切な順序で繰り返し処理するリスト反復子を返します。

戻り値:

リスト内の要素を適切な順序で繰り返し処理するリスト反復子

listIterator

ListIterator<E> listIterator(int index)

リスト内の要素を適切な順序で繰り返し処理する、リスト内の指定された位置から開始する反復子を返します。指定されたインデックスは、next の最初の呼び出しによって返される最初の要素を示します。previous の最初の呼び出しは、指定されたインデックスから 1 を引いた値のインデックスを持つ要素を返します。

パラメータ:

index - リスト反復子から (next メソッド呼び出しによって) 返される最初の要素のインデックス

戻り値:

リスト内の要素を適切な順序で繰り返し処理する、リスト内の指定された位置から開始するリスト反復子

例外:

IndexOutOfBoundsException - インデックスが範囲外の場合 (index < 0 || index > size())

subList

List<E> subList(int fromIndex,
                int toIndex)

このリストの、fromIndex (これを含む) から toIndex (これを含まない) の範囲の部分のビューを返します。fromIndex と toIndex が等しい場合は、空のリストが返されます。 返されるリストはこのリストに連動しています。そのため、返されるリスト内での非構造的な変更はこのリストに反映され、このリスト内での変更は返されるリストに反映されます。返されるリストは、このリストによってサポートされている、リストに関連するオプションのオペレーションをすべてサポートします。

このメソッドは、配列に一般的に見られるような、明示的な範囲操作のための要求を不要にします。リストを要求するいかなる操作もリスト全体ではなく、subList ビュー上で操作することで、範囲操作として使用できます。たとえば、次の慣用法は、指定された範囲の要素をリストから削除します。

      list.subList(from, to).clear();
 

indexOf および lastIndexOf でも、同様の慣用法を作成できます。Collections クラスのアルゴリズムがすべて subList に適用できます。

バッキングリスト (すなわち、このリスト) の構造が、返されたリストを経由せずに変更された場合、このメソッドで返されたリストのセマンティクスは保証されません。構造の変更とは、リストのサイズが変わるような変更や、進行中の繰り返し処理が不正な結果に終わるような変更のことです。

パラメータ:

fromIndex - subList の下端点 (これを含む)

toIndex - subList の上端点 (これを含まない)

戻り値:

このリスト内の指定された範囲のビュー

例外:

IndexOutOfBoundsException - 端点のインデックス値が不正である場合 (fromIndex < 0 || toIndex > size || fromIndex > toIndex)