Список интерфейсов<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.
Они сериализуемы, если все элементы сериализуемы.
Порядок элементов в списке такой же, как порядок предоставленных аргументов или элементов в предоставленном массиве.
Списки и их subList представления реализуют интерфейс RandomAccess.
Они являются базовыми значениями. Программисты должны рассматривать экземпляры, которые являются равными, как взаимозаменяемые и не должны использовать их для синхронизации, иначе может произойти непредсказуемое поведение. Например, в будущей версии синхронизация может завершиться сбоем. Вызывающие стороны не должны делать предположений об идентичности возвращаемых экземпляров. Фабрики свободны создавать новые экземпляры или повторно использовать существующие.
Они сериализуются как указано на странице Сериализованной формы.

Этот интерфейс является членом фреймворка Java Collections Framework.

С:

1.2

См. также:

Краткое описание методов

Модификатор и тип	Метод	Описание
`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)

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

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

removeAll

boolean removeAll(Collection<?> c)

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

Specified by:

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

Parameters:

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

Returns:

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

Throws:

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

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

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

See Also:

remove(Object)
contains(Object)

retainAll

boolean retainAll(Collection<?> c)

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

Specified by:

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

Parameters:

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

Returns:

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

Throws:

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

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

See Also:

remove(Object)
contains(Object)

replaceAll

default void replaceAll(UnaryOperator<E> operator)

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

Implementation Requirements:

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


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

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

Parameters:

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

Throws:

UnsupportedOperationException - если этот список неизменяемый. Реализации могут выбросить это исключение, если элемент нельзя заменить или если, в общем случае, изменение не поддерживается

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

Since:

1.8

sort

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

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

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

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

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

Implementation Requirements:: Реализация по умолчанию получает массив, содержащий все элементы в этом списке, сортирует массив и итерируется по этому списку, перезаписывая каждый элемент из соответствующей позиции в массиве. (Это позволяет избежать производительности n² log(n), которая возникнет при попытке отсортировать связанный список на месте.)
Implementation Note:: Эта реализация является стабильной, адаптивной, итеративной сортировкой слиянием, которая требует значительно меньше, чем n lg(n) сравнений, когда входной массив частично отсортирован, в то время как она обеспечивает производительность традиционной сортировки слиянием, когда входной массив упорядочен случайным образом. Если входной массив почти отсортирован, реализация требует примерно n сравнений. Требования к временным ресурсам варьируются от малой константы для почти отсортированных входных массивов до n/2 ссылок на объекты для массивов со случайным порядком.
Реализация адаптирована из сортировки списка Tim Peters для Python ( TimSort). Она использует техники из статьи Peter McIlroy "Optimistic Sorting and Information Theoretic Complexity", в Трудах четвертой ежегодной конференции ACM-SIAM по дискретным алгоритмам, стр. 467-474, январь 1993.
Parameters:: c - компаратор, используемый для сравнения элементов списка. Значение Comparator указывает, что должен использоваться естественный порядок элементов
Throws:: ClassCastException - если список содержит элементы, которые не взаимно сравнимы с помощью указанного компаратора; UnsupportedOperationException - если итератор списка не поддерживает операцию set; IllegalArgumentException - (необязательно) если компаратор нарушает соглашение Comparator
Since:: 1.8

clear

void clear()

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

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

equals

boolean equals(Object o)

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

Specified by:

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

Overrides:

equals в классе Object

Parameters:

o - объект, который нужно сравнить на равенство с этим списком

Returns:

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

See Also:

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().

Specified by:

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

Overrides:

hashCode в классе Object

Returns:

значение хэш-кода для этого списка

See Also:

get

E get(int index)

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

Parameters:: index - индекс возвращаемого элемента
Returns:: элемент по указанному индексу в этом списке
Throws:: IndexOutOfBoundsException - если индекс вне диапазона (index < 0 || index >= size())

set

E set(int index, E element)

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

Parameters:: index - индекс заменяемого элемента; element - элемент, который будет сохранён по указанному индексу
Returns:: элемент, который был ранее по указанному индексу
Throws:: UnsupportedOperationException - если операция set не поддерживается этим списком; ClassCastException - если класс указанного элемента запрещает его добавление в этот список; NullPointerException - если указанный элемент null, а этот список не допускает null-элементы; IllegalArgumentException - если какие-либо свойства указанного элемента запрещают его добавление в этот список; IndexOutOfBoundsException - если индекс вне диапазона (index < 0 || index >= size())

add

void add(int index, E element)

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

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

remove

E remove(int index)

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

Parameters:: index - индекс удаляемого элемента
Returns:: элемент, который был ранее по указанному индексу
Throws:: UnsupportedOperationException - если операция remove не поддерживается этим списком; IndexOutOfBoundsException - если индекс вне диапазона (index < 0 || index >= size())

indexOf

int indexOf(Object o)

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

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

lastIndexOf

int lastIndexOf(Object o)

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

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

listIterator

ListIterator<E> listIterator()

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

Returns:: итератор списка для элементов в этом списке (в правильном порядке)

listIterator

ListIterator<E> listIterator(int index)

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

Parameters:: index - индекс первого элемента, который будет возвращён итератором списка (вызовом next)
Returns:: итератор списка для элементов в этом списке (в правильном порядке), начиная с указанной позиции в списке
Throws:: 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.

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

Parameters:: fromIndex - нижняя граница (включительно) subList; toIndex - верхняя граница (исключительно) subList
Returns:: представление указанного диапазона в этом списке
Throws:: IndexOutOfBoundsException - для некорректного индекса конечной точки (fromIndex < 0 || toIndex > size || fromIndex > toIndex)

spliterator

default Spliterator<E> spliterator()

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

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

Specified by:

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

Specified by:

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

Implementation Requirements:

Базовая реализация создаёт итератор с отложенной привязкой следующим образом:

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

Implementation Note:

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

Returns:

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

Since:

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 - третий элемент
Возвращает:: список List, содержащий указанные элементы
Исключения:: NullPointerException - если элемент null
С момента:: 9

of

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

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

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

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

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

© 1993, 2021, 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/17/docs/api/java.base/java/util/List.html