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

Параметры типа:: K — тип ключей, хранящихся в этой карте; V — тип отображаемых значений

Все суперинтерфейсы:: Map<K,V>, SequencedMap<K,V>, SortedMap<K,V>

Все известные подынтерфейсы:: ConcurrentNavigableMap<K,V>

Все известные реализующие классы:: ConcurrentSkipListMap, TreeMap

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

Интерфейс SortedMap, расширенный методами навигации, возвращающими наиболее близкие совпадения для заданных целей поиска. Методы lowerEntry(K), floorEntry(K), ceilingEntry(K) и higherEntry(K) возвращают объекты Map.Entry, связанные с ключами, соответственно меньшими, меньшими или равными, большими или равными и большими заданного ключа; если такого ключа нет, возвращается null. Аналогично методы lowerKey(K), floorKey(K), ceilingKey(K) и higherKey(K) возвращают только соответствующие ключи. Все эти методы предназначены для поиска записей, а не для их перебора.

Доступ к NavigableMap и её обход возможны как в порядке возрастания, так и в порядке убывания ключей. Метод descendingMap() возвращает представление карты, в котором смысл всех методов отношений и направления обхода инвертирован. Производительность операций и представлений для обхода в порядке возрастания, вероятно, выше, чем для обхода в порядке убывания. Методы subMap(K, boolean, K, boolean), headMap(K, boolean) и tailMap(K, boolean) отличаются от одноимённых методов SortedMap тем, что принимают дополнительные аргументы, определяющие, включаются ли нижняя и верхняя границы или исключаются. Подкарты любой NavigableMap должны реализовывать интерфейс NavigableMap.

Этот интерфейс также определяет методы firstEntry(), pollFirstEntry(), lastEntry() и pollLastEntry(), которые возвращают и/или удаляют наименьшее и наибольшее отображения, если они существуют; в противном случае возвращается null.

Методы ceilingEntry(K), firstEntry(), floorEntry(K), higherEntry(K), lastEntry(), lowerEntry(K), pollFirstEntry() и pollLastEntry() возвращают экземпляры Map.Entry, представляющие снимки отображений на момент вызова. Они не поддерживают изменение базовой карты с помощью необязательного метода setValue.

Методы subMap(K, K), headMap(K) и tailMap(K) объявлены возвращающими SortedMap, чтобы существующие реализации SortedMap можно было без нарушения совместимости дополнительно адаптировать для реализации NavigableMap; однако расширения и реализации этого интерфейса рекомендуется переопределять эти методы так, чтобы они возвращали NavigableMap. Аналогично, метод SortedMap.keySet() можно переопределить, чтобы он возвращал NavigableSet.

Этот интерфейс входит в состав Java Collections Framework.

Начиная с версии:: 1.6

Краткое описание вложенных классов

Вложенные классы и интерфейсы, объявленные в интерфейсе Map

Map.Entry<K,V>

Модификатор и тип	Интерфейс	Описание
`static interface`	`Map.Entry<K,V>`	Запись карты (пара ключ-значение).

Краткое описание методов

Модификатор и тип	Метод	Описание
`Map.Entry<K,V>`	`ceilingEntry(K key)`	Возвращает отображение ключ-значение, связанное с наименьшим ключом, большим или равным заданному, либо `null`, если такого ключа нет.
`K`	`ceilingKey(K key)`	Возвращает наименьший ключ, больший или равный заданному, либо `null`, если такого ключа нет.
`NavigableSet<K>`	`descendingKeySet()`	Возвращает представление ключей, содержащихся в этой карте, в обратном порядке в виде `NavigableSet`.
`NavigableMap<K,V>`	`descendingMap()`	Возвращает представление отображений, содержащихся в этой карте, в обратном порядке.
`Map.Entry<K,V>`	`firstEntry()`	Возвращает отображение ключ-значение, связанное с наименьшим ключом в этой карте, либо `null`, если карта пуста.
`Map.Entry<K,V>`	`floorEntry(K key)`	Возвращает отображение ключ-значение, связанное с наибольшим ключом, меньшим или равным заданному, либо `null`, если такого ключа нет.
`K`	`floorKey(K key)`	Возвращает наибольший ключ, меньший или равный заданному, либо `null`, если такого ключа нет.
`SortedMap<K,V>`	`headMap(K toKey)`	Возвращает представление той части этой карты, ключи которой строго меньше `toKey`.
`NavigableMap<K,V>`	`headMap(K toKey, boolean inclusive)`	Возвращает представление той части этой карты, ключи которой меньше (или равны, если `inclusive` имеет значение true) `toKey`.
`Map.Entry<K,V>`	`higherEntry(K key)`	Возвращает отображение ключ-значение, связанное с наименьшим ключом, строго большим заданного, либо `null`, если такого ключа нет.
`K`	`higherKey(K key)`	Возвращает наименьший ключ, строго больший заданного, либо `null`, если такого ключа нет.
`Map.Entry<K,V>`	`lastEntry()`	Возвращает отображение ключ-значение, связанное с наибольшим ключом в этой карте, либо `null`, если карта пуста.
`Map.Entry<K,V>`	`lowerEntry(K key)`	Возвращает отображение ключ-значение, связанное с наибольшим ключом, строго меньшим заданного, либо `null`, если такого ключа нет.
`K`	`lowerKey(K key)`	Возвращает наибольший ключ, строго меньший заданного, либо `null`, если такого ключа нет.
`NavigableSet<K>`	`navigableKeySet()`	Возвращает представление ключей, содержащихся в этой карте, в виде `NavigableSet`.
`Map.Entry<K,V>`	`pollFirstEntry()`	Удаляет и возвращает отображение ключ-значение, связанное с наименьшим ключом в этой карте, либо `null`, если карта пуста (необязательная операция).
`Map.Entry<K,V>`	`pollLastEntry()`	Удаляет и возвращает отображение ключ-значение, связанное с наибольшим ключом в этой карте, либо `null`, если карта пуста (необязательная операция).
`default NavigableMap<K,V>`	`reversed()`	Возвращает представление этой карты в обратном порядке.
`NavigableMap<K,V>`	`subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)`	Возвращает представление той части этой карты, ключи которой находятся в диапазоне от `fromKey` до `toKey`.
`SortedMap<K,V>`	`subMap(K fromKey, K toKey)`	Возвращает представление той части этой карты, ключи которой находятся в диапазоне от `fromKey` включительно до `toKey` исключительно.
`SortedMap<K,V>`	`tailMap(K fromKey)`	Возвращает представление той части этой карты, ключи которой больше или равны `fromKey`.
`NavigableMap<K,V>`	`tailMap(K fromKey, boolean inclusive)`	Возвращает представление той части этой карты, ключи которой больше (или равны, если `inclusive` имеет значение true) `fromKey`.

Методы, объявленные в интерфейсе Map

clear, compute, computeIfAbsent, computeIfPresent, containsKey, containsValue, equals, forEach, get, getOrDefault, hashCode, isEmpty, merge, put, putAll, putIfAbsent, remove, remove, replace, replace, replaceAll, size

