Класс Collections

public static final Set EMPTY_SET

Пустое множество (неизменяемое). Это множество сериализуемо.

public static final List EMPTY_LIST

Пустой список (неизменяемый). Этот список сериализуем.

public static final Map EMPTY_MAP

Пустая карта (неизменяемая). Эта карта сериализуема.

public static <T extends Comparable<? super T>> void sort(List<T> list)

Сортирует указанный список в порядке возрастания в соответствии с естественным порядком его элементов. Все элементы в списке должны реализовывать интерфейс Comparable. Кроме того, все элементы в списке должны быть взаимно сравнимы (то есть, e1.compareTo(e2) не должен вызывать ClassCastException для любых элементов e1 и e2 в списке).

Эта сортировка гарантированно стабильна: равные элементы не будут переупорядочены в результате сортировки.

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

public static <T> void sort(List<T> list, Comparator<? super T> c)

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

Эта сортировка гарантированно стабильна: равные элементы не будут переупорядочены в результате сортировки.

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

public static <T> int binarySearch(List<? extends Comparable<? super T>> list, T key)

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

Этот метод работает за время log(n) для списка с «случайным доступом» (который предоставляет доступ к позиции почти за постоянное время). Если указанный список не реализует интерфейс RandomAccess и имеет большой размер, этот метод выполнит двоичный поиск на основе итератора, который выполнит O(n) обходов ссылок и O(log n) сравнений элементов.

public static <T> int binarySearch(List<? extends T> list, T key, Comparator<? super T> c)

Ищет указанный объект в заданном списке с использованием алгоритма двоичного поиска. Список должен быть отсортирован в порядке возрастания в соответствии с указанным компаратором (как методом sort(List, Comparator)) перед вызовом этого метода. Если он не отсортирован, результаты неопределенны. Если список содержит несколько элементов, равных указанному объекту, нет гарантии, какой из них будет найден.

Этот метод работает за время log(n) для списка с «случайным доступом» (который предоставляет доступ к позиции почти за постоянное время). Если указанный список не реализует интерфейс RandomAccess и имеет большой размер, этот метод выполнит двоичный поиск на основе итератора, который выполнит O(n) обходов ссылок и O(log n) сравнений элементов.

public static void reverse(List<?> list)

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

Этот метод работает за линейное время.

public static void shuffle(List<?> list)

Случайно переупорядочивает указанный список, используя стандартный источник случайности. Все перестановки происходят с приблизительно равной вероятностью.

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

Это реализация проходит по списку в обратном порядке, от последнего элемента до второго, многократно переставляя случайным образом выбранный элемент в «текущую позицию». Элементы случайным образом выбираются из части списка, которая начинается с первого элемента и заканчивается текущей позицией включительно.

public static void shuffle(List<?> list, Random rnd)

Случайно переупорядочивает указанный список, используя указанный источник случайности.

Этот метод эквивалентен shuffle(List, RandomGenerator) и существует для обратной совместимости. Метод shuffle(List, RandomGenerator) предпочтительнее, так как он не ограничен генераторами случайных чисел, которые расширяют класс Random.

public static void shuffle(List<?> list, RandomGenerator rnd)

Случайно переупорядочивает указанный список, используя указанный источник случайности. Все перестановки происходят с равной вероятностью, если источник случайности честный.

Эта реализация проходит по списку в обратном порядке, от последнего элемента до второго, многократно переставляя случайным образом выбранный элемент в «текущую позицию». Элементы случайным образом выбираются из части списка, которая начинается с первого элемента и заканчивается текущей позицией включительно.

public static void swap(List<?> list, int i, int j)

Меняет местами элементы в указанном списке по указанным позициям. (Если указанные позиции равны, вызов этого метода не изменяет список.)

public static <T> void fill(List<? super T> list, T obj)

Заменяет все элементы в указанном списке заданным элементом.

Этот метод работает за линейное время.

public static <T> void copy(List<? super T> dest, List<? extends T> src)

Копирует все элементы из одного списка в другой. После операции индекс каждого скопированного элемента в целевом списке будет совпадать с его индексом в исходном списке. Размер целевого списка должен быть больше или равен размеру исходного списка. Если он больше, оставшиеся элементы в целевом списке не затрагиваются.

Этот метод работает за линейное время.

public static <T extends Object & Comparable<? super T>> T min(Collection<? extends T> coll)

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

Этот метод проходит по всему набору, поэтому он требует времени, пропорционального размеру набора.

public static <T> T min(Collection<? extends T> coll, Comparator<? super T> comp)

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

Этот метод проходит по всему набору, поэтому он требует времени, пропорционального размеру набора.

public static <T extends Object & Comparable<? super T>> T max(Collection<? extends T> coll)

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

Этот метод проходит по всему набору, поэтому он требует времени, пропорционального размеру набора.

public static <T> T max(Collection<? extends T> coll, Comparator<? super T> comp)

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

Этот метод итерируется по всему набору, поэтому он требует времени, пропорционального размеру набора.

public static void rotate(List<?> list, int distance)

Поворачивает элементы в указанном списке на указанное расстояние. После вызова этого метода, элемент с индексом i будет элементом, который ранее находился по индексу (i - distance) mod list.size(), для всех значений i между 0 и list.size()-1 включительно. (Этот метод не влияет на размер списка.)

Например, предположим, что list содержит [t, a, n, k, s]. После вызова Collections.rotate(list, 1) (или Collections.rotate(list, -4)), list будет содержать [s, t, a, n, k].

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

     Collections.rotate(list.subList(j, k+1), -1);
 

Чтобы сделать это конкретным, предположим, что list содержит [a, b, c, d, e]. Чтобы переместить элемент с индексом 1 (b) вперёд на две позиции, выполните следующий вызов:

     Collections.rotate(l.subList(1, 4), -1);
 

Результирующий список – [a, c, d, b, e].

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

Если указанный список небольшой или реализует интерфейс RandomAccess, эта реализация обменивает первый элемент на место, куда он должен перейти, а затем повторяет обмен перемещённого элемента на место, куда он должен перейти, пока перемещённый элемент не будет обменян на первый элемент. При необходимости процесс повторяется для второго и последующих элементов, пока поворот не будет завершён. Если указанный список большой и не реализует интерфейс RandomAccess, эта реализация разбивает список на два подсписка вокруг индекса -distance mod size. Затем метод reverse(List) вызывается для каждого подсписка, и, наконец, для всего списка. Более полное описание обоих алгоритмов см. в разделе 2.3 книги Джона Бентли «Programming Pearls» (Addison-Wesley, 1986).

public static <T> boolean replaceAll(List<T> list, T oldVal, T newVal)

Заменяет все вхождения одного указанного значения в списке другим. Более формально, заменяет newVal каждый элемент e в list, таким образом, что (oldVal==null ? e==null : oldVal.equals(e)). (Этот метод не влияет на размер списка.)

public static int indexOfSubList(List<?> source, List<?> target)

Возвращает начальную позицию первого вхождения указанного целевого списка в указанном исходном списке, или -1, если такого вхождения нет. Более формально, возвращает наименьший индекс i, такой что source.subList(i, i+target.size()).equals(target), или -1, если такого индекса нет. (Возвращает -1, если target.size() > source.size())

Эта реализация использует «прямой» метод сканирования исходного списка, поиск соответствия с целевым списком в каждой позиции по очереди.

public static int lastIndexOfSubList(List<?> source, List<?> target)

Возвращает начальную позицию последнего вхождения указанного целевого списка в указанный исходный список, или -1, если такого вхождения нет. Более формально, возвращает наибольший индекс i, такой что source.subList(i, i+target.size()).equals(target), или -1, если такого индекса нет. (Возвращает -1, если target.size() > source.size())

Эта реализация использует «прямой» метод итерации по исходному списку, поиск соответствия с целевым списком в каждой позиции по очереди.

public static <T> Collection<T> unmodifiableCollection(Collection<? extends T> c)

Возвращает неизменяемый вид указанного набора. Операции запроса к возвращаемому набору «проходят через» к указанному набору, и попытки модифицировать возвращаемый набор, как непосредственно, так и через его итератор, приводят к UnsupportedOperationException.

Возвращаемый набор не передаёт операции hashCode и equals в подлежащий набор, а полагается на Object's equals и hashCode методы. Это необходимо, чтобы сохранить контракты этих операций в случае, если подлежащий набор является множеством или списком.

Возвращаемый набор будет сериализуемым, если указанный набор сериализуем.

public static <T> SequencedCollection<T> unmodifiableSequencedCollection(SequencedCollection<? extends T> c)

Возвращает неизменяемый вид указанного SequencedCollection. Операции запроса к возвращаемому набору «проходят через» к указанному набору, и попытки модифицировать возвращаемый набор, как непосредственно, так и через его итератор, приводят к UnsupportedOperationException.

Возвращаемый набор не передаёт операции hashCode и equals в подлежащий набор, а полагается на Object's equals и hashCode методы. Это необходимо, чтобы сохранить контракты этих операций в случае, если подлежащий набор является множеством или списком.

Возвращаемый набор будет сериализуемым, если указанный набор сериализуем.

public static <T> Set<T> unmodifiableSet(Set<? extends T> s)

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

Возвращаемый набор будет сериализуемым, если указанный набор сериализуем.

public static <T> SequencedSet<T> unmodifiableSequencedSet(SequencedSet<? extends T> s)

Возвращает неизменяемый вид указанного SequencedSet. Операции запроса к возвращаемому набору "считываются" из указанного набора, а попытки изменить возвращаемый набор, будь то непосредственно или через его итератор, приводят к UnsupportedOperationException.

Возвращаемый набор будет сериализуемым, если указанный набор сериализуем.

public static <T> SortedSet<T> unmodifiableSortedSet(SortedSet<T> s)

Возвращает неизменяемый вид указанного отсортированного набора. Операции запроса к возвращаемому отсортированному набору "считываются" из указанного отсортированного набора. Попытки изменить возвращаемый отсортированный набор, будь то непосредственно, через его итератор, или через его subSet, headSet или tailSet представления, приводят к UnsupportedOperationException.

Возвращаемый отсортированный набор будет сериализуемым, если указанный отсортированный набор сериализуем.

public static <T> NavigableSet<T> unmodifiableNavigableSet(NavigableSet<T> s)

Возвращает неизменяемый вид указанного навигационного набора. Операции запроса к возвращаемому навигационному набору "считываются" из указанного навигационного набора. Попытки изменить возвращаемый навигационный набор, будь то непосредственно, через его итератор, или через его subSet, headSet или tailSet представления, приводят к UnsupportedOperationException.

Возвращаемый навигационный набор будет сериализуемым, если указанный навигационный набор сериализуем.

public static <T> List<T> unmodifiableList(List<? extends T> list)

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

Возвращаемый список будет сериализуемым, если указанный список сериализуем. Аналогично, возвращаемый список будет реализовывать RandomAccess, если указанный список это делает.

public static <K, V> Map<K,V> unmodifiableMap(Map<? extends K,? extends V> m)

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

Возвращаемая карта будет сериализуемой, если указанная карта сериализуема.

public static <K, V> SequencedMap<K,V> unmodifiableSequencedMap(SequencedMap<? extends K,? extends V> m)

Возвращает неизменяемый вид указанной SequencedMap. Операции запроса к возвращаемой карте "считываются" из указанной карты, а попытки изменить возвращаемую карту, будь то непосредственно или через ее коллекции-представления, приводят к UnsupportedOperationException.

Возвращаемая карта будет сериализуемой, если указанная карта сериализуема.

public static <K, V> SortedMap<K,V> unmodifiableSortedMap(SortedMap<K,? extends V> m)

Возвращает неизменяемый вид указанной отсортированной карты. Операции запроса к возвращаемой отсортированной карте "считываются" из указанной отсортированной карты. Попытки изменить возвращаемую отсортированную карту, будь то непосредственно, через ее коллекции-представления, или через ее subMap, headMap или tailMap представления, приводят к UnsupportedOperationException.

Возвращаемая отсортированная карта будет сериализуемой, если указанная отсортированная карта сериализуема.

public static <K, V> NavigableMap<K,V> unmodifiableNavigableMap(NavigableMap<K,? extends V> m)

Возвращает неизменяемый вид указанной навигационной карты. Операции запроса к возвращаемой навигационной карте "считываются" из указанной навигационной карты. Попытки изменить возвращаемую навигационную карту, будь то непосредственно, через ее коллекции-представления, или через ее subMap, headMap или tailMap представления, приводят к UnsupportedOperationException.

Возвращаемая навигационная карта будет сериализуемой, если указанная навигационная карта сериализуема.

public static <T> Collection<T> synchronizedCollection(Collection<T> c)

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

Необходимо, чтобы пользователь вручную синхронизировался на возвращаемой коллекции при прохождении по ней с помощью Iterator, Spliterator или Stream:

  Collection c = Collections.synchronizedCollection(myCollection);
     ...
  synchronized (c) {
      Iterator i = c.iterator(); // Must be in the synchronized block
      while (i.hasNext())
         foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемая коллекция не пропускает операции hashCode и equals через базовую коллекцию, а полагается на методы equals и hashCode коллекции Object. Это необходимо для сохранения контрактов этих операций в случае, если базовая коллекция является множеством или списком.

Возвращаемая коллекция будет сериализуемой, если указанная коллекция сериализуема.

public static <T> Set<T> synchronizedSet(Set<T> s)

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

Необходимо вручную синхронизировать на возвращённом наборе при его обходе с помощью Iterator, Spliterator или Stream:

  Set s = Collections.synchronizedSet(new HashSet());
      ...
  synchronized (s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемый набор будет сериализуемым, если указанный набор является сериализуемым.

public static <T> SortedSet<T> synchronizedSortedSet(SortedSet<T> s)

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

Необходимо вручную синхронизировать на возвращённом отсортированном наборе при его обходе или любых его subSet, headSet, или tailSet представлениях с помощью Iterator, Spliterator или Stream:

  SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
      ...
  synchronized (s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

или:

  SortedSet s = Collections.synchronizedSortedSet(new TreeSet());
  SortedSet s2 = s.headSet(foo);
      ...
  synchronized (s) {  // Note: s, not s2!!!
      Iterator i = s2.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемый отсортированный набор будет сериализуемым, если указанный отсортированный набор является сериализуемым.

public static <T> NavigableSet<T> synchronizedNavigableSet(NavigableSet<T> s)

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

Необходимо вручную синхронизировать на возвращённом навигационном наборе при его обходе или любых его subSet, headSet, или tailSet представлениях с помощью Iterator, Spliterator или Stream:

  NavigableSet s = Collections.synchronizedNavigableSet(new TreeSet());
      ...
  synchronized (s) {
      Iterator i = s.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

или:

  NavigableSet s = Collections.synchronizedNavigableSet(new TreeSet());
  NavigableSet s2 = s.headSet(foo, true);
      ...
  synchronized (s) {  // Note: s, not s2!!!
      Iterator i = s2.iterator(); // Must be in the synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

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

public static <T> List<T> synchronizedList(List<T> list)

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

Необходимо вручную синхронизировать на возвращённом списке при его обходе с помощью Iterator, Spliterator или Stream:

  List list = Collections.synchronizedList(new ArrayList());
      ...
  synchronized (list) {
      Iterator i = list.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

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

public static <K, V> Map<K,V> synchronizedMap(Map<K,V> m)

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

Необходимо вручную синхронизировать на возвращённой карте при обходе любого из её представлений коллекций с помощью Iterator, Spliterator или Stream:

  Map m = Collections.synchronizedMap(new HashMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемая карта будет сериализуемой, если указанная карта является сериализуемой.

public static <K, V> SortedMap<K,V> synchronizedSortedMap(SortedMap<K,V> m)

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

Необходимо вручную синхронизировать на возвращённой отсортированной карте при обходе любых её представлений коллекций, или коллекций представлений любых её subMap, headMap или tailMap представлений, с помощью Iterator, Spliterator или Stream:

  SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

или:

  SortedMap m = Collections.synchronizedSortedMap(new TreeMap());
  SortedMap m2 = m.subMap(foo, bar);
      ...
  Set s2 = m2.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not m2 or s2!
      Iterator i = s2.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемая отсортированная карта будет сериализуемой, если указанная отсортированная карта является сериализуемой.

public static <K, V> NavigableMap<K,V> synchronizedNavigableMap(NavigableMap<K,V> m)

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

Необходимо вручную синхронизировать на возвращённой навигационной карте при обходе любых её представлений коллекций, или коллекций представлений любых её subMap, headMap или tailMap представлений, с помощью Iterator, Spliterator или Stream:

  NavigableMap m = Collections.synchronizedNavigableMap(new TreeMap());
      ...
  Set s = m.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not s!
      Iterator i = s.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

или:

  NavigableMap m = Collections.synchronizedNavigableMap(new TreeMap());
  NavigableMap m2 = m.subMap(foo, true, bar, false);
      ...
  Set s2 = m2.keySet();  // Needn't be in synchronized block
      ...
  synchronized (m) {  // Synchronizing on m, not m2 or s2!
      Iterator i = s2.iterator(); // Must be in synchronized block
      while (i.hasNext())
          foo(i.next());
  }
 

Несоблюдение этого совета может привести к непредсказуемому поведению.

Возвращаемая навигационная карта будет сериализуемой, если указанная навигационная карта является сериализуемой.

public static <E> Collection<E> checkedCollection(Collection<E> c, Class<E> type)

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

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

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

 
     Collection<String> c = new HashSet<>();
 

может быть временно заменено этим:

 
     Collection<String> c = Collections.checkedCollection(
         new HashSet<>(), String.class);
 

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

Возвращаемый набор не передает операции hashCode и equals в базовый набор, но полагается на методы Object's equals и hashCode. Это необходимо для сохранения контрактов этих операций в случае, если базовый набор является множеством или списком.

Возвращаемый набор будет сериализуемым, если указанный набор является сериализуемым.

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

public static <E> Queue<E> checkedQueue(Queue<E> queue, Class<E> type)

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

Описание использования динамически типизированных представлений можно найти в документации к методу checkedCollection.

Возвращаемая очередь будет сериализуемой, если указанная очередь сериализуема.

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

public static <E> Set<E> checkedSet(Set<E> s, Class<E> type)

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

Описание использования динамически типизированных представлений можно найти в документации к методу checkedCollection.

Возвращаемое множество будет сериализуемым, если указанное множество сериализуемо.

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

public static <E> SortedSet<E> checkedSortedSet(SortedSet<E> s, Class<E> type)

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

Описание использования динамически типизированных представлений можно найти в документации к методу checkedCollection.

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

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

public static <E> NavigableSet<E> checkedNavigableSet(NavigableSet<E> s, Class<E> type)

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

Описание использования динамически типизированных представлений можно найти в документации к методу checkedCollection.

Возвращаемое навигационное множество будет сериализуемым, если указанное навигационное множество сериализуемо.

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

public static <E> List<E> checkedList(List<E> list, Class<E> type)

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

Описание использования динамически типизированных представлений можно найти в документации к методу checkedCollection.

Возвращаемый список будет сериализуемым, если указанный список сериализуем.

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

public static <K, V> Map<K,V> checkedMap(Map<K,V> m, Class<K> keyType, Class<V> valueType)

Возвращает динамически типизированный вид указанной карты. Любая попытка вставить отображение, ключ или значение которого имеют неправильный тип, приведёт к немедленному ClassCastException. Аналогично, любая попытка изменить значение, в настоящее время связанное с ключом, приведёт к немедленному ClassCastException, независимо от того, осуществляется ли изменение непосредственно через саму карту или через экземпляр Map.Entry, полученный из представления entry set карты.

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

Обсуждение использования динамически типизированных представлений можно найти в документации для метода checkedCollection.

Возвращаемая карта будет сериализуемой, если указанная карта является сериализуемой.

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

public static <K, V> SortedMap<K,V> checkedSortedMap(SortedMap<K,V> m, Class<K> keyType, Class<V> valueType)

Возвращает динамически типизированный вид указанного отсортированного отображения. Любая попытка вставить отображение, ключ или значение которого имеют неправильный тип, приведёт к немедленному ClassCastException. Аналогично, любая попытка изменить значение, в настоящее время связанное с ключом, приведёт к немедленному ClassCastException, независимо от того, осуществляется ли изменение непосредственно через саму карту или через экземпляр Map.Entry, полученный из представления entry set карты.

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

Обсуждение использования динамически типизированных представлений можно найти в документации для метода checkedCollection.

Возвращаемая карта будет сериализуемой, если указанная карта является сериализуемой.

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

public static <K, V> NavigableMap<K,V> checkedNavigableMap(NavigableMap<K,V> m, Class<K> keyType, Class<V> valueType)

Возвращает динамически типизированный вид указанного отображения с навигацией. Любая попытка вставить отображение, ключ или значение которого имеют неправильный тип, приведёт к немедленному ClassCastException. Аналогично, любая попытка изменить значение, в настоящее время связанное с ключом, приведёт к немедленному ClassCastException, независимо от того, осуществляется ли изменение непосредственно через саму карту или через экземпляр Map.Entry, полученный из представления entry set карты.

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

Обсуждение использования динамически типизированных представлений можно найти в документации для метода checkedCollection.

Возвращаемая карта будет сериализуемой, если указанная карта является сериализуемой.

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

public static <T> Iterator<T> emptyIterator()

Возвращает итератор, не имеющий элементов. Более точно:

• hasNext всегда возвращает false.
• next всегда выбрасывает NoSuchElementException.
• remove всегда выбрасывает IllegalStateException.

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

public static <T> ListIterator<T> emptyListIterator()

Возвращает список итератор, не имеющий элементов. Более точно:

• hasNext и hasPrevious всегда возвращают false.
• next и previous всегда выбрасывают NoSuchElementException.
• remove и set всегда выбрасывают IllegalStateException.
• add всегда выбрасывает UnsupportedOperationException.
• nextIndex всегда возвращает 0.
• previousIndex всегда возвращает -1.

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

public static <T> Enumeration<T> emptyEnumeration()

Возвращает перечисление, не имеющее элементов. Более точно:

• hasMoreElements всегда возвращает false.
• nextElement всегда выбрасывает NoSuchElementException.

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

public static final <T> Set<T> emptySet()

Возвращает пустое множество (неизменяемое). Это множество сериализуемо. В отличие от одноимённого поля, этот метод параметризован.

Этот пример демонстрирует безопасный с точки зрения типов способ получения пустого множества:

     Set<String> s = Collections.emptySet();
 

public static <E> SortedSet<E> emptySortedSet()

Возвращает пустое упорядоченное множество (неизменяемое). Это множество сериализуемо.

Этот пример иллюстрирует безопасный способ получения пустого упорядоченного множества:

 
     SortedSet<String> s = Collections.emptySortedSet();
 

public static <E> NavigableSet<E> emptyNavigableSet()

Возвращает пустое навигационное множество (неизменяемое). Это множество сериализуемо.

Этот пример иллюстрирует безопасный способ получения пустого навигационного множества:

 
     NavigableSet<String> s = Collections.emptyNavigableSet();
 

public static final <T> List<T> emptyList()

Возвращает пустой список (неизменяемый). Этот список сериализуем.

Этот пример иллюстрирует безопасный способ получения пустого списка:

     List<String> s = Collections.emptyList();
 

public static final <K, V> Map<K,V> emptyMap()

Возвращает пустой словарь (неизменяемый). Этот словарь сериализуем.

Этот пример иллюстрирует безопасный способ получения пустого словаря:

     Map<String, Date> s = Collections.emptyMap();
 

public static final <K, V> SortedMap<K,V> emptySortedMap()

Возвращает пустой упорядоченный словарь (неизменяемый). Этот словарь сериализуем.

Этот пример иллюстрирует безопасный способ получения пустого словаря:

 
     SortedMap<String, Date> s = Collections.emptySortedMap();
 

public static final <K, V> NavigableMap<K,V> emptyNavigableMap()

Возвращает пустой навигационный словарь (неизменяемый). Этот словарь сериализуем.

Этот пример иллюстрирует безопасный способ получения пустого словаря:

 
     NavigableMap<String, Date> s = Collections.emptyNavigableMap();
 

public static <T> Set<T> singleton(T o)

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

public static <T> List<T> singletonList(T o)

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

public static <K, V> Map<K,V> singletonMap(K key, V value)

Возвращает неизменяемый словарь, сопоставляющий только указанный ключ со значением. Возвращаемый словарь сериализуем.

public static <T> List<T> nCopies(int n, T o)

Возвращает неизменяемый список, состоящий из n копий указанного объекта. Новый выделенный объект данных является очень маленьким (он содержит единственную ссылку на объект данных). Этот метод полезен в сочетании с методом List.addAll для увеличения списков. Возвращаемый список сериализуем.

public static <T> Comparator<T> reverseOrder()

Возвращает компаратор, который накладывает обратный порядок естественного порядка на коллекцию объектов, реализующих интерфейс Comparable. (Естественный порядок — порядок, налагаемый собственным методом compareTo объектов.) Это позволяет использовать простой подход для сортировки (или поддержания) коллекций (или массивов) объектов, реализующих интерфейс Comparable в обратном естественном порядке. Например, предположим, что a — это массив строк. Тогда:

          Arrays.sort(a, Collections.reverseOrder());
 

сортирует массив в обратном лексикографическом (алфавитном) порядке.

Возвращаемый компаратор сериализуем.

public static <T> Comparator<T> reverseOrder(Comparator<T> cmp)

Возвращает компаратор, который накладывает обратный порядок, заданный указанным компаратором. Если указанный компаратор является null, этот метод эквивалентен методу reverseOrder() (то есть он возвращает компаратор, который накладывает обратный естественный порядок на коллекцию объектов, реализующих интерфейс Comparable).

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

public static <T> Enumeration<T> enumeration(Collection<T> c)

Возвращает перечисление над указанной коллекцией. Это обеспечивает межпрограммную совместимость со старыми API, которые требуют перечисления в качестве входных данных.

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

public static <T> ArrayList<T> list(Enumeration<T> e)

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

public static int frequency(Collection<?> c, Object o)

Возвращает количество элементов в указанной коллекции, равных указанному объекту. Более формально, возвращает количество элементов e в коллекции, таких что Objects.equals(o, e).

public static boolean disjoint(Collection<?> c1, Collection<?> c2)

Возвращает true, если две указанные коллекции не имеют общих элементов.

Следует соблюдать осторожность, если этот метод используется для коллекций, которые не соответствуют общему контракту для Collection. Реализации могут выбрать итерацию по любой коллекции и проверку на включение в другую коллекцию (или выполнить любое эквивалентное вычисление). Если одна из коллекций использует нестандартный тест равенства (как в случае с SortedSet, порядок которого не совместим с equals, или набором ключей IdentityHashMap), обе коллекции должны использовать один и тот же нестандартный тест равенства, иначе результат этого метода неопределен.

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

Обратите внимание, что разрешается передать одну и ту же коллекцию в обоих параметрах, в этом случае метод вернет true только в том случае, если коллекция пуста.

@SafeVarargs public static <T> boolean addAll(Collection<? super T> c, T... elements)

Добавляет все указанные элементы в указанную коллекцию. Добавляемые элементы могут быть указаны индивидуально или в виде массива. Поведение этого вспомогательного метода аналогично поведению c.addAll(Collections.unmodifiableList(Arrays.asList(elements))).

Когда элементы указаны индивидуально, этот метод предоставляет удобный способ добавления нескольких элементов в существующую коллекцию:

     Collections.addAll(flavors, "Peaches 'n Plutonium", "Rocky Racoon");
 

public static <E> Set<E> newSetFromMap(Map<E,Boolean> map)

Возвращает набор, поддерживаемый указанной картой. Результирующий набор отображает те же характеристики упорядочения, одновременного доступа и производительности, что и поддерживающая карта. По сути, этот фабричный метод предоставляет реализацию Set, соответствующую любой реализации Map. Нет необходимости использовать этот метод для реализации Map, которая уже имеет соответствующую реализацию Set (например, HashMap или TreeMap).

Каждый вызов метода для набора, возвращаемого этим методом, приводит к точно одному вызову метода для поддерживающей карты или ее представления keySet, за исключением одного случая. Метод addAll реализуется как последовательность вызовов put для поддерживающей карты.

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

    Set<Object> weakHashSet = Collections.newSetFromMap(
        new WeakHashMap<Object, Boolean>());
 

public static <E> SequencedSet<E> newSequencedSetFromMap(SequencedMap<E,Boolean> map)

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

Каждый вызов метода для набора, возвращаемого этим методом, приводит к точно одному вызову метода для поддерживающей карты или ее представления keySet, за исключением одного случая. Метод addAll реализуется как последовательность вызовов put для поддерживающей карты.

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

public static <T> Queue<T> asLifoQueue(Deque<T> deque)

Возвращает представление Deque как очереди «последним вошел — первым вышел» (LIFO). Метод add сопоставлен с push, метод remove сопоставлен с pop и так далее. Это представление может быть полезно, когда вам нужен метод, требующий Queue, но вам нужна очередность LIFO.

Каждый вызов метода в очереди, возвращаемой этим методом, приводит к ровно одному вызову метода на основе подлежащего дека, за одним исключением. Метод addAll реализуется как последовательность вызовов addFirst на подлежащем дека.