Интерфейс List<E>

int size()

Определено в:

size в интерфейсе Collection<E>

Возвращает:

количество элементов в этом списке

boolean isEmpty()

Определено в:

isEmpty в интерфейсе Collection<E>

Возвращает:

true, если этот список не содержит элементов

boolean contains(Object o)

Определено в:

contains в интерфейсе Collection<E>

Параметры:

o — элемент, наличие которого в этом списке проверяется

Возвращает:

true, если этот список содержит указанный элемент

Вызывает исключение:

ClassCastException — если тип указанного элемента несовместим с этим списком (необязательно)

NullPointerException — если указанный элемент равен null, а этот список не допускает элементы null (необязательно)

Iterator<E> iterator()

Определено в:

iterator в интерфейсе Collection<E>

Определено в:

iterator в интерфейсе Iterable<E>

Возвращает:

итератор по элементам этого списка в надлежащем порядке

Object[] toArray()

Определено в:

toArray в интерфейсе Collection<E>

Возвращает:

массив, содержащий все элементы этого списка в надлежащем порядке

См. также:

• Arrays.asList(Object[])

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

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

Определено в:

toArray в интерфейсе Collection<E>

Параметры типа:

T — тип компонентов массива, в котором будет храниться коллекция

Параметры:

a — массив, в который будут помещены элементы этого списка, если он достаточно велик; в противном случае для этой цели выделяется новый массив того же типа во время выполнения.

Возвращает:

массив, содержащий элементы этого списка

Вызывает исключение:

ArrayStoreException — если тип указанного массива во время выполнения не является супертипом типа во время выполнения каждого элемента этого списка

NullPointerException — если указанный массив равен null

boolean add(E e)

Определено в:

add в интерфейсе Collection<E>

Параметры:

e — элемент, который нужно добавить в конец этого списка

Возвращает:

true (как указано в Collection.add(E))

Вызывает исключение:

UnsupportedOperationException — если эта операция add не поддерживается данным списком

ClassCastException — если класс указанного элемента не позволяет добавить его в этот список

NullPointerException — если указанный элемент равен null, а этот список не допускает элементы null

IllegalArgumentException — если какое-либо свойство этого элемента не позволяет добавить его в этот список

boolean remove(Object o)

Определено в:

remove в интерфейсе Collection<E>

Параметры:

o — элемент, который нужно удалить из этого списка, если он присутствует

Возвращает:

true, если этот список содержал указанный элемент

Вызывает исключение:

ClassCastException — если тип указанного элемента несовместим с этим списком (необязательно)

NullPointerException — если указанный элемент равен null, а этот список не допускает элементы null (необязательно)

UnsupportedOperationException — если операция remove не поддерживается данным списком

boolean containsAll(Collection<?> c)

Определено в:

containsAll в интерфейсе Collection<E>

Параметры:

c — коллекция, наличие элементов которой в этом списке проверяется

Возвращает:

true, если этот список содержит все элементы указанной коллекции

Вызывает исключение:

ClassCastException — если типы одного или нескольких элементов указанной коллекции несовместимы с этим списком (необязательно)

NullPointerException — если указанная коллекция содержит один или несколько элементов null, а этот список не допускает элементы null (необязательно), или если указанная коллекция равна null

См. также:

• contains(Object)

boolean addAll(Collection<? extends E> c)

Определено в:

addAll в интерфейсе Collection<E>

Параметры:

c — коллекция, содержащая элементы, которые нужно добавить в этот список

Возвращает:

true, если этот список изменился в результате вызова

Вызывает исключение:

UnsupportedOperationException — если операция addAll не поддерживается данным списком

ClassCastException — если класс элемента указанной коллекции не позволяет добавить его в этот список

NullPointerException — если указанная коллекция содержит один или несколько элементов null, а этот список не допускает элементы null, или если указанная коллекция равна null

IllegalArgumentException — если какое-либо свойство элемента указанной коллекции не позволяет добавить его в этот список

