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

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

Интерфейс Set устанавливает дополнительные условия, помимо унаследованных от интерфейса Collection, на контрактах всех конструкторов и на контрактах методов add, equals и hashCode. Объявления других унаследованных методов также включены здесь для удобства. (Спецификации, сопровождающие эти объявления, адаптированы к интерфейсу Set, но они не содержат дополнительных положений.)

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

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

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

Возвращает:

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

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 если этот набор ещё не содержал указанного элемента

Исключения:

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

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

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

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

remove

boolean remove(Object o)

Удаляет указанный элемент из этого набора, если он присутствует (необязательная операция). Более формально, удаляет элемент e такой, что (o==null ? e==null : o.equals(e)), если этот набор содержит такой элемент. Возвращает true если этот набор содержал элемент (или, что эквивалентно, если этот набор изменился в результате вызова). (Этот набор не будет содержать элемент после возвращения вызова.)

Указано в:

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

Параметры:

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

Возвращает:

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

Исключения:

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

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

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

containsAll

boolean containsAll(Collection<?> c)

Возвращает true если этот набор содержит все элементы указанной коллекции. Если указанная коллекция также является набором, этот метод возвращает true если она является *подмножеством* этого набора.

Указано в:

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

Параметры:

c - коллекция, которую нужно проверить на включение в этот набор

Возвращает:

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

Исключения:

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

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

См. также:

contains(Object)

addAll

boolean addAll(Collection<? extends E> c)

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

Указано в:

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

Параметры:

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

Возвращает:

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

Исключения:

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

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

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

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

См. также:

add(Object)

retainAll

boolean retainAll(Collection<?> c)

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

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

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

Параметры:

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

Возвращает:

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

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

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

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

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

См. также:

remove(Object)

removeAll

boolean removeAll(Collection<?> c)

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

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

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

Параметры:

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

Возвращает:

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

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

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

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

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

См. также:

remove(Object), contains(Object)

clear

void clear()

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

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

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

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

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

equals

boolean equals(Object o)

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

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

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

Переопределяет:

equals в классе Object

Параметры:

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

Возвращает:

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

См. также:

Object.hashCode(), HashMap

hashCode

int hashCode()

Возвращает значение хэш-кода для этого множества. Хэш-код множества определяется как сумма хэш-кодов элементов в множестве, где хэш-код элемента null определяется как ноль. Это гарантирует, что s1.equals(s2) подразумевает, что s1.hashCode()==s2.hashCode() для любых двух множеств s1 и s2, как требуется общим контрактом Object.hashCode().

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

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

Переопределяет:

hashCode в классе Object

Возвращает:

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

См. также:

Object.equals(Object), equals(Object)

spliterator

default Spliterator<E> spliterator()

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

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

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

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

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

Стандартная реализация создает итератор поздней привязки из Iterator множества. Итератор наследует свойства быстрого отказа итератора множества.

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

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

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

Возвращает:

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

С:

1.8