Интерфейс List<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; некоторые реализации будут проявлять первое поведение, а некоторые — второе. В более общем смысле, попытка выполнения операции с недопустимым элементом, завершение которой не приведет к вставке недопустимого элемента в список, может вызвать исключение или может завершиться успешно, в зависимости от реализации. Такие исключения помечены как «необязательные» в спецификации для данного интерфейса.

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

Методы

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 такой, что (o==null ? e==null : o.equals(e)).

Указано в:

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

Параметры:

o - элемент, присутствие которого в этом списке необходимо проверить

Возвращает:

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

Инициирует:

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

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

iterator

Iterator<E> iterator()

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

Указано в:

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

Указано в:

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

Возвращает:

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

toArray

Object[] toArray()

Указано в:

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

Возвращает:

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

См. также:

Arrays.asList(Object[])

toArray

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

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

Указано в:

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

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

T - тип выполнения массива, содержащего коллекцию

Параметры:

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

Возвращает:

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

Инициирует:

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

NullPointerException - если указанный массив имеет значение null

add

boolean add(E e)

Указано в:

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

Параметры:

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

Возвращает:

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

Инициирует:

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

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

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

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

remove

boolean remove(Object o)

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

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

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

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

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

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

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

Параметры:

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

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

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

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

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

С:

1.8

clear

void clear()

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

Указано в:

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

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

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

equals

boolean equals(Object o)

Сравнивает указанный объект с этим списком на предмет равенства. Возвращает true тогда и только тогда, когда указанный объект также является списком, оба списка имеют одинаковый размер, и все соответствующие пары элементов в двух списках являются равными. (Два элемента e1 и e2 равны, если (e1==null ? e2==null : e1.equals(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());

Указано в:

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 такой, что (o==null ? get(i)==null : o.equals(get(i))), или -1, если такого индекса нет.

Параметры:

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

Возвращает:

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

Исключение:

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

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

lastIndexOf

int lastIndexOf(Object o)

Возвращает индекс последнего вхождения указанного элемента в этот список, или -1, если этот список не содержит элемент. Более формально, возвращает наибольший индекс i такой, что (o==null ? get(i)==null : o.equals(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)

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

Параметры:

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

toIndex - высокая граница (исключая) subList

Возвращает:

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

Исключение:

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

spliterator

default Spliterator<E> spliterator()

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

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

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

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

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

По умолчанию реализация создаёт позднесвязываемый итератор из Iterator списка. Итератор наследует свойства fail-fast итератора списка.

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

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

Возвращает:

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

С:

1.8