Список интерфейсов<E>

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

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

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

public interface List<E> extends SequencedCollection<E>

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

В отличие от множеств, списки обычно допускают дублирование элементов. Более формально, списки обычно допускают пары элементов e1 и 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)`	Добавляет все элементы из указанной коллекции в конец этого списка в порядке, в котором они возвращаются итератором указанной коллекции (необязательная операция).
`default void`	`addFirst(E e)`	Добавляет элемент как первый элемент этой коллекции (необязательная операция).
`default void`	`addLast(E e)`	Добавляет элемент как последний элемент этой коллекции (необязательная операция).
`void`	`clear()`	Удаляет все элементы из этого списка (необязательная операция).
`boolean`	`contains(Object o)`	Возвращает `true`, если этот список содержит указанный элемент.
`boolean`	`containsAll(Collection<?> c)`	Возвращает `true`, если этот список содержит все элементы указанной коллекции.
`static <E> List<E>`	`copyOf(Collection<? extends E> coll)`	Возвращает неизменяемый список содержащий элементы заданной коллекции в порядке итерации.
`boolean`	`equals(Object o)`	Сравнивает указанный объект с этим списком на равенство.
`E`	`get(int index)`	Возвращает элемент в указанной позиции в этом списке.
`default E`	`getFirst()`	Возвращает первый элемент этой коллекции.
`default E`	`getLast()`	Возвращает последний элемент этой коллекции.
`int`	`hashCode()`	Возвращает значение хэш-кода для этого списка.
`int`	`indexOf(Object o)`	Возвращает индекс первого вхождения указанного элемента в этом списке или -1, если этот список не содержит элемент.
`boolean`	`isEmpty()`	Возвращает `true`, если этот список не содержит элементов.
`Iterator<E>`	`iterator()`	Возвращает итератор по элементам в этом списке в правильной последовательности.
`int`	`lastIndexOf(Object o)`	Возвращает индекс последнего вхождения указанного элемента в этом списке, или -1, если этот список не содержит элемент.
`ListIterator<E>`	`listIterator()`	Возвращает итератор по элементам в этом списке (в правильной последовательности).
`ListIterator<E>`	`listIterator(int index)`	Возвращает итератор по элементам в этом списке (в правильной последовательности), начиная с указанной позиции в списке.
`static <E> List<E>`	`of()`	Возвращает неизменяемый список, содержащий ноль элементов.
`static <E> List<E>`	`of(E e1)`	Возвращает неизменяемый список, содержащий один элемент.
`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 E`	`removeFirst()`	Удаляет и возвращает первый элемент этой коллекции (необязательная операция).
`default E`	`removeLast()`	Удаляет и возвращает последний элемент этой коллекции (необязательная операция).
`default void`	`replaceAll(UnaryOperator<E> operator)`	Заменяет каждый элемент этого списка результатом применения оператора к этому элементу.
`boolean`	`retainAll(Collection<?> c)`	Оставляет только элементы в этом списке, которые содержатся в указанной коллекции (необязательная операция).
`default List<E>`	`reversed()`	Возвращает отсортированный по обратному порядку просмотр этой коллекции.
`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 на основе массивов и API на основе коллекций.

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

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

Возвращает:

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

См. также:

toArray

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

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

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

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

Предположим, x — это список, известный тем, что содержит только строки. Следующий код можно использовать для выгрузки списка в новый выделенный массив типа String:


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

Обратите внимание, что toArray(new Object[0]) идентичен по функции toArray().

Определено в:: toArray в интерфейсе Collection<E>
Типы параметров:: T - тип компонентов массива, который должен содержать коллекцию
Параметры:: a - массив, в который должны быть сохранены элементы этого списка, если он достаточно большой; в противном случае для этой цели выделяется новый массив того же типа времени выполнения.
Возвращает:: массив, содержащий элементы этого списка
Исключения:: ArrayStoreException - если тип времени выполнения указанного массива не является надтипом типа времени выполнения каждого элемента в этом списке; NullPointerException - если указанный массив равен null

add

boolean add(E e)

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

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

Определено в:: 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

См. также:

addAll

boolean addAll(Collection<? extends E> c)

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

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

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

Параметры:

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

Возвращает:

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

Исключения:

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

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

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

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

См. также:

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:

retainAll

boolean retainAll(Collection<?> c)

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

Specified by:

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

Parameters:

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

Returns:

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

Throws:

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

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

See Also:

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 или если результат оператора — нулевое значение, и этот список не допускает нулевых элементов (необязательно)

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" в материалах Fourth Annual ACM-SIAM Symposium on Discrete Algorithms, стр. 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 in interface Collection<E>

Overrides:

hashCode in class 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 in interface Collection<E>

Specified by:

spliterator in interface Iterable<E>

Implementation Requirements:

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

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

Implementation Note:

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

Returns:

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

Since:

1.8

addFirst

default void addFirst(E e)

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

Указано в:: addFirst в интерфейсе SequencedCollection<E>
Требования к реализации:: Реализация в этом интерфейсе вызывает add(0, e).
Параметры:: e - добавляемый элемент
Выбрасывает:: NullPointerException - если заданный элемент имеет значение null, а эта коллекция не допускает элементов null; UnsupportedOperationException - если реализация этой коллекции не поддерживает эту операцию
С:: 21

addLast

default void addLast(E e)

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

Указано в:: addLast в интерфейсе SequencedCollection<E>
Требования к реализации:: Реализация в этом интерфейсе вызывает add(e).
Параметры:: e - добавляемый элемент.
Выбрасывает:: NullPointerException - если заданный элемент имеет значение null, а эта коллекция не допускает элементов null; UnsupportedOperationException - если реализация этой коллекции не поддерживает эту операцию
С:: 21

getFirst

default E getFirst()

Возвращает первый элемент этой коллекции.

Указано в:: getFirst в интерфейсе SequencedCollection<E>
Требования к реализации:: Если этот список не пустой, реализация в этом интерфейсе возвращает результат вызова get(0). В противном случае, он выбрасывает NoSuchElementException.
Возвращает:: полученный элемент
Выбрасывает:: NoSuchElementException - если эта коллекция пуста
С:: 21

getLast

default E getLast()

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

Указано в:: getLast в интерфейсе SequencedCollection<E>
Требования к реализации:: Если этот список не пустой, реализация в этом интерфейсе возвращает результат вызова get(size() - 1). В противном случае, он выбрасывает NoSuchElementException.
Возвращает:: полученный элемент
Выбрасывает:: NoSuchElementException - если эта коллекция пуста
С:: 21

removeFirst

default E removeFirst()

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

Указано в:: removeFirst в интерфейсе SequencedCollection<E>
Требования к реализации:: Если этот список не пустой, реализация в этом интерфейсе возвращает результат вызова remove(0). В противном случае, он выбрасывает NoSuchElementException.
Возвращает:: удаленный элемент
Выбрасывает:: NoSuchElementException - если эта коллекция пуста; UnsupportedOperationException - если реализация этой коллекции не поддерживает эту операцию
С:: 21

removeLast

default E removeLast()

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

Указано в:: removeLast в интерфейсе SequencedCollection<E>
Требования к реализации:: Если этот список не пустой, реализация в этом интерфейсе возвращает результат вызова remove(size() - 1). В противном случае, он выбрасывает NoSuchElementException.
Возвращает:: удаленный элемент
Выбрасывает:: NoSuchElementException - если эта коллекция пуста; UnsupportedOperationException - если реализация этой коллекции не поддерживает эту операцию
С:: 21

reversed

default List<E> reversed()

Возвращает вид этой коллекции в обратном порядке. Порядок встречи элементов в возвращаемом виде — обратный порядку встречи элементов в этой коллекции. Обратный порядок влияет на все операции, чувствительные к порядку, включая те, которые выполняются на коллекциях-видах возвращаемого вида. Если реализация коллекции допускает изменения в этом виде, то изменения "проходят сквозь" в базовую коллекцию. Изменения в базовой коллекции могут или могут не отображаться в этом обратном виде, в зависимости от реализации.

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

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 - шестой элемент
Возвращает:: 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, 2023, 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/21/docs/api/java.base/java/util/List.html