См. также:

• add(Object)

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

Параметры:

index — индекс, по которому нужно вставить первый элемент указанной коллекции

c — коллекция, содержащая элементы, которые нужно добавить в этот список

Возвращает:

true, если этот список изменился в результате вызова

Вызывает исключение:

UnsupportedOperationException — если операция addAll не поддерживается данным списком

ClassCastException — если класс элемента указанной коллекции не позволяет добавить его в этот список

NullPointerException — если указанная коллекция содержит один или несколько элементов null, а этот список не допускает элементы null, или если указанная коллекция равна null

IllegalArgumentException — если какое-либо свойство элемента указанной коллекции не позволяет добавить его в этот список

IndexOutOfBoundsException — если индекс выходит за пределы допустимого диапазона (index < 0 || index > size())

boolean removeAll(Collection<?> c)

Определено в:

removeAll в интерфейсе Collection<E>

Параметры:

c — коллекция, содержащая элементы, которые нужно удалить из этого списка

Возвращает:

true, если этот список изменился в результате вызова

Вызывает исключение:

UnsupportedOperationException — если операция removeAll не поддерживается данным списком

ClassCastException — если класс элемента этого списка несовместим с указанной коллекцией (необязательно)

NullPointerException — если этот список содержит элемент null, а указанная коллекция не допускает элементы null (необязательно), или если указанная коллекция равна null

См. также:

• remove(Object)
• contains(Object)

boolean retainAll(Collection<?> c)

Определено в:

retainAll в интерфейсе Collection<E>

Параметры:

c — коллекция, содержащая элементы, которые нужно оставить в этом списке

Возвращает:

true, если этот список изменился в результате вызова

Вызывает исключение:

UnsupportedOperationException — если операция retainAll не поддерживается данным списком

ClassCastException — если класс элемента этого списка несовместим с указанной коллекцией (необязательно)

NullPointerException — если этот список содержит элемент null, а указанная коллекция не допускает элементы null (необязательно), или если указанная коллекция равна null

См. также:

• remove(Object)
• contains(Object)

default void replaceAll(UnaryOperator<E> operator)

Требования к реализации:

Реализация по умолчанию эквивалентна следующему коду для этого list:

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

Если list-iterator списка не поддерживает операцию set, при замене первого элемента будет выброшено исключение UnsupportedOperationException.

Параметры:

operator — оператор, применяемый к каждому элементу

Вызывает исключение:

UnsupportedOperationException — если операция replaceAll не поддерживается данным списком

NullPointerException — если указанный оператор равен null или результат оператора равен null, а этот список не допускает элементы null (необязательно)

Начиная с версии:

1.8

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

Требования к реализации:

Реализация по умолчанию получает массив, содержащий все элементы этого списка, сортирует его и проходит по списку, заново устанавливая каждый элемент из соответствующей позиции массива. (Это позволяет избежать производительности n² log(n), которая возникла бы при попытке сортировать связанный список на месте.)

Примечание по реализации:

Эта реализация представляет собой стабильную адаптивную итеративную сортировку слиянием, которой требуется значительно меньше n lg(n) сравнений, если входной массив частично отсортирован; при случайном порядке элементов она обеспечивает производительность обычной сортировки слиянием. Если входной массив почти отсортирован, реализации требуется примерно n сравнений. Требования к временному хранилищу варьируются от небольшой константы для почти отсортированных входных массивов до n/2 ссылок на объекты для входных массивов со случайным порядком элементов.

Реализация одинаково эффективно использует возрастающий и убывающий порядок во входном массиве, а также может использовать возрастающий и убывающий порядок в разных частях одного и того же входного массива. Она хорошо подходит для слияния двух или более отсортированных массивов: достаточно объединить массивы и отсортировать полученный массив.