Модификатор и тип	Метод	Описание
`void`	`clear()`	Удаляет все отображения из этой карты (необязательная операция).
`default V`	`compute(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)`	Пытается вычислить отображение для указанного ключа и его текущего отображаемого значения либо `null`, если текущего отображения нет (необязательная операция).
`default V`	`computeIfAbsent(K key, Function<? super K, ? extends V> mappingFunction)`	Если указанный ключ ещё не связан со значением (или ему сопоставлено `null`), пытается вычислить его значение с помощью заданной функции отображения и добавляет его в эту карту, если результатом не является `null` (необязательная операция).
`default V`	`computeIfPresent(K key, BiFunction<? super K, ? super V, ? extends V> remappingFunction)`	Если для указанного ключа имеется ненулевое значение, пытается вычислить новое отображение на основе ключа и его текущего отображаемого значения (необязательная операция).
`boolean`	`containsKey(Object key)`	Возвращает `true`, если эта карта содержит отображение для указанного ключа.
`boolean`	`containsValue(Object value)`	Возвращает `true`, если в этой карте один или несколько ключей сопоставлены указанному значению.
`boolean`	`equals(Object o)`	Сравнивает указанный объект с этой картой на равенство.
`default void`	`forEach(BiConsumer<? super K, ? super V> action)`	Выполняет заданное действие для каждой записи в этой карте, пока не будут обработаны все записи или действие не вызовет исключение.
`V`	`get(Object key)`	Возвращает значение, сопоставленное указанному ключу, либо `null`, если в этой карте нет отображения для данного ключа.
`default V`	`getOrDefault(Object key, V defaultValue)`	Возвращает значение, сопоставленное указанному ключу, либо `defaultValue`, если в этой карте нет отображения для данного ключа.
`int`	`hashCode()`	Возвращает значение хеш-кода этой карты.
`boolean`	`isEmpty()`	Возвращает `true`, если эта карта не содержит отображений ключ-значение.
`default V`	`merge(K key, V value, BiFunction<? super V, ? super V, ? extends V> remappingFunction)`	Если указанный ключ ещё не связан со значением или связан со значением null, связывает его с заданным ненулевым значением (необязательная операция).
`V`	`put(K key, V value)`	Сопоставляет указанное значение указанному ключу в этой карте (необязательная операция).
`void`	`putAll(Map<? extends K, ? extends V> m)`	Копирует все отображения из указанной карты в эту карту (необязательная операция).
`default V`	`putIfAbsent(K key, V value)`	Если указанный ключ ещё не связан со значением (или ему сопоставлено `null`), связывает его с заданным значением и возвращает `null`; в противном случае возвращает текущее значение (необязательная операция).
`V`	`remove(Object key)`	Удаляет отображение ключа из этой карты, если оно существует (необязательная операция).
`default boolean`	`remove(Object key, Object value)`	Удаляет запись для указанного ключа, только если в данный момент ему сопоставлено указанное значение (необязательная операция).
`default V`	`replace(K key, V value)`	Заменяет запись для указанного ключа, только если в данный момент ему сопоставлено какое-либо значение (необязательная операция).
`default boolean`	`replace(K key, V oldValue, V newValue)`	Заменяет запись для указанного ключа, только если в данный момент ему сопоставлено указанное значение (необязательная операция).
`default void`	`replaceAll(BiFunction<? super K, ? super V, ? extends V> function)`	Заменяет значение каждой записи результатом вызова заданной функции для этой записи, пока не будут обработаны все записи или функция не вызовет исключение (необязательная операция).
`int`	`size()`	Возвращает количество отображений ключ-значение в этой карте.

Методы, объявленные в интерфейсе SequencedMap

sequencedEntrySet, sequencedKeySet, sequencedValues

Модификатор и тип	Метод	Описание
`default SequencedSet<Map.Entry<K,V>>`	`sequencedEntrySet()`	Возвращает представление `SequencedSet` набора `entrySet` этой карты.
`default SequencedSet<K>`	`sequencedKeySet()`	Возвращает представление `SequencedSet` набора `keySet` этой карты.
`default SequencedCollection<V>`	`sequencedValues()`	Возвращает представление `SequencedCollection` коллекции `values` этой карты.

Методы, объявленные в интерфейсе SortedMap

comparator, entrySet, firstKey, keySet, lastKey, putFirst, putLast, values

Модификатор и тип	Метод	Описание
`Comparator<? super K>`	`comparator()`	Возвращает компаратор, используемый для упорядочения ключей в этой карте, либо `null`, если карта использует естественный порядок ключей.
`Set<Map.Entry<K,V>>`	`entrySet()`	Возвращает представление отображений, содержащихся в этой карте, в виде `Set`.
`K`	`firstKey()`	Возвращает первый (наименьший) ключ, находящийся в этой карте в данный момент.
`Set<K>`	`keySet()`	Возвращает представление ключей, содержащихся в этой карте, в виде `Set`.
`K`	`lastKey()`	Возвращает последний (наибольший) ключ, находящийся в этой карте в данный момент.
`default V`	`putFirst(K k, V v)`	Вызывает `UnsupportedOperationException`.
`default V`	`putLast(K k, V v)`	Вызывает `UnsupportedOperationException`.
`Collection<V>`	`values()`	Возвращает представление значений, содержащихся в этой карте, в виде `Collection`.

Подробное описание методов

lowerEntry

Map.Entry<K,V> lowerEntry(K key)

Возвращает отображение ключ-значение, связанное с наибольшим ключом, строго меньшим заданного ключа, или null, если такого ключа нет.

Параметры:: key — ключ
Возвращает:: запись с наибольшим ключом, меньшим key, или null, если такого ключа нет
Выбрасывает:: ClassCastException — если заданный ключ нельзя сравнить с ключами, содержащимися в данный момент в карте; NullPointerException — если заданный ключ равен null, а эта карта не допускает null-ключи

lowerKey

K lowerKey(K key)

Возвращает наибольший ключ, строго меньший заданного ключа, или null, если такого ключа нет.

Параметры:: key — ключ
Возвращает:: наибольший ключ, меньший key, или null, если такого ключа нет
Выбрасывает:: ClassCastException — если заданный ключ нельзя сравнить с ключами, содержащимися в данный момент в карте; NullPointerException — если заданный ключ равен null, а эта карта не допускает null-ключи

floorEntry

Map.Entry<K,V> floorEntry(K key)

Возвращает отображение ключ-значение, связанное с наибольшим ключом, меньшим или равным заданному ключу, или null, если такого ключа нет.

Параметры:: key — ключ
Возвращает:: запись с наибольшим ключом, меньшим или равным key, или null, если такого ключа нет
Выбрасывает:: ClassCastException — если заданный ключ нельзя сравнить с ключами, содержащимися в данный момент в карте; NullPointerException — если заданный ключ равен null, а эта карта не допускает null-ключи

floorKey

K floorKey(K key)

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

Параметры:: key — ключ
Возвращает:: наибольший ключ, меньший или равный key, или null, если такого ключа нет
Выбрасывает:: ClassCastException — если заданный ключ нельзя сравнить с ключами, содержащимися в данный момент в карте; NullPointerException — если заданный ключ равен null, а эта карта не допускает null-ключи

ceilingEntry

Map.Entry<K,V> ceilingEntry(K key)

Возвращает отображение ключ-значение, связанное с наименьшим ключом, большим или равным заданному ключу, или null, если такого ключа нет.

Параметры:: key — ключ
Возвращает:: запись с наименьшим ключом, большим или равным key, или null, если такого ключа нет
Выбрасывает:: ClassCastException — если заданный ключ нельзя сравнить с ключами, содержащимися в данный момент в карте; NullPointerException — если заданный ключ равен null, а эта карта не допускает null-ключи

ceilingKey

K ceilingKey(K key)

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

Параметры:: key — ключ
Возвращает:: наименьший ключ, больший или равный key, или null, если такого ключа нет
Выбрасывает:: ClassCastException — если заданный ключ нельзя сравнить с ключами, содержащимися в данный момент в карте; NullPointerException — если заданный ключ равен null, а эта карта не допускает null-ключи

higherEntry

Map.Entry<K,V> higherEntry(K key)

Возвращает отображение ключ-значение, связанное с наименьшим ключом, строго большим заданного ключа, или null, если такого ключа нет.

Параметры:: key — ключ
Возвращает:: запись с наименьшим ключом, большим key, или null, если такого ключа нет
Выбрасывает:: ClassCastException — если заданный ключ нельзя сравнить с ключами, содержащимися в данный момент в карте; NullPointerException — если заданный ключ равен null, а эта карта не допускает null-ключи

higherKey

K higherKey(K key)

Возвращает наименьший ключ, строго больший заданного ключа, или null, если такого ключа нет.

Параметры:: key — ключ
Возвращает:: наименьший ключ, больший key, или null, если такого ключа нет
Выбрасывает:: ClassCastException — если заданный ключ нельзя сравнить с ключами, содержащимися в данный момент в карте; NullPointerException — если заданный ключ равен null, а эта карта не допускает null-ключи

firstEntry

Map.Entry<K,V> firstEntry()

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

Определено в:: firstEntry в интерфейсе SequencedMap<K,V>
Возвращает:: запись с наименьшим ключом или null, если эта карта пуста

lastEntry

Map.Entry<K,V> lastEntry()

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

Определено в:: lastEntry в интерфейсе SequencedMap<K,V>
Возвращает:: запись с наибольшим ключом или null, если эта карта пуста

pollFirstEntry

Map.Entry<K,V> pollFirstEntry()

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

Определено в:: pollFirstEntry в интерфейсе SequencedMap<K,V>
Возвращает:: удалённую первую запись этой карты или null, если эта карта пуста
Выбрасывает:: UnsupportedOperationException — если операция pollFirstEntry не поддерживается этой картой

pollLastEntry

Map.Entry<K,V> pollLastEntry()

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

Определено в:: pollLastEntry в интерфейсе SequencedMap<K,V>
Возвращает:: удалённую последнюю запись этой карты или null, если эта карта пуста
Выбрасывает:: UnsupportedOperationException — если операция pollLastEntry не поддерживается этой картой

descendingMap

NavigableMap<K,V> descendingMap()

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

Возвращённая карта имеет порядок, эквивалентный Collections.reverseOrder(comparator()). Выражение m.descendingMap().descendingMap() возвращает представление m, по существу эквивалентное m.

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

navigableKeySet

NavigableSet<K> navigableKeySet()

Возвращает представление NavigableSet ключей, содержащихся в этой карте. Итератор набора возвращает ключи в порядке возрастания. Набор основан на карте, поэтому изменения в карте отражаются в наборе, и наоборот. Если карта изменяется во время итерации по набору (кроме операции


remove

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

Возвращает:: представление ключей этой карты в виде навигационного набора

descendingKeySet

NavigableSet<K> descendingKeySet()

Возвращает представление NavigableSet ключей, содержащихся в этой карте, в обратном порядке. Итератор набора возвращает ключи в порядке убывания. Набор основан на карте, поэтому изменения в карте отражаются в наборе, и наоборот. Если карта изменяется во время итерации по набору (кроме операции


remove

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

subMap

NavigableMap<K,V> subMap(K fromKey, boolean fromInclusive, K toKey, boolean toInclusive)

Возвращает представление части этой карты, ключи которой находятся в диапазоне от fromKey до toKey. Если fromKey и toKey равны, возвращённая карта пуста, если только fromInclusive и toInclusive не равны true. Возвращённая карта основана на этой карте, поэтому изменения в возвращённой карте отражаются в этой карте, и наоборот. Возвращённая карта поддерживает все необязательные операции с картами, поддерживаемые этой картой.

При попытке вставить ключ за пределами диапазона возвращённая карта выбросит IllegalArgumentException; то же произойдёт при попытке создать под-карту, одна из конечных точек которой находится за пределами диапазона.

Параметры:: fromKey — нижняя граница ключей возвращённой карты; fromInclusive — true, если нижнюю границу следует включить в возвращённое представление; toKey — верхняя граница ключей возвращённой карты; toInclusive — true, если верхнюю границу следует включить в возвращённое представление
Возвращает:: представление части этой карты, ключи которой находятся в диапазоне от fromKey до toKey
Выбрасывает:: ClassCastException — если fromKey и toKey нельзя сравнить друг с другом с помощью компаратора этой карты (или, если у карты нет компаратора, с помощью естественного порядка). Реализации могут выбрасывать это исключение, но не обязаны делать это, если fromKey или toKey нельзя сравнить с ключами, содержащимися в данный момент в карте.; NullPointerException — если fromKey или toKey равен null, а эта карта не допускает null-ключи; IllegalArgumentException — если fromKey больше toKey; или если сама карта имеет ограниченный диапазон, а fromKey или toKey находится за его пределами

headMap

NavigableMap<K,V> headMap(K toKey, boolean inclusive)

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