java.util
インタフェース List

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

AbstractList, LinkedList, Vector, ArrayList

public abstract interface List

extends Collection

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

セットとは異なり、通常、リストは重複する要素を許可します。つまり、リストは、通常 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 メソッドの動作は保証されません。

導入されたバージョン:

JDK1.2

関連項目:

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

メソッドの概要

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

メソッドの詳細

size

public int size()

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

定義:

インタフェース Collection 内の size

戻り値:

リスト内の要素数

isEmpty

public boolean isEmpty()

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

定義:

インタフェース Collection 内の isEmpty

戻り値:

リストに要素がない場合は true

contains

public boolean contains(Object o)

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

定義:

インタフェース Collection 内の contains

パラメータ:

o - リストにあるかどうかを判定する要素

戻り値:

リストに指定された要素が含まれている場合は true

iterator

public Iterator iterator()

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

定義:

インタフェース Collection 内の iterator

戻り値:

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

toArray

public Object[] toArray()

リスト内のすべて要素を適切なシーケンスで格納している配列を返します。Collection.toArray メソッドの一般規約に従います。

定義:

インタフェース Collection 内の toArray

戻り値:

リスト内のすべて要素を適切なシーケンスで格納している配列

関連項目:

Arrays.asList(Object[])

toArray

public Object[] toArray(Object[] a)

リスト内のすべて要素を適切なシーケンスで格納している配列を返します。返される配列の実行時の型は、指定された配列の型になります。Collection.toArray(Object[]) メソッドの一般規約に従います。

定義:

インタフェース Collection 内の toArray

パラメータ:

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

戻り値:

リストの要素を格納している配列

例外:

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

add

public boolean add(Object o)

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

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

定義:

インタフェース Collection 内の add

パラメータ:

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

戻り値:

true (Collection.add メソッドの一般規約に従う)

例外:

UnsupportedOperationException - add メソッドがリストによってサポートされていない場合

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

IllegalArgumentException - この要素の特性が原因で、コレクションに要素を追加できない場合

remove

public boolean remove(Object o)

リスト内で指定された要素が最初に検出されたとき、その要素を削除します (任意のオペレーション)。リストにその要素がない場合は、変更されません。つまり、(o==null ? get(i)==null : o.equals(get(i))) となる、最小のインデックス値 i を持つ要素を削除します (そのような要素が存在する場合)。

定義:

インタフェース Collection 内の remove

パラメータ:

o - リストから削除する要素 (存在する場合)

戻り値:

リストに指定された要素が含まれている場合は true

例外:

UnsupportedOperationException - リストが remove メソッドをサポートしていない場合

containsAll

public boolean containsAll(Collection c)

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

定義:

インタフェース Collection 内の containsAll

パラメータ:

c - リストにあるかどうかを判定するコレクション

戻り値:

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

関連項目:

contains(Object)

addAll

public boolean addAll(Collection c)

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

定義:

インタフェース Collection 内の addAll

パラメータ:

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

戻り値:

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

例外:

UnsupportedOperationException - addAll メソッドがリストによってサポートされていない場合

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

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

関連項目:

add(Object)

addAll

public boolean addAll(int index,
                      Collection c)

指定されたコレクション内のすべての要素を、リストの指定された位置に挿入します (任意のオペレーション)。現在その位置にある要素と後続の要素は右に移動されます (インデックス値が増加)。新しい要素は、指定されたコレクションの反復子によって返される順序でリストに挿入されます。指定されたコレクションがオペレーションの進行中に変更された場合、このオペレーションの動作は保証されません。つまり、指定されたコレクションがリストであり、リストが空でない場合、この呼出しの動作は保証されません。

パラメータ:

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

c - リストに挿入する要素

戻り値:

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

例外:

UnsupportedOperationException - addAll メソッドがリストによってサポートされていない場合

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

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

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

removeAll

public boolean removeAll(Collection c)

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

定義:

インタフェース Collection 内の removeAll

パラメータ:

c - どの要素がリストから削除されるかを定義するコレクション

戻り値:

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

例外:

UnsupportedOperationException - removeAll メソッドがリストによってサポートされていない場合

関連項目:

remove(Object), contains(Object)

retainAll

public boolean retainAll(Collection c)

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

定義:

インタフェース Collection 内の retainAll

パラメータ:

c - セットに残る要素を定義するコレクション

戻り値:

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

例外:

UnsupportedOperationException - retainAll メソッドがリストによってサポートされていない場合

関連項目:

remove(Object), contains(Object)

clear

public void clear()

すべての要素をリストから削除します (任意のオペレーション)。この呼び出しからの復帰後、リストは空になります (例外をスローした場合を除く)。

定義:

インタフェース Collection 内の clear

例外:

UnsupportedOperationException - clear メソッドがリストによってサポートされていない場合

equals

public boolean equals(Object o)

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

定義:

インタフェース Collection 内の equals

パラメータ:

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

戻り値:

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

オーバーライド:

クラス Object 内の equals

hashCode

public int hashCode()

リストのハッシュコード値を返します。リストのハッシュコードは、次の計算の結果として定義されます。

  hashCode = 1;
  Iterator i = list.iterator();
  while (i.hasNext()) {
      Object obj = i.next();
      hashCode = 31*hashCode + (obj==null ? 0 : obj.hashCode());
  }
 

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

定義:

インタフェース Collection 内の hashCode

戻り値:

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

オーバーライド:

クラス Object 内の hashCode

関連項目:

Object.hashCode(), Object.equals(Object), equals(Object)

get

public Object get(int index)

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

パラメータ:

index - 返す要素のインデックス

戻り値:

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

例外:

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

set

public Object set(int index,
                  Object element)

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

パラメータ:

index - 置き換える要素のインデックス

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

戻り値:

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

例外:

UnsupportedOperationException - リストが set メソッドをサポートしていない場合

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

IllegalArgumentException - 指定された要素の特性が原因で、リストに要素を追加できない場合

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

add

public void add(int index,
                Object element)

リスト内の指定された位置に、指定された要素を挿入します (任意のオペレーション)。現在その位置にある要素と後続の要素は右に移動されます (インデックス値に 1 を加算)。

パラメータ:

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

element - 挿入される要素

例外:

UnsupportedOperationException - リストが add メソッドをサポートしていない場合

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

IllegalArgumentException - 指定された要素の特性が原因で、リストに要素を追加できない場合

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

remove

public Object remove(int index)

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

パラメータ:

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

戻り値:

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

例外:

UnsupportedOperationException - リストが remove メソッドをサポートしていない場合

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

indexOf

public int indexOf(Object o)

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

パラメータ:

o - 検索する要素

戻り値:

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

lastIndexOf

public int lastIndexOf(Object o)

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

パラメータ:

o - 検索する要素

戻り値:

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

listIterator

public ListIterator listIterator()

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

戻り値:

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

listIterator

public ListIterator listIterator(int index)

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

パラメータ:

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

戻り値:

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

例外:

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

subList

public List 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)