Реализация адаптирована из алгоритма сортировки списков Тима Питерса для Python ( TimSort). В ней используются методы из работы Питера Макилроя «Оптимистическая сортировка и информационно-теоретическая сложность», представленной на Четвёртом ежегодном симпозиуме ACM-SIAM по дискретным алгоритмам, с. 467–474, январь 1993 г.

Параметры:

c — Comparator, используемый для сравнения элементов списка. Значение null означает, что следует использовать естественный порядок элементов

Вызывает исключение:

ClassCastException — если список содержит элементы, которые нельзя взаимно сравнить с помощью указанного компаратора

UnsupportedOperationException — если операция sort не поддерживается данным списком

IllegalArgumentException — (необязательно), если обнаружено, что компаратор нарушает контракт Comparator

Начиная с версии:

1.8

void clear()

Определено в:

clear в интерфейсе Collection<E>

Вызывает исключение:

UnsupportedOperationException — если операция clear не поддерживается данным списком

boolean equals(Object o)

Определено в:

equals в интерфейсе Collection<E>

Переопределяет:

equals в классе Object

Параметры:

o — объект, который сравнивается на равенство с этим списком

Возвращает:

true, если указанный объект равен этому списку

См. также:

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

int hashCode()

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

Определено в:

hashCode в интерфейсе Collection<E>

Переопределяет:

hashCode в классе Object

Возвращает:

хеш-код этого списка

См. также:

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

E get(int index)

Параметры:

index — индекс возвращаемого элемента

Возвращает:

элемент, расположенный в указанной позиции этого списка

Вызывает исключение:

IndexOutOfBoundsException — если индекс выходит за пределы допустимого диапазона (index < 0 || index >= size())

E set(int index, E element)

Параметры:

index — индекс заменяемого элемента

element — элемент, который нужно сохранить в указанной позиции

Возвращает:

элемент, ранее находившийся в указанной позиции

Вызывает исключение:

UnsupportedOperationException — если операция set не поддерживается данным списком

ClassCastException — если класс указанного элемента не позволяет добавить его в этот список

NullPointerException — если указанный элемент равен null, а этот список не допускает элементы null

IllegalArgumentException — если какое-либо свойство указанного элемента не позволяет добавить его в этот список

IndexOutOfBoundsException — если индекс выходит за пределы допустимого диапазона (index < 0 || index >= size())

void add(int index, E element)

Параметры:

index — индекс, по которому нужно вставить указанный элемент

element — элемент, который нужно вставить

Вызывает исключение:

UnsupportedOperationException — если операция add не поддерживается данным списком

ClassCastException — если класс указанного элемента не позволяет добавить его в этот список

NullPointerException — если указанный элемент равен null, а этот список не допускает элементы null

IllegalArgumentException — если какое-либо свойство указанного элемента не позволяет добавить его в этот список

IndexOutOfBoundsException — если индекс выходит за пределы допустимого диапазона (index < 0 || index > size())

E remove(int index)

Параметры:

index — индекс удаляемого элемента

Возвращает:

элемент, ранее находившийся в указанной позиции

Вызывает исключение:

UnsupportedOperationException — если операция remove не поддерживается данным списком

IndexOutOfBoundsException — если индекс выходит за пределы допустимого диапазона (index < 0 || index >= size())

int indexOf(Object o)

Параметры:

o — элемент для поиска

Возвращает:

индекс первого вхождения указанного элемента в этом списке или -1, если список не содержит этот элемент

Вызывает исключение:

ClassCastException — если тип указанного элемента несовместим с этим списком (необязательно)

NullPointerException — если указанный элемент равен null, а этот список не допускает элементы null (необязательно)

int lastIndexOf(Object o)

Параметры:

o — элемент для поиска

Возвращает:

индекс последнего вхождения указанного элемента в этом списке или -1, если список не содержит этот элемент

Вызывает исключение:

ClassCastException — если тип указанного элемента несовместим с этим списком (необязательно)

NullPointerException — если указанный элемент равен null, а этот список не допускает элементы null (необязательно)

ListIterator<E> listIterator()

Возвращает:

list-iterator по элементам этого списка (в надлежащем порядке)

ListIterator<E> listIterator(int index)

Параметры:

index — индекс первого элемента, возвращаемого list-iterator (при вызове next)

Возвращает:

list-iterator по элементам этого списка (в надлежащем порядке), начиная с указанной позиции в списке

Вызывает исключение:

IndexOutOfBoundsException — если индекс выходит за пределы допустимого диапазона (index < 0 || index > size())

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

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

Параметры:

fromIndex — нижняя граница (включительно) subList

toIndex — верхняя граница (исключительно) subList

Возвращает:

представление указанного диапазона в этом списке

Исключения:

IndexOutOfBoundsException — если значение индекса конечной точки недопустимо (fromIndex < 0 || toIndex > size || fromIndex > toIndex)

default Spliterator<E> spliterator()

Определено в:

spliterator в интерфейсе Collection<E>

Определено в:

spliterator в интерфейсе Iterable<E>

Требования к реализации:

Реализация по умолчанию создаёт поздно связываемый сплитератор следующим образом:

• Если список является экземпляром RandomAccess, реализация по умолчанию создаёт сплитератор, который перебирает элементы, вызывая метод get(int). Если такой вызов приводит или может привести к IndexOutOfBoundsException, сплитератор завершится с ошибкой (fail-fast) и выбросит ConcurrentModificationException. Если список также является экземпляром AbstractList, сплитератор использует поле списка modCount для дополнительной обработки ошибок по принципу fail-fast.
• В противном случае реализация по умолчанию создаёт сплитератор на основе Iterator списка. Сплитератор наследует от итератора списка поведение fail-fast.

Примечание по реализации:

Созданный Spliterator также сообщает о характеристике Spliterator.SUBSIZED.

Возвращает:

Spliterator для элементов этого списка

Начиная с:

1.8

default void addFirst(E e)

Определено в:

addFirst в интерфейсе SequencedCollection<E>

Требования к реализации:

Реализация в этом интерфейсе вызывает add(0, e).

Параметры:

e — добавляемый элемент

Исключения:

NullPointerException — если указанный элемент равен null, а эта коллекция не допускает элементы null

UnsupportedOperationException — если реализация этой коллекции не поддерживает данную операцию

Начиная с:

21

default void addLast(E e)

Определено в:

addLast в интерфейсе SequencedCollection<E>

Требования к реализации:

Реализация в этом интерфейсе вызывает add(e).

Параметры:

e — добавляемый элемент.

Исключения:

NullPointerException — если указанный элемент равен null, а эта коллекция не допускает элементы null

UnsupportedOperationException — если реализация этой коллекции не поддерживает данную операцию

Начиная с:

21

default E getFirst()

Определено в:

getFirst в интерфейсе SequencedCollection<E>

Требования к реализации:

Если этот список не пуст, реализация в этом интерфейсе возвращает результат вызова get(0). В противном случае она выбрасывает NoSuchElementException.

Возвращает:

полученный элемент

Исключения:

NoSuchElementException — если эта коллекция пуста

Начиная с:

21

default E getLast()

Определено в:

getLast в интерфейсе SequencedCollection<E>

Требования к реализации:

Если этот список не пуст, реализация в этом интерфейсе возвращает результат вызова get(size() - 1). В противном случае она выбрасывает NoSuchElementException.

Возвращает:

полученный элемент

Исключения:

NoSuchElementException — если эта коллекция пуста

Начиная с:

21

default E removeFirst()

Определено в:

removeFirst в интерфейсе SequencedCollection<E>

Требования к реализации:

Если этот список не пуст, реализация в этом интерфейсе возвращает результат вызова remove(0). В противном случае она выбрасывает NoSuchElementException.

Возвращает:

удалённый элемент

Исключения:

NoSuchElementException — если эта коллекция пуста

UnsupportedOperationException — если реализация этой коллекции не поддерживает данную операцию

Начиная с:

21

default E removeLast()

Определено в:

removeLast в интерфейсе SequencedCollection<E>

Требования к реализации:

Если этот список не пуст, реализация в этом интерфейсе возвращает результат вызова remove(size() - 1). В противном случае она выбрасывает NoSuchElementException.

Возвращает:

удалённый элемент

Исключения:

NoSuchElementException — если эта коллекция пуста

UnsupportedOperationException — если реализация этой коллекции не поддерживает данную операцию

Начиная с:

21

default List<E> reversed()

Определено в:

reversed в интерфейсе SequencedCollection<E>

Требования к реализации:

Реализация в этом интерфейсе возвращает представление List в обратном порядке. Метод reversed() этого представления возвращает ссылку на этот List. Другие операции над представлением реализуются посредством вызовов общедоступных методов этого List. Точная связь между вызовами методов представления и вызовами методов этого List не определена. Однако операции, чувствительные к порядку, обычно ведут себя так, как если бы они делегировали вызов соответствующему методу с противоположной ориентацией. Например, вызов getFirst для представления может привести к вызову getLast для этого List.

Возвращает:

представление этой коллекции в обратном порядке в виде List

Начиная с:

21

static <E> List<E> of()

Параметры типа:

E — тип элементов List

Возвращает:

пустой List

Начиная с:

9

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

Параметры типа:

E — тип элементов List

Параметры:

e1 — единственный элемент

Возвращает:

List, содержащий указанный элемент

Исключения:

NullPointerException — если элемент равен null

Начиная с:

9

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

Параметры типа:

E — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

9

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

Параметры типа:

E — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

e3 — третий элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

9

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

Параметры типа:

E — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

e3 — третий элемент

e4 — четвёртый элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

9

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

Параметры типа:

E — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

e3 — третий элемент

e4 — четвёртый элемент

e5 — пятый элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

9

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

Параметры типа:

E — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

e3 — третий элемент

e4 — четвёртый элемент

e5 — пятый элемент

e6 — шестой элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

9

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

Параметры типа:

E — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

e3 — третий элемент

e4 — четвёртый элемент

e5 — пятый элемент

e6 — шестой элемент

e7 — седьмой элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

9

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

Параметры типа:

E — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

e3 — третий элемент

e4 — четвёртый элемент

e5 — пятый элемент

e6 — шестой элемент

e7 — седьмой элемент

e8 — восьмой элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

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 — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

e3 — третий элемент

e4 — четвёртый элемент

e5 — пятый элемент

e6 — шестой элемент

e7 — седьмой элемент

e8 — восьмой элемент

e9 — девятый элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

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)

Параметры типа:

E — тип элементов List

Параметры:

e1 — первый элемент

e2 — второй элемент

e3 — третий элемент

e4 — четвёртый элемент

e5 — пятый элемент

e6 — шестой элемент

e7 — седьмой элемент

e8 — восьмой элемент

e9 — девятый элемент

e10 — десятый элемент

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null

Начиная с:

9

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

Примечание API:

Этот метод также принимает в качестве аргумента один массив. Типом элементов результирующего списка будет тип компонентов массива, а размер списка будет равен длине массива. Чтобы создать список с одним элементом, которым является массив, выполните следующие действия:

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

В этом случае будет вызван метод List.of(E).

Параметры типа:

E — тип элементов List

Параметры:

elements — элементы, которые будут содержаться в списке

Возвращает:

List, содержащий указанные элементы

Исключения:

NullPointerException — если элемент равен null или массив равен null

Начиная с:

9

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

Примечание по реализации:

Если указанная Collection является немодифицируемым List, вызов copyOf обычно не создаёт копию.

Параметры типа:

E — тип элементов List

Параметры:

coll — Collection, из которой берутся элементы; не должна быть null

Возвращает:

List, содержащий элементы указанной Collection

Исключения:

NullPointerException — если coll равен null или содержит значения null

Начиная с:

10