インタフェースList<E>

型パラメータ:

E - このリストの要� のタイプ

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

Collection<E>, Iterable<E>, SequencedCollection<E>

既知のすべての実装クラス:

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

public interface List<E> extends SequencedCollection<E>

� �序付けられたコレクション。リスト内の各要� が挿入される� �所をユーザーが正確に制御できます。 ユーザーは整数値のインデックス(リスト内の位置)によって要� にアクセスしたり、リスト内の要� を検索したりできます。

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

Listインタフェースは、Collectionインタフェースで指定されたものよりも、iterator, add, remove, equalsおよびhashCodeメソッドの契約に、追� の規定を配置します。 便宜上、ほかの継承メソッドの宣言もここに含まれます。

Listインタフェースには、リスト要� への位置指定(インデックス付き)アクセスのための4つのメソッドが用意されています。 Java配列と同様に、Listのインデックスは0から始まります。 これらの操作は、一部の実装(たとえば、LinkedListクラス)の索引値に比例して実行される� �合があります。 このため、呼出し側がこうした実装について知らない� �合は、リストにインデックスを付けるよりも、リスト内の要� を反復してく� さい。

Listインタフェースには、Iteratorインタフェースが提供する通常の操作に� えて、要� の挿入と置換、および双方向アクセスを許可する、ListIteratorという特別なイテレータが用意されています。 リスト内の指定した位置から開始するリスト・イテレータを取得するためのメソッドが提供されています。

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

Listインタフェースには、リスト内の任意のポイントで複数の要� を効率的に挿入および削除するための2つのメソッドがあります。

ノート: リスト自体を要� として含めることは可能ですが、細心の注意を払ってく� さい: equalsおよびhashCodeメソッドは、このようなリストに適切に定義されなくなりました。

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

変更不可能なLists

List.ofおよびList.copyOf静的ファクトリ・メソッドは、変更不可能なリストを作成する便利な方法を提供します。 これらのメソッドによって作成されたListインスタンスには、次の特性があります:

• それらはunmodifiableです。 要� を追� 、削除または置換することはできません。 Listで任意のmutatorメソッドを呼び出すと、常にUnsupportedOperationExceptionがスローされます。 た� し、含まれている要� 自体が可変である� �合は、リストの内容が変更される可能性があります。
• null要� は許可されません。 null要� でそれらを作成しようとすると、NullPointerExceptionになります。
• すべての要� が直列化可能である� �合は、直列化可能です。
• リスト内の要� の� �序は、指定された引数の� �序、または指定された配列内の要� の� �序と同じです。
• リストとそのsubListビューは、RandomAccessインタフェースを実装します。
• それらはvalue-basedです。 プログラマは、equalのインスタンスを交換可能として処理し、同期に使用しないようにする必要があります。そうしないと、予期しない動作が発生する可能性があります。 たとえば、将来のリリースでは、同期が失敗する可能性があります。 呼び出し元は、返されたインスタンスのアイデンティティについて何も想定しないでく� さい。 ファクトリは、新しいインスタンスを作成したり、既存のインスタンスを再利用できます。
• これらは、「直列化された形式」ページで指定したとおりに直列化されます。

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

導入されたバージョン:

1.2

関連� �目:

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

メソッドのサマリー

修飾子と型	メソッド	説明
void	add(int index, E element)	このリスト内の指定された位置に、指定された要� を挿入します(オプションの操作)。
boolean	add(E e)	指定された要� をこのリストの最後に追� します(オプションの操作)。
boolean	addAll(int index, Collection<? extends E> c)	指定されたコレクション内のすべての要� を、このリストの指定された位置に挿入します(オプションの操作)。
boolean	addAll(Collection<? extends E> c)	指定されたコレクション内のすべての要� を、指定されたコレクションのイテレータによって返される� �序で、このリストの最後に追� します(オプションの操作)。
default void	addFirst(E e)	このコレクションの最初の要� として要� を追� します (オプションの操作)。
default void	addLast(E e)	このコレクションの最後の要� として要� を追� します (オプションの操作)。
void	clear()	すべての要� をこのリストから削除します(オプションの操作)。
boolean	contains(Object o)	指定された要� がこのリストに含まれている� �合にtrueを返します。
boolean	containsAll(Collection<?> c)	指定されたコレクションのすべての要� がこのリストに含まれている� �合にtrueを返します。
static <E> List<E>	copyOf(Collection<? extends E> coll)	指定されたCollectionの要� をその反復� �序で含む「変更不可能なList」を返します。
boolean	equals(Object o)	指定されたオブジェクトがこのリストと等しいかどうかを比較します。
E	get(int index)	このリスト内の指定された位置にある要� を返します。
default E	getFirst()	このコレクションの最初の要� を取得します。
default E	getLast()	このコレクションの最後の要� を取得します。
int	hashCode()	このリストのハッシュ・コード値を返します。
int	indexOf(Object o)	指定された要� がこのリスト内で最初に検出された位置のインデックスを返します。指定された要� がこのリストにない� �合は -1を返します。
boolean	isEmpty()	このリストに要� がない� �合にtrueを返します。
Iterator<E>	iterator()	このリスト内の要� を適切な� �序で反復するイテレータを返します。
int	lastIndexOf(Object o)	指定された要� がこのリスト内で最後に検出された位置のインデックスを返します。指定された要� がこのリストにない� �合は -1を返します。
ListIterator<E>	listIterator()	このリスト内の要� を(適切な� �序で)反復するリスト・イテレータを返します。
ListIterator<E>	listIterator(int index)	リスト内の指定された位置で始まる、リスト内の要� を(適切な� �序で)反復するリスト・イテレータを返します。
static <E> List<E>	of()	ゼロ要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1)	1つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E... elements)	任意の数の要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2)	2つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2, E e3)	3つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2, E e3, E e4)	4つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5)	5つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6)	6つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)	7つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)	8つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)	9つの要� を含む変更不可能なリストを返します。
static <E> List<E>	of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)	10個の要� を含む変更不可能なリストを返します。
E	remove(int index)	このリスト内の指定された位置にある要� を削除します(オプションの操作)。
boolean	remove(Object o)	指定された要� がこのリストにあれば、その最初のものをリストから削除します(オプションの操作)。
boolean	removeAll(Collection<?> c)	このリストから、指定されたコレクションに含まれる要� をすべて削除します(オプションの操作)。
default E	removeFirst()	このコレクションの最初の要� を削除して返します(オプションの操作)。
default E	removeLast()	このコレクションの最後の要� を削除して返します(オプションの操作)。
default void	replaceAll(UnaryOperator<E> operator)	このリストの各要� を、その要� (オプションの操作)に演算子を適用した結果に置き換えます。
boolean	retainAll(Collection<?> c)	このリスト内で、指定されたコレクションに含まれている要� � けを保持します(オプションの操作)。
default List<E>	reversed()	このコレクションの逆� �viewを返します。
E	set(int index, E element)	このリスト内の指定された位置にある要� を、指定された要� に置き換えます(オプションの操作)。
int	size()	このリスト内にある要� の数を返します。
default void	sort(Comparator<? super E> c)	このリストは、指定されたComparator (オプションの操作)によって誘導された� �序に従ってソートされます。
default Spliterator<E>	spliterator()	このリスト内の要� に対するSpliteratorを作成します。
List<E>	subList(int fromIndex, int toIndex)	このリストの、指定されたfromIndex (これを含む)からtoIndex (これを含まない)までの部分のビューを返します。
Object[]	toArray()	このリスト内のすべての要� を適切な� �序で(最初の要� から最後の要� へ)含んでいる配列を返します。
<T> T[]	toArray(T[] a)	このリスト内のすべての要� を適切な� �序で(最初の要� から最後の要� へ)含んでいる配列を返します。返される配列の実行時の型は、指定された配列の型になります。

インタフェースjava.util.Collectionで宣言されたメソッド

parallelStream, removeIf, stream, toArray

インタフェースjava.lang.Iterableで宣言されたメソッド

forEach

メソッドの詳細

size

int size()

このリスト内にある要� の数を返します。 このリストにInteger.MAX_VALUEを超える要� が含まれている� �合は、Integer.MAX_VALUEを返します。

定義:

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

戻り値:

このリスト内の要� 数

isEmpty

boolean isEmpty()

このリストに要� がない� �合にtrueを返します。

定義:

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

戻り値:

このリストに要� が含まれていない� �合はtrue

contains

boolean contains(Object o)

指定された要� がこのリストに含まれている� �合にtrueを返します。 より正式には、このリストにObjects.equals(o, e)などの要� eが少なくとも1つ含まれている� �合のみ、trueを返します。

定義:

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

パラメータ:

o - このリスト内にあるかどうかが判定される要�

戻り値:

指定された要� がこのリスト内にある� �合はtrue

スロー:

ClassCastException - 指定された要� の型が、このリストと互換でない� �合(オプション)

NullPointerException - 指定された要� がnullで、このリストがnull要� を許可しない� �合(オプション)

iterator

Iterator<E> iterator()

このリスト内の要� を適切な� �序で反復するイテレータを返します。

定義:

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

定義:

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

戻り値:

リスト内の要� を適切な� �序で反復するイテレータ

toArray

Object[] toArray()

このリスト内のすべての要� を適切な� �序で(最初の要� から最後の要� へ)含んでいる配列を返します。

返される配列は、それへの参照がこのリストで保持されない� �合に、安全になります。 (つまり、このメソッドは、このリストが配列に連動している� �合でも、新しい配列を割り当てる必要があります。) このため、呼出し側は、返された配列を自由に変更できます。

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

定義:

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

戻り値:

このリスト内のすべての要� を適切な� �序で含んでいる配列

関連� �目:

• 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()と同一です。

定義:

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

型パラメータ:

T - コレクションを� �納する配列のコンポーネント型

パラメータ:

a - 配列が十分な大きさを持つ� �合は、このリストの要� の� �納先の配列。配列のサイズが十分でない� �合は、同じ実行時の型で新しい配列が� �納用として割り当てられる。

戻り値:

このリストの要� が含まれている配列

スロー:

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

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

add

boolean add(E e)

指定された要� をこのリストの最後に追� します(オプションの操作)。

このオペレーションをサポートするリストは、リストに追� できる要� に制限を� える� �合があります。 たとえば、リストにはnull要� の追� を拒否するものもあれば、追� される要� の型について制限を� えるものもあります。 Listクラスは、追� できる要� について制約があれば、ドキュメントでそれを明確に記述するようにしてく� さい。

定義:

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

パラメータ:

e - このリストに追� される要�

戻り値:

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

スロー:

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

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

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

IllegalArgumentException - この要� のあるプロパティが原� で、このリストにその要� を追� できない� �合

remove

boolean remove(Object o)

指定された要� がこのリストにあれば、その最初のものをリストから削除します(オプションの操作)。 このリストにその要� がない� �合は、変更されません。 より正式には、Objects.equals(o, get(i)) (そのような要� が存在する� �合)のように、最も低い索引iを持つ要� を削除します。 指定された要� がこのリストに含まれていた� �合、つまり、呼出しの結果としてこのリストが変更された� �合にtrueを返します。

定義:

remove、インタフェースCollection<E>

パラメータ:

o - このリストから削除される要� (その要� が存在する� �合)

戻り値:

指定された要� がこのリストに含まれていた� �合はtrue

スロー:

ClassCastException - 指定された要� の型が、このリストと互換でない� �合(オプション)

NullPointerException - 指定された要� がnullで、このリストがnull要� を許可しない� �合(オプション)

UnsupportedOperationException - remove操作がこのリストでサポートされていない� �合

containsAll

boolean containsAll(Collection<?> c)

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

定義:

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

パラメータ:

c - このリストにあるかどうかがチェックされるコレクション

戻り値:

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

スロー:

ClassCastException - 指定されたコレクションの1つ以上の要� の型が、このリストと互換でない� �合(オプション)

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

関連� �目:

• contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

指定されたコレクション内のすべての要� を、指定されたコレクションのイテレータによって返される� �序で、このリストの最後に追� します(オプションの操作)。 オペレーションの進行中に、指定されたコレクションが変更された� �合の、このオペレーションの動作は定義されていません。 (これは、指定されたコレクションがこのリストで、しかも空ではない� �合に起こります。)

定義:

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

パラメータ:

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)

このリストから、指定されたコレクションに含まれる要� をすべて削除します(オプションの操作)。

定義:

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

パラメータ:

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

戻り値:

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

スロー:

UnsupportedOperationException - removeAll操作がこのリストでサポートされていない� �合

ClassCastException - このリストのある要� のクラスが、指定されたコレクションと互換でない� �合(オプション)

NullPointerException - このリストにnull要� が含まれており、指定されたコレクションがnull要� を許可しない� �合(オプション)、または指定されたコレクションがnullの� �合

関連� �目:

• remove(Object)
• contains(Object)

retainAll

boolean retainAll(Collection<?> c)

このリスト内で、指定されたコレクションに含まれている要� � けを保持します(オプションの操作)。 つまり、指定されたコレクションに含まれていないすべての要� をこのリストから削除します。

定義:

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

パラメータ:

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

戻り値:

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

スロー:

UnsupportedOperationException - retainAll操作がこのリストでサポートされていない� �合

ClassCastException - このリストのある要� のクラスが、指定されたコレクションと互換でない� �合(オプション)

NullPointerException - このリストにnull要� が含まれており、指定されたコレクションがnull要� を許可しない� �合(オプション)、または指定されたコレクションがnullの� �合

関連� �目:

• remove(Object)
• contains(Object)

replaceAll

default void replaceAll(UnaryOperator<E> operator)

このリストの各要� を、その要� (オプションの操作)に演算子を適用した結果に置き換えます。 演算子によってスローされたエラーまたは実行時例外は、呼出し側に中継されます。

実装要件:

このリストでは、デフォルト実装は次と同等です。

     final ListIterator<E> li = list.listIterator();
     while (li.hasNext()) {
         li.set(operator.apply(li.next()));
     }
 

このリストのリスト・イテレータがset操作をサポートしない� �合、最初の要� を置き換えるときにUnsupportedOperationExceptionがスローされます。

パラメータ:

operator - 各要� に適用する演算子

スロー:

UnsupportedOperationException - このリストでreplaceAll操作がサポートされていない� �合

NullPointerException - 指定された演算子がnull、または演算子の結果がnull値でこのリストがnull要� を許可しない� �合(オプション)

導入されたバージョン:

1.8

sort

default void sort(Comparator<? super E> c)

このリストは、指定されたComparator (オプションの操作)によって誘導された� �序に従ってソートされます。 ソートはstableです: このメソッドは等しい要� を並べ替えてはいけません。

このリストの要� はすべて、指定されたコンパレータを使用して相互に比較可能であることが必要です(つまり、リストの要� e1およびe2に対して、c.compare(e1, e2)からClassCastExceptionがスローされないようにする必要があります)。

指定されたコンパレータがnullの� �合は、リストの全要� でComparableインタフェースを実装し、要� の自然� �序を使用する必要があります。

このリストは変更可能でなければなりませんが、サイズ変更はできなくてもかまいません。

実装要件:

デフォルト実装は、このリストの全要� を含む配列の取得、配列のソート、このリストの反復処理を行うことにより、配列の対応する位置から各要� を再設定します。 (これは、リンクされたリストを適所にソートしようとした� �合のn² log(n)のパフォーマンスになるのを回避します。)

実装上のノート:

この実装は安定した適応型の反復マージ・ソートです。このソートでは、入力配列がランダ� に� �序付けられる� �合は従来のマージ・ソートのパフォーマンスを提供しながら、入力配列が部分的にソートされている� �合は必要となる比較回数がn lg(n)よりもかなり少なくなります。 入力配列がほとんどソートされている� �合、この実装ではおよそn回の比較が必要になります。 一時ストレージの要件は、ほとんどソートされている入力配列用の小さな定数から、ランダ� に� �序付けられた入力配列用のn/2のオブジェクト参照までさまざまです。

この実装では、その入力配列で昇� �と降� �を等しく利用するため、同じ入力配列のさまざまな部分で昇� �と降� �を利用できます。 それは、2つ以上のソートされた配列をマージするのに適切です。つまり、それらの配列を連結し、結果となる配列をソートする� けです。

この実装は、Tim Peters氏によるPython用のリスト・ソート(TimSort)から応用されました。 それは、『Proceedings of the Fourth Annual ACM-SIAM Symposium on Discrete Algorithms』(1993年1月)の467-474ページに記載されている、Peter McIlroy氏の「Optimistic Sorting and Information Theoretic Complexity」からの技術を採用しています。

パラメータ:

c - リスト要� を比較するために使用されるComparator。 null値は、要� の自然� �序付けが使用されることを示す

スロー:

ClassCastException - リストに、指定されたコンパレータで相互比較できない要� が含まれる� �合

UnsupportedOperationException - このリストでsort操作がサポートされていない� �合

IllegalArgumentException - (オプション)コンパレータがComparator規約に違反していることが見つかった� �合

導入されたバージョン:

1.8

clear

void clear()

すべての要� をこのリストから削除します(オプションの操作)。 この呼出しが戻ると、このリストは空になります。

定義:

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

スロー:

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

equals

boolean equals(Object o)

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

定義:

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

オーバーライド:

equals、クラスObject

パラメータ:

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

戻り値:

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

関連� �目:

• Object.equals(Object)
• Set.equals(Object)
• equals(Object)

hashCode

int hashCode()

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

     int hashCode = 1;
     for (E e : list)
         hashCode = 31*hashCode + (e==null ? 0 : e.hashCode());
 

これにより、Object.hashCode()の一般的な契約で必要となる、list1およびlist2の2つのリストに対してlist1.equals(list2)がlist1.hashCode()==list2.hashCode()であることを意味します。

定義:

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

オーバーライド:

hashCode、クラスObject

戻り値:

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

関連� �目:

• 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を返します。 より正式には、Objects.equals(o, get(i))のように最も低い索引iを戻し、そのような索引がない� �合は -1を戻します。

パラメータ:

o - 検索する要�

戻り値:

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

スロー:

ClassCastException - 指定された要� の型が、このリストと互換でない� �合(オプション)

NullPointerException - 指定された要� がnullで、このリストがnull要� を許可しない� �合(オプション)

lastIndexOf

int lastIndexOf(Object o)

指定された要� がこのリスト内で最後に検出された位置のインデックスを返します。指定された要� がこのリストにない� �合は -1を返します。 より正式には、Objects.equals(o, 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にも同様のidiomsを構成でき、Collectionsクラスのすべてのアルゴリズ� をsubListに適用できます。

バッキング・リスト(すなわち、このリスト)の構� が、返されたリストを経由せずに変更された� �合、このメソッドで返されるリストのセマンティックスは定義されていません。 (構� の変更とは、リストのサイズが変わるような変更や、進行中のイテレーションが不正な結果に終わるような変更のことです。)

パラメータ:

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

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

戻り値:

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

スロー:

IndexOutOfBoundsException - 不正なエンドポイント索引値(fromIndex < 0 || toIndex > size || fromIndex > toIndex)

spliterator

default Spliterator<E> spliterator()

このリスト内の要� に対するSpliteratorを作成します。

Spliteratorは、Spliterator.SIZEDおよびSpliterator.ORDEREDを� �告します。 実装は、追� の特性値の� �告をドキュメント化する必要があります。

定義:

spliterator、インタフェースCollection<E>

定義:

spliterator、インタフェースIterable<E>

実装要件:

デフォルト実装では、次のようにlate-bindingスプライテータが作成されます:

• リストがRandomAccessのインスタンスである� �合、デフォルトの実装では、メソッドget(int)を呼び出すことによって要� を走査するスプライテータが作成されます。 そのような呼び出しが結果となるか、またはIndexOutOfBoundsExceptionとなる� �合、スプライテータはfail-fastになり、ConcurrentModificationExceptionをスローします。 リストがAbstractListのインスタンスでもある� �合、スプリッタはリストのmodCountフィールドを使用して、追� のfail-fast動作を提供します。
• それ以外の� �合、デフォルトの実装では、リストのIteratorからスプリッタが作成されます。 スプリッタは、リストのイテレータのfail-fastを継承します。

実装上のノート:

作成されたSpliteratorはさらにSpliterator.SUBSIZEDも� �告します。

戻り値:

このリスト内の要� に対するSpliterator

導入されたバージョン:

1.8

addFirst

default void addFirst(E e)

このコレクションの最初の要� として要� を追� します (オプションの操作)。 この操作が正常に完了すると、指定された要� はこのコレクションのメンバーになり、発生� �に最初の要� になります。

定義:

インタフェースSequencedCollection<E>内のaddFirst

実装要件:

このインタフェースの実装では、add(0, e)がコールされます。

パラメータ:

e - 追� する要�

スロー:

NullPointerException - 指定された要� がnullで、このコレクションがnull要� を許可しない� �合

UnsupportedOperationException - このコレクション実装がこの操作をサポートしていない� �合

導入されたバージョン:

21

addLast

default void addLast(E e)

このコレクションの最後の要� として要� を追� します (オプションの操作)。 この操作が正常に完了すると、指定された要� はこのコレクションのメンバーになり、最後の要� が出現� �になります。

定義:

インタフェースSequencedCollection<E>内のaddLast

実装要件:

このインタフェースの実装では、add(e)がコールされます。

パラメータ:

e - 追� する要� 。

スロー:

NullPointerException - 指定された要� がnullで、このコレクションがnull要� を許可しない� �合

UnsupportedOperationException - このコレクション実装がこの操作をサポートしていない� �合

導入されたバージョン:

21

getFirst

default E getFirst()

このコレクションの最初の要� を取得します。

定義:

インタフェースSequencedCollection<E>内のgetFirst

実装要件:

このリストが空でない� �合、このインタフェースの実装はget(0)をコールした結果を返します。 それ以外の� �合は、NoSuchElementExceptionがスローされます。

戻り値:

取得された要�

スロー:

NoSuchElementException - このコレクションが空の� �合

導入されたバージョン:

21

getLast

default E getLast()

このコレクションの最後の要� を取得します。

定義:

インタフェースSequencedCollection<E>内のgetLast

実装要件:

このリストが空でない� �合、このインタフェースの実装はget(size() - 1)をコールした結果を返します。 それ以外の� �合は、NoSuchElementExceptionがスローされます。

戻り値:

取得された要�

スロー:

NoSuchElementException - このコレクションが空の� �合

導入されたバージョン:

21

removeFirst

default E removeFirst()

このコレクションの最初の要� を削除して返します(オプションの操作)。

定義:

インタフェースSequencedCollection<E>内のremoveFirst

実装要件:

このリストが空でない� �合、このインタフェースの実装はremove(0)をコールした結果を返します。 それ以外の� �合は、NoSuchElementExceptionがスローされます。

戻り値:

削除される要�

スロー:

NoSuchElementException - このコレクションが空の� �合

UnsupportedOperationException - このコレクション実装がこの操作をサポートしていない� �合

導入されたバージョン:

21

removeLast

default E removeLast()

このコレクションの最後の要� を削除して返します(オプションの操作)。

定義:

インタフェースSequencedCollection<E>内のremoveLast

実装要件:

このリストが空でない� �合、このインタフェースの実装はremove(size() - 1)をコールした結果を返します。 それ以外の� �合は、NoSuchElementExceptionがスローされます。

戻り値:

削除される要�

スロー:

NoSuchElementException - このコレクションが空の� �合

UnsupportedOperationException - このコレクション実装がこの操作をサポートしていない� �合

導入されたバージョン:

21

reversed

default List<E> reversed()

このコレクションの逆� �viewを返します。 返されるビュー内の要� の出現� �序は、このコレクション内の要� の出現� �序の逆です。 逆の� �序付けは、返されるビューのビュー・コレクションに含まれるすべての� �序依存操作に影響します。 コレクション実装でこのビューの変更が許可されている� �合、ベースとなるコレクションへの変更"ライトスルー"。 実装によっては、基礎となるコレクションに対する変更が、この逆方向ビューに表示される� �合と表示されない� �合があります。

定義:

インタフェースSequencedCollection<E>内のreversed

実装要件:

このインタフェースの実装では、逆� �のリスト・ビューが返されます。 ビューのreversed()メソッドは、このリストへの参照を返します。 ビューに対するその他の操作は、このリストのpublicメソッドへのコールを介して実装されます。 ビューのコールとこのリストのコールとの正確な関係は未指定です。 た� し、� �序依存操作は、通常、反対の方向で適切なメソッドに委任するかのように動作します。 たとえば、ビューでgetFirstをコールすると、このリストでgetLastがコールされる� �合があります。

戻り値:

このコレクションの逆� �ビュー(Listとして)

導入されたバージョン:

21

of

static <E> List<E> of()

ゼロ要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

戻り値:

空のList

導入されたバージョン:

9

of

static <E> List<E> of(E e1)

1つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 単一要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2)

2つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2, E e3)

3つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

e3 - 第3要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2, E e3, E e4)

4つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

e3 - 第3要�

e4 - 第4要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2, E e3, E e4, E e5)

5つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

e3 - 第3要�

e4 - 第4要�

e5 - 第5要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6)

6つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

e3 - 第3要�

e4 - 第4要�

e5 - 第5要�

e6 - 第6要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)

7つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

e3 - 第3要�

e4 - 第4要�

e5 - 第5要�

e6 - 第6要�

e7 - 第7要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)

8つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

e3 - 第3要�

e4 - 第4要�

e5 - 第5要�

e6 - 第6要�

e7 - 第7要�

e8 - 第8要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)

9つの要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

e3 - 第3要�

e4 - 第4要�

e5 - 第5要�

e6 - 第6要�

e7 - 第7要�

e8 - 第8要�

e9 - 第9要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

static <E> List<E> of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9, E e10)

10個の要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

型パラメータ:

E - Listの要� 型

パラメータ:

e1 - 最初の要�

e2 - 第2要�

e3 - 第3要�

e4 - 第4要�

e5 - 第5要�

e6 - 第6要�

e7 - 第7要�

e8 - 第8要�

e9 - 第9要�

e10 - 10番目の要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合

導入されたバージョン:

9

of

@SafeVarargs static <E> List<E> of(E... elements)

任意の数の要� を含む変更不可能なリストを返します。 詳細については、「変更不可能なLists」を参照してく� さい。

APIのノート:

このメソッドは、引数として単一の配列も受け入れます。 結果リストの要� タイプは配列のコンポーネント・タイプとなり、リストのサイズは配列の長さと等しくなります。 配列である単一の要� を含むリストを作成するには、次の手� �を実行します:

     String[] array = ... ;
     List<String[]> list = List.<String[]>of(array);
 

これにより、かわりにList.of(E)メソッドが呼び出されます。

型パラメータ:

E - Listの要� 型

パラメータ:

elements - リストに含まれる要�

戻り値:

指定された要� を含むList

スロー:

NullPointerException - 要� がnullの� �合、または配列がnullの� �合

導入されたバージョン:

9

copyOf

static <E> List<E> copyOf(Collection<? extends E> coll)

指定されたCollectionの要� をその反復� �序で含む「変更不可能なList」を返します。 指定されたCollectionはnullであってはならず、null要� を含んではいけません。 指定されたCollectionがその後に変更された� �合、返されたListはそのような変更を反� しません。

実装上のノート:

指定されたコレクションが「変更不可能なList」の� �合、通常、copyOfをコールしてもコピーは作成されません。

型パラメータ:

E - Listの要� 型

パラメータ:

coll - 要� が描画されるCollectionはnullでなくてはなりません

戻り値:

与えられたCollectionの要� を含むList

スロー:

NullPointerException - collがnullの� �合、またはnullが含まれている� �合

導入されたバージョン:

10