Интерфейс 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()));
    }

Если итератор списка не поддерживает операцию 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). В ней используются методы из работы Питера Мак-Илроя «Optimistic Sorting and Information Theoretic Complexity», опубликованной в трудах четвёртого ежегодного симпозиума 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()

Возвращает:

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

ListIterator<E> listIterator(int index)

Параметры:

index - индекс первого элемента, который будет возвращён итератором списка (при вызове next)

Возвращает:

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

Выбрасывает:

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, сплитератор обнаружит это и выбросит ConcurrentModificationException. Если список также является экземпляром AbstractList, сплитератор будет использовать поле modCount списка, чтобы обеспечить дополнительную защиту от таких изменений.
• В противном случае реализация по умолчанию создает сплитератор из Iterator списка. Сплитератор наследует поведение итератора списка при обнаружении изменений.

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

Созданный 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>

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

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

Возвращает:

представление этой коллекции с обратным порядком в виде 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)

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

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

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

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

Параметры:

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

Возвращает:

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

Вызывает:

NullPointerException — если coll равен null или содержит элементы null

С версии:

10

static <E> List<E> ofLazy(int size, IntFunction<? extends E> computingFunction)

class Application {

    private static final int POOL_SIZE = 3;

    static final List<OrderController> ORDERS
        = List.ofLazy(POOL_SIZE, _ -> new OrderController());

    public static OrderController orders() {
        long index = Thread.currentThread().threadId() % POOL_SIZE;
        return ORDERS.get((int)index);
    }

     // Eligible for constant folding
     OrderController orders = orders();
}

 class LazyList<E> extends AbstractList<E> {

     private final List<LazyConstant<E>> backingList;

     public LazyList(int size, IntFunction<E> computingFunction) {
         this.backingList = IntStream.range(0, size)
                 .mapToObj(i -> LazyConstant.of(() -> computingFunction.apply(i)))
                 .toList();
     }

     @Override
     public E get(int index) {
         return backingList.get(index).get();
     }
 }

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

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

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

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

Параметры:

size — размер возвращаемого ленивого списка

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

Возвращает:

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

Вызывает:

IllegalArgumentException — если предоставленное size отрицательно.

NullPointerException — если предоставленное computingFunction равно null

С версии:

26

См. также:

• LazyConstant^PREVIEW