Интерфейс SortedMap<K,V>

public interface SortedMap<K,V>
extends Map<K,V>

A Map который дополнительно предоставляет полный порядок по своим ключам. Отображение упорядочено в соответствии с естественным порядком своих ключей или по Comparator, обычно предоставляемому во время создания отсортированного отображения. Этот порядок отражается при итерации по коллекционным представлениям отсортированного отображения (возвращаемым методами entrySet, keySet и values). Предоставлено несколько дополнительных операций для использования порядка. (Этот интерфейс является аналогом отображения SortedSet.)

Все ключи, вставленные в отсортированное отображение, должны реализовывать интерфейс Comparable (или быть принятыми указанным компаратором). Кроме того, все такие ключи должны быть взаимно сравнимы: k1.compareTo(k2) (или comparator.compare(k1, k2)) не должно выбрасывать ClassCastException для любых ключей k1 и k2 в отсортированном отображении. Попытки нарушения этого ограничения приведут к тому, что вызов метода или конструктора, нарушившего ограничение, выбросит ClassCastException.

Обратите внимание, что порядок, поддерживаемый отсортированным отображением (с предоставленным или без явного компаратора), должен быть совместим с equals, если отсортированное отображение должно правильно реализовывать интерфейс Map. (См. интерфейс Comparable или интерфейс Comparator для точного определения совместимости с equals.) Это так, потому что интерфейс Map определен в терминах операции equals, но отсортированное отображение выполняет все сравнения ключей с помощью метода compareTo (или compare), поэтому два ключа, которые считаются равными этим методом, с точки зрения отсортированного отображения, равны. Поведение отображения дерева определено даже если его порядок несовместим с equals; оно просто не подчиняется общему контракту интерфейса Map.

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

1. Конструктор без аргументов, который создает пустое отсортированное отображение, отсортированное в соответствии с естественным порядком его ключей.
2. Конструктор с одним аргументом типа Comparator, который создает пустое отсортированное отображение, отсортированное в соответствии с указанным компаратором.
3. Конструктор с одним аргументом типа Map, который создает новое отображение с теми же отображениями ключ-значение, что и его аргумент, отсортированное в соответствии с естественным порядком ключей.
4. Конструктор с одним аргументом типа SortedMap, который создает новое отсортированное отображение с теми же отображениями ключ-значение и тем же порядком, что и входное отсортированное отображение.

Примечание: несколько методов возвращают подотображения с ограниченными диапазонами ключей. Такие диапазоны полуоткрытые, то есть они включают свою нижнюю границу, но не верхнюю (если применимо). Если вам нужен закрытый диапазон (который включает обе границы), и тип ключа позволяет вычислить преемника заданного ключа, просто запросите поддиапазон от lowEndpoint до successor(highEndpoint). Например, предположим, что m — это отображение, ключи которого — строки. Следующий идиоматический фрагмент получает представление, содержащее все отображения ключ-значение в m, ключи которых находятся между low и high, включительно:

SortedMap<String, V> sub = m.subMap(low, high+"\0");

Аналогичная техника может использоваться для генерации открытого диапазона (который не содержит ни одной границы). Следующий идиоматический фрагмент получает представление, содержащее все отображения ключ-значение в m, ключи которых находятся между low и high, исключая эти значения:

SortedMap<String, V> sub = m.subMap(low+"\0", high);

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

Методы

comparator

Comparator<? super K> comparator()

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

Возвращает:

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

subMap

SortedMap<K,V> subMap(K fromKey,
                      K toKey)

Параметры:

fromKey - нижняя граница (включительно) ключей в возвращаемом отображении

toKey - верхняя граница (не включительно) ключей в возвращаемом отображении

Возвращает:

представление части этого отображения, ключи которого находятся в диапазоне от fromKey, включительно, до toKey, не включительно

Исключение:

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

NullPointerException - если fromKey или toKey равно null, а это отображение не допускает null-ключей

IllegalArgumentException - если fromKey больше, чем toKey; или если у этого отображения ограниченный диапазон, и fromKey или toKey выходят за пределы границ диапазона

headMap

SortedMap<K,V> headMap(K toKey)

Параметры:

toKey - верхняя граница (не включительно) ключей в возвращаемом отображении

Возвращает:

представление части этого отображения, ключи которого строго меньше toKey

Исключение:

ClassCastException - если toKey несовместим с компаратором этого отображения (или, если у отображения нет компаратора, если toKey не реализует Comparable). Реализации могут, но не обязаны, выбрасывать это исключение, если toKey не может быть сравнен с ключами, которые есть в отображении.

NullPointerException - если toKey равно null, а это отображение не допускает null-ключей

IllegalArgumentException - если у этого отображения ограниченный диапазон, и toKey выходят за пределы границ диапазона

tailMap

SortedMap<K,V> tailMap(K fromKey)

Параметры:

fromKey - нижняя граница (включительно) ключей в возвращаемом отображении

Возвращает:

представление части этого отображения, ключи которого больше или равны fromKey

Исключение:

ClassCastException - если fromKey несовместим с компаратором этого отображения (или, если у отображения нет компаратора, если fromKey не реализует Comparable). Реализации могут, но не обязаны, выбрасывать это исключение, если fromKey не может быть сравнен с ключами, которые есть в отображении.

NullPointerException - если fromKey равно null, а это отображение не допускает null-ключей

IllegalArgumentException - если у этого отображения ограниченный диапазон, и fromKey выходят за пределы границ диапазона

firstKey

K firstKey()

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

Возвращает:

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

Исключение:

NoSuchElementException - если это отображение пустое

lastKey

K lastKey()

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

Возвращает:

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

Исключение:

NoSuchElementException - если это отображение пустое

keySet

Set<K> keySet()

Возвращает вид Set ключей, содержащихся в этом отображении. Итератор набора возвращает ключи в возрастающем порядке. Набор поддерживается отображением, поэтому изменения в отображении отражаются в наборе и наоборот. Если отображение изменяется во время итерации по набору (кроме операции самого итератора remove), результаты итерации не определены. Набор поддерживает удаление элементов, что удаляет соответствующее отображение из отображения, через операции Iterator.remove, Set.remove, removeAll, retainAll, и clear. Он не поддерживает операции add или addAll.

Задано в:

keySet в интерфейсе Map<K,V>

Возвращает:

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

values

Collection<V> values()

Возвращает вид Collection значений, содержащихся в этом отображении. Итератор коллекции возвращает значения в возрастающем порядке соответствующих ключей. Коллекция поддерживается отображением, поэтому изменения в отображении отражаются в коллекции и наоборот. Если отображение изменяется во время итерации по коллекции (кроме операции самого итератора remove), результаты итерации не определены. Коллекция поддерживает удаление элементов, что удаляет соответствующее отображение из отображения, через операции Iterator.remove, Collection.remove, removeAll, retainAll и clear. Она не поддерживает операции add или addAll.

Задано в:

values в интерфейсе Map<K,V>

Возвращает:

вид коллекции значений, содержащихся в этом отображении, отсортированных в порядке возрастания ключей

entrySet

Set<Map.Entry<K,V>> entrySet()

Возвращает Set представление сопоставлений, содержащихся в этом отображении. Итератор набора возвращает записи в порядке возрастания ключей. Набор поддерживается отображением, поэтому изменения в отображении отражаются в наборе и наоборот. Если отображение изменяется во время итерации по набору (кроме операции самого итератора remove, или через операцию setValue на записи отображения, возвращенной итератором), результаты итерации не определены. Набор поддерживает удаление элементов, что удаляет соответствующее отображение из отображения, через операции Iterator.remove, Set.remove, removeAll, retainAll и clear. Он не поддерживает операции add или addAll.

Задано в:

entrySet в интерфейсе Map<K,V>

Возвращает:

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