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

Параметры типа:: E - тип элементов в этом списке

Все суперинтерфейсы:: Collection<E>, Iterable<E>

Все известные реализующие классы:: AbstractList, AbstractSequentialList, ArrayList, AttributeList, CopyOnWriteArrayList, LinkedList, RoleList, RoleUnresolvedList, Stack, Vector

public interface List<E>
extends Collection<E>

Упорядоченное множество (также известное как последовательность). Пользователь этого интерфейса имеет точный контроль над тем, куда в списке вставляется каждый элемент. Пользователь может получать доступ к элементам по целочисленному индексу (позиции в списке) и искать элементы в списке.

В отличие от множеств, списки обычно допускают дублирование элементов. Более формально, списки обычно допускают пары элементов e1 и e2, такие что e1.equals(e2), и они обычно допускают несколько нулевых элементов, если они вообще допускают нулевые элементы. Не исключено, что кто-то захочет реализовать список, запрещающий дублирование, выбрасывая исключения во время выполнения при попытке их вставки, но мы ожидаем, что такое использование будет редким.

Интерфейс List устанавливает дополнительные условия, помимо тех, которые указаны в интерфейсе Collection, на контракты методов iterator, add, remove, equals, и hashCode. Объявления других унаследованных методов также включены здесь для удобства.

Интерфейс List предоставляет четыре метода для позиционного (индексированного) доступа к элементам списка. Списки (подобно массивам Java) нумеруются с нуля. Обратите внимание, что эти операции могут выполняться за время, пропорциональное значению индекса для некоторых реализаций (например, класс LinkedList). Таким образом, итерация по элементам списка обычно предпочтительнее индексирования, если вызывающий код не знает реализации.

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

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

Интерфейс List предоставляет два метода для эффективной вставки и удаления нескольких элементов в произвольной точке списка.

Примечание: хотя списки могут содержать сами себя в качестве элементов, следует проявлять крайнюю осторожность: методы equals и hashCode больше не определены для такого списка.

Некоторые реализации списков имеют ограничения на элементы, которые они могут содержать. Например, некоторые реализации запрещают нулевые элементы, а некоторые имеют ограничения на типы своих элементов. Попытка добавить недопустимый элемент приводит к выбрасыванию необрабатываемого исключения, обычно NullPointerException или ClassCastException. Попытка запросить наличие недопустимого элемента может вызвать исключение или просто вернуть false; некоторые реализации будут демонстрировать первое поведение, а некоторые - второе. Более обще, попытка выполнить операцию над недопустимым элементом, завершение которой не приведет к вставке недопустимого элемента в список, может вызвать исключение или выполниться успешно, по выбору реализации. Такие исключения помечены как "необязательные" в спецификации этого интерфейса.

Неизменяемые списки

Статические фабричные методы List.of и List.copyOf предоставляют удобный способ создания неизменяемых списков. Экземпляры List, созданные этими методами, обладают следующими характеристиками:

Они неизменяемы. Элементы нельзя добавлять, удалять или заменять. Вызов любого мутаторного метода на списке всегда вызовет исключение UnsupportedOperationException. Однако, если содержащиеся элементы сами по себе изменяемы, это может привести к тому, что содержимое списка, кажется, изменится.
Они не допускают null элементы. Попытки создать их с null элементами приводят к NullPointerException.
Они сериализуемы, если все элементы сериализуемы.
Порядок элементов в списке такой же, как порядок предоставленных аргументов или элементов в предоставленном массиве.
Они значение-ориентированные. Вызывающие стороны не должны делать предположений об идентичности возвращенных экземпляров. Фабрики могут создавать новые экземпляры или повторно использовать существующие. Следовательно, операции, чувствительные к идентичности, над этими экземплярами (равенство по ссылке (==), хэш-код по идентичности и синхронизация) ненадежны и должны быть избегаемы.
Они сериализуются, как указано на странице Serialized Form.

Этот интерфейс является членом 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)`	Добавляет все элементы из указанного набора в конец этого списка в порядке, в котором они возвращаются итератором указанного набора (необязательная операция).
`void`	`clear()`	Удаляет все элементы из этого списка (необязательная операция).
`boolean`	`contains(Object o)`	Возвращает `true`, если этот список содержит указанный элемент.
`boolean`	`containsAll(Collection<?> c)`	Возвращает `true`, если этот список содержит все элементы указанного набора.
`static <E> List<E>`	`copyOf(Collection<? extends E> coll)`	Возвращает неизменяемый список содержащий элементы данного набора, в порядке итерации.
`boolean`	`equals(Object o)`	Сравнивает указанный объект с этим списком на равенство.
`E`	`get(int index)`	Возвращает элемент в указанной позиции в этом списке.
`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)`	Возвращает неизменяемый список, содержащий один элемент.
`static <E> List<E>`	`of(E... elements)`	Возвращает неизменяемый список, содержащий произвольное количество элементов.
`static <E> List<E>`	`of(E e1, E e2)`	Возвращает неизменяемый список, содержащий два элемента.
`static <E> List<E>`	`of(E e1, E e2, E e3)`	Возвращает неизменяемый список, содержащий три элемента.
`static <E> List<E>`	`of(E e1, E e2, E e3, E e4)`	Возвращает неизменяемый список, содержащий четыре элемента.
`static <E> List<E>`	`of(E e1, E e2, E e3, E e4, E e5)`	Возвращает неизменяемый список, содержащий пять элементов.
`static <E> List<E>`	`of(E e1, E e2, E e3, E e4, E e5, E e6)`	Возвращает неизменяемый список, содержащий шесть элементов.
`static <E> List<E>`	`of(E e1, E e2, E e3, E e4, E e5, E e6, E e7)`	Возвращает неизменяемый список, содержащий семь элементов.
`static <E> List<E>`	`of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8)`	Возвращает неизменяемый список, содержащий восемь элементов.
`static <E> List<E>`	`of(E e1, E e2, E e3, E e4, E e5, E e6, E e7, E e8, E e9)`	Возвращает неизменяемый список, содержащий девять элементов.
`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`	`remove(int index)`	Удаляет элемент в указанной позиции в этом списке (необязательная операция).
`boolean`	`remove(Object o)`	Удаляет первое вхождение указанного элемента из этого списка, если он присутствует (необязательная операция).
`boolean`	`removeAll(Collection<?> c)`	Удаляет из этого списка все его элементы, которые содержатся в указанном наборе (необязательная операция).
`default void`	`replaceAll(UnaryOperator<E> operator)`	Заменяет каждый элемент этого списка результатом применения оператора к этому элементу.
`boolean`	`retainAll(Collection<?> c)`	Оставляет в этом списке только элементы, которые содержатся в указанном наборе (необязательная операция).
`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, если этот список содержит указанный элемент. Более формально, возвращает true тогда и только тогда, когда этот список содержит по меньшей мере один элемент e такой, что Objects.equals(o, e).

Указано в:: contains в интерфейсе Collection<E>
Параметры:: o - элемент, присутствие которого в этом списке требуется проверить
Возвращает:: true если этот список содержит указанный элемент
Исключения:: ClassCastException - если тип указанного элемента несовместим с этим списком (необязательно); NullPointerException - если указанный элемент равен null, а этот список не допускает null-элементы (необязательно)

iterator

Iterator<E> iterator()

Возвращает итератор по элементам в этом списке в правильной последовательности.

Указано в:: iterator в интерфейсе Collection<E>
Указано в:: iterator в интерфейсе Iterable<E>
Возвращает:: итератор по элементам в этом списке в правильной последовательности

toArray

Object[] toArray()

Возвращает массив, содержащий все элементы в этом списке в правильной последовательности (от первого к последнему элементу).

Возвращаемый массив будет «безопасным» в том смысле, что к нему не сохраняются ссылки из этого списка. (Иными словами, этот метод должен выделять новый массив, даже если этот список поддерживается массивом). Таким образом, вызывающая сторона свободна изменять возвращаемый массив.

Этот метод действует как мост между основанными на массивах и основанными на коллекциях API.

Указано в:: toArray в интерфейсе Collection<E>
Возвращает:: массив, содержащий все элементы в этом списке в правильной последовательности
См. также:: Arrays.asList(Object[])

toArray

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

Возвращает массив, содержащий все элементы в этом списке в правильной последовательности (от первого к последнему элементу); тип времени выполнения возвращаемого массива — тип указанного массива. Если список помещается в указанный массив, он возвращается в нём. В противном случае выделяется новый массив с типом времени выполнения указанного массива и размером этого списка.

Если список помещается в указанный массив с избыточным пространством (т. е. массив имеет больше элементов, чем список), элемент в массиве сразу после конца списка устанавливается в null. (Это полезно для определения длины списка только в том случае, если вызывающая сторона знает, что список не содержит каких-либо null-элементов.)

Как и метод toArray(), этот метод действует как мост между основанными на массивах и основанными на коллекциях 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-элементы, а другие наложат ограничения на тип добавляемых элементов. Классы списков должны чётко указывать в своей документации любые ограничения на добавляемые элементы.

Указано в:: add в интерфейсе Collection<E>
Параметры:: e - элемент, который будет добавлен в конец этого списка
Возвращает:: true (как указано в Collection.add(E))
Исключения:: UnsupportedOperationException - если операция add не поддерживается этим списком; ClassCastException - если класс указанного элемента препятствует его добавлению в этот список; NullPointerException - если указанный элемент равен null, а этот список не допускает null-элементы; IllegalArgumentException - если какое-либо свойство этого элемента препятствует его добавлению в этот список

remove

boolean remove(Object o)

Удаляет первое вхождение указанного элемента из этого списка, если он присутствует (необязательная операция). Если этот список не содержит элемент, он не изменяется. Более формально, удаляет элемент с наименьшим индексом i таким, что Objects.equals(o, get(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 - если типы одного или нескольких элементов в указанной коллекции несовместимы с этим списком (необязательно); NullPointerException - если указанная коллекция содержит один или несколько null-элементов, а этот список не допускает null-элементы (необязательно), или если указанная коллекция равна null
См. также:: contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

Добавляет все элементы указанной коллекции в конец этого списка в порядке, в котором они возвращаются итератором указанной коллекции (необязательная операция). Поведение этой операции не определено, если указанная коллекция модифицируется во время выполнения операции. (Обратите внимание, что это произойдёт, если указанная коллекция — это этот список, и он непустой.)

Указано в:: addAll в интерфейсе Collection<E>
Параметры:: c - коллекция, содержащая элементы, которые должны быть добавлены в этот список
Возвращает:: true если этот список изменился в результате вызова
Исключения:: UnsupportedOperationException - если операция addAll не поддерживается этим списком; ClassCastException - если класс элемента указанной коллекции препятствует его добавлению в этот список; NullPointerException - если указанная коллекция содержит один или несколько null-элементов, а этот список не допускает null-элементы, или если указанная коллекция равна null; IllegalArgumentException - если какое-либо свойство элемента указанной коллекции препятствует его добавлению в этот список
См. также:: add(Object)

addAll

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

Вставляет все элементы указанной коллекции в этот список в указанной позиции (необязательная операция). Смещает элемент, который в данный момент находится на этой позиции (если таковой имеется), и все последующие элементы вправо (увеличивает их индексы). Новые элементы будут отображаться в этом списке в порядке, в котором они возвращаются итератором указанной коллекции. Поведение этой операции не определено, если указанная коллекция модифицируется во время выполнения операции. (Обратите внимание, что это произойдёт, если указанная коллекция — это этот список, и он непустой.)

Параметры:: index - индекс, в котором следует вставить первый элемент из указанной коллекции; c - коллекция, содержащая элементы, которые нужно добавить в этот список
Возвращает:: true , если этот список изменился в результате вызова
Выбрасывает:: UnsupportedOperationException - если операция addAll не поддерживается этим списком; ClassCastException - если класс элемента указанной коллекции препятствует его добавлению в этот список; NullPointerException - если указанная коллекция содержит один или несколько нулевых элементов, а этот список не допускает нулевых элементов, или если указанная коллекция равна null; IllegalArgumentException - если какое-либо свойство элемента указанной коллекции препятствует его добавлению в этот список; IndexOutOfBoundsException - если индекс находится вне допустимого диапазона (index < 0 || index > size())

removeAll

boolean removeAll(Collection<?> c)

Удаляет из этого списка все его элементы, которые содержатся в указанной коллекции (необязательная операция).

Определено в:: removeAll в интерфейсе Collection<E>
Параметры:: c - коллекция, содержащая элементы, которые нужно удалить из этого списка
Возвращает:: true , если этот список изменился в результате вызова
Выбрасывает:: UnsupportedOperationException - если операция removeAll не поддерживается этим списком; ClassCastException - если класс элемента этого списка несовместим с указанной коллекцией (необязательно); NullPointerException - если этот список содержит нулевой элемент, а указанная коллекция не допускает нулевых элементов (необязательно), или если указанная коллекция равна null
См. также:: remove(Object), contains(Object)

retainAll

boolean retainAll(Collection<?> c)

Оставляет в этом списке только элементы, содержащиеся в указанной коллекции (необязательная операция). Другими словами, удаляет из этого списка все элементы, которые не содержатся в указанной коллекции.

Определено в:: retainAll в интерфейсе Collection<E>
Параметры:: c - коллекция, содержащая элементы, которые следует сохранить в этом списке
Возвращает:: true , если этот список изменился в результате вызова
Выбрасывает:: UnsupportedOperationException - если операция retainAll не поддерживается этим списком; ClassCastException - если класс элемента этого списка несовместим с указанной коллекцией (необязательно); NullPointerException - если этот список содержит нулевой элемент, а указанная коллекция не допускает нулевых элементов (необязательно), или если указанная коллекция равна null
См. также:: remove(Object), contains(Object)

replaceAll

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 - если этот список неизменяем. Реализации могут выбросить это исключение, если элемент нельзя заменить или если, вообще, изменение не поддерживается

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

С:

1.8

sort

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

Сортирует этот список в соответствии с порядком, заданным указанным Comparator. Сортировка стабильна: этот метод не должен менять порядок равных элементов.

Все элементы в этом списке должны быть взаимно сравнимыми с помощью указанного компаратора (то есть, c.compare(e1, e2) не должно генерировать исключение ClassCastException для любых элементов e1 и e2 в списке).

Если указанный компаратор равен null , то все элементы в этом списке должны реализовывать интерфейс Comparable и должно использоваться естественное упорядочение элементов.

Этот список должен быть изменяемым, но не обязательно изменяемым по размеру.

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

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

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

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

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

Реализация была адаптирована из сортировки списков Tim Peters для Python ( TimSort). Она использует методы из статьи "Optimistic Sorting and Information Theoretic Complexity" Питера МакИлрой, опубликованной в Трудах четвертой ежегодной конференции ACM-SIAM по дискретным алгоритмам, стр. 467-474, январь 1993 года.

Параметры:

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

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

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

UnsupportedOperationException - если итератор списка не поддерживает операцию set

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

С:

1.8

clear

void clear()

Удаляет все элементы из этого списка (необязательная операция). Список будет пустым после возвращения этого вызова.

Определено в:: clear в интерфейсе Collection<E>
Выбрасывает:: UnsupportedOperationException - если операция clear не поддерживается этим списком

equals

boolean equals(Object o)

Сравнивает указанный объект с этим списком на равенство. Возвращает true тогда и только тогда, когда указанный объект также является списком, оба списка имеют одинаковый размер и все соответствующие пары элементов в двух списках являются равными. (Два элемента e1 и e2 считаются равными, если Objects.equals(e1, e2)). Другими словами, два списка определяются как равные, если они содержат одни и те же элементы в том же порядке. Это определение гарантирует, что метод equals работает правильно с различными реализациями интерфейса List.

Определено в:: equals в интерфейсе Collection<E>
Переопределяет:: equals в классе Object
Параметры:: o - объект, который нужно сравнить на равенство с этим списком
Возвращает:: true , если указанный объект равен этому списку
См. также:: Object.hashCode(), HashMap

hashCode

int hashCode()

Возвращает значение хэш-кода для этого списка. Хэш-код списка определяется как результат следующего вычисления:

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

Это гарантирует, что list1.equals(list2) подразумевает, что list1.hashCode()==list2.hashCode() для любых двух списков, list1 и list2, как требуется общим контрактом Object.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)

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

Параметры:: index - индекс, в который должен быть вставлен указанный элемент; element - элемент, который нужно вставить
Использует исключения:: UnsupportedOperationException - если операция add не поддерживается этим списком; ClassCastException - если класс указанного элемента препятствует его добавлению в этот список; NullPointerException - если указанный элемент имеет значение null, а этот список не допускает null-элементы; IllegalArgumentException - если некоторые свойства указанного элемента препятствуют его добавлению в этот список; IndexOutOfBoundsException - если индекс находится вне диапазона (index < 0 || index > size())

remove

E remove(int index)

Удаляет элемент по указанной позиции в этом списке (необязательная операция). Перемещает все последующие элементы влево (уменьшает их индексы на единицу). Возвращает удалённый элемент из списка.

Параметры:: index - индекс удаляемого элемента
Возвращает:: элемент, который ранее находился в указанной позиции
Использует исключения:: UnsupportedOperationException - если операция remove не поддерживается этим списком; IndexOutOfBoundsException - если индекс находится вне диапазона (index < 0 || index >= size())

indexOf

int indexOf(Object o)

Возвращает индекс первого вхождения указанного элемента в этот список, или -1, если этот список не содержит элемент. Более формально, возвращает наименьший индекс i такой, что Objects.equals(o, get(i)), или -1, если такого индекса нет.

Параметры:: o - элемент для поиска
Возвращает:: индекс первого вхождения указанного элемента в этот список, или -1, если этот список не содержит элемент
Использует исключения:: ClassCastException - если тип указанного элемента несовместим с этим списком (необязательно); NullPointerException - если указанный элемент имеет значение null, а этот список не допускает null-элементы (необязательно)

lastIndexOf

int lastIndexOf(Object o)

Возвращает индекс последнего вхождения указанного элемента в этом списке, или -1, если этот список не содержит элемент. Более формально, возвращает наибольший индекс i такой, что Objects.equals(o, get(i)), или -1, если такого индекса нет.

Параметры:: o - элемент для поиска
Возвращает:: индекс последнего вхождения указанного элемента в этом списке, или -1, если этот список не содержит элемент
Использует исключения:: ClassCastException - если тип указанного элемента несовместим с этим списком (необязательно); NullPointerException - если указанный элемент имеет значение null, а этот список не допускает null-элементы (необязательно)

listIterator

ListIterator<E> listIterator()

Возвращает итератор по элементам в этом списке (в правильной последовательности).

Возвращает:: итератор по элементам в этом списке (в правильной последовательности)

listIterator

ListIterator<E> listIterator(int index)

Возвращает итератор по элементам в этом списке (в правильной последовательности), начиная с указанной позиции в списке. Указанный индекс указывает на первый элемент, который будет возвращён начальным вызовом next. Начальный вызов previous вернёт элемент с индексом на единицу меньше указанного.

Параметры:: 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 - нижняя граница (включительно) подсписка; toIndex - верхняя граница (исключительно) подсписка
Возвращает:: представление указанного диапазона в этом списке
Использует исключения:: IndexOutOfBoundsException - для некорректного индекса конечной точки (fromIndex < 0 || toIndex > size || fromIndex > toIndex)

spliterator

default Spliterator<E> spliterator()

Создаёт Spliterator по элементам в этом списке.

Итератор Spliterator сообщает о Spliterator.SIZED и Spliterator.ORDERED. Реализации должны документировать сообщение об дополнительных характеристических значениях.

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

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

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

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

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

По умолчанию создаётся отложенно-связанный итератор следующим образом:

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

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

Созданный итератор Spliterator дополнительно сообщает о Spliterator.SUBSIZED.

Возвращает:

итератор Spliterator по элементам в этом списке

С:

1.8

of

static <E> List<E> of()

Возвращает неизменяемый список, содержащий ноль элементов. Подробности см. в разделе Неизменяемые списки.

Параметры типа:: E - тип элемента List
Возвращает:: пустой List
С:: 9

of

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

Возвращает неизменяемый список, содержащий один элемент. Подробности см. в разделе Неизменяемые списки.

Параметры типа:: E - тип элемента List
Параметры:: e1 - единственный элемент
Возвращает:: List содержащий указанный элемент
Использует исключения:: NullPointerException - если элемент null
С:: 9

of

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

Возвращает неизменяемый список, содержащий два элемента. Подробности см. в разделе Неизменяемые списки.

Параметры типа:: E - тип элемента List
Параметры:: e1 - первый элемент; e2 - второй элемент
Возвращает:: List содержащий указанные элементы
Использует исключения:: NullPointerException - если элемент null
С:: 9

of

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

Возвращает неизменяемый список, содержащий три элемента. Подробности см. в разделе Неизменяемые списки.

Параметры типа:: E - тип элемента List
Параметры:: e1 - первый элемент; e2 - второй элемент; e3 - третий элемент
Возвращает:: a List, содержащий указанные элементы
Выбрасывает:: NullPointerException - если элемент является null
С:: 9

of

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

Возвращает неизменяемый список, содержащий четыре элемента. Подробности см. в разделе Неизменяемые списки.

Параметры типа:: E - тип элемента List
Параметры:: e1 - первый элемент; e2 - второй элемент; e3 - третий элемент; e4 - четвёртый элемент
Возвращает:: a List, содержащий указанные элементы
Выбрасывает:: NullPointerException - если элемент является null
С:: 9

of

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

Возвращает неизменяемый список, содержащий пять элементов. Подробности см. в разделе Неизменяемые списки.

Параметры типа:: E - тип элемента List
Параметры:: e1 - первый элемент; e2 - второй элемент; e3 - третий элемент; e4 - четвёртый элемент; e5 - пятый элемент
Возвращает:: a List, содержащий указанные элементы
Выбрасывает:: NullPointerException - если элемент является null
С:: 9

of

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 - шестой элемент
Возвращает:: a 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 - тип элемента List
Параметры:: e1 - первый элемент; e2 - второй элемент; e3 - третий элемент; e4 - четвёртый элемент; e5 - пятый элемент; e6 - шестой элемент; e7 - седьмой элемент
Возвращает:: a 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 - тип элемента List
Параметры:: e1 - первый элемент; e2 - второй элемент; e3 - третий элемент; e4 - четвёртый элемент; e5 - пятый элемент; e6 - шестой элемент; e7 - седьмой элемент; e8 - восьмой элемент
Возвращает:: a 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 - тип элемента List
Параметры:: e1 - первый элемент; e2 - второй элемент; e3 - третий элемент; e4 - четвёртый элемент; e5 - пятый элемент; e6 - шестой элемент; e7 - седьмой элемент; e8 - восьмой элемент; e9 - девятый элемент
Возвращает:: a 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)

Возвращает неизменяемый список, содержащий десять элементов. Подробности см. в разделе Неизменяемые списки.

Параметры типа:: E - тип элемента List
Параметры:: e1 - первый элемент; e2 - второй элемент; e3 - третий элемент; e4 - четвёртый элемент; e5 - пятый элемент; e6 - шестой элемент; e7 - седьмой элемент; e8 - восьмой элемент; e9 - девятый элемент; e10 - десятый элемент
Возвращает:: a List, содержащий указанные элементы
Выбрасывает:: NullPointerException - если элемент является null
С:: 9

of

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

Возвращает неизменяемый список, содержащий произвольное количество элементов. Подробности см. в разделе Неизменяемые списки.

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

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

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

Это вызовет метод List.of(E) вместо этого.

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

E - тип элемента List

Параметры:

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

Возвращает:

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

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

NullPointerException - если элемент является null или если массив является null

С:

copyOf

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

Возвращает неизменяемый список, содержащий элементы заданного объекта Collection в порядке их итерации. Заданный объект Collection не должен быть null, и он не должен содержать элементов null. Если заданный объект Collection впоследствии будет изменён, возвращаемый список не будет отражать эти изменения.

Примечание реализации:: Если заданный объект Collection является неизменяемым списком, вызов copyOf обычно не создаст копию.
Параметры типа:: E - тип элемента List
Параметры:: coll - объект Collection, из которого извлекаются элементы, не должен быть null
Возвращает:: a List, содержащий элементы заданного объекта Collection
Выбрасывает:: NullPointerException - если coll равен null или содержит элементы null
С:: 10

© 1993, 2020, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://docs.oracle.com/en/java/javase/11/docs/api/java.base/java/util/List.html