Интерфейс 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

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

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

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` истинно) `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` истинно) `fromKey`.

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

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

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

sequencedEntrySet, sequencedKeySet, sequencedValues

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

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

END_OF_DOCUMENT_MARKER

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

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()

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

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

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

navigableKeySet

NavigableSet<K> navigableKeySet()

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


 remove

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

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

descendingKeySet

NavigableSet<K> descendingKeySet()

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

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

subMap

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

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

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

Parameters:: fromKey - нижняя граница ключей в возвращаемой карте; fromInclusive - true, если нижняя граница должна быть включена в возвращаемое представление; toKey - верхняя граница ключей в возвращаемой карте; toInclusive - true, если верхняя граница должна быть включена в возвращаемое представление
Returns:: представление части этой карты, ключи которой находятся в диапазоне от fromKey до toKey
Throws:: 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. Возвращаемая карта поддерживается этой картой, поэтому изменения в возвращаемой карте отражаются в этой карте, и наоборот. Возвращаемая карта поддерживает все необязательные операции карты, которые поддерживает эта карта.

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

Parameters:: toKey - верхняя граница ключей в возвращаемой карте; inclusive - true, если верхняя граница должна быть включена в возвращаемое представление
Returns:: представление части этой карты, ключи которой меньше (или равны, если inclusive равно true) toKey
Throws:: ClassCastException - если toKey несовместим с компаратором этой карты (или, если у карты нет компаратора, если toKey не реализует Comparable). Реализации могут, но не обязаны, выбрасывать это исключение, если toKey нельзя сравнить с ключами, которые есть в данный момент в карте.; NullPointerException - если toKey равно null, и эта карта не допускает null-ключей; IllegalArgumentException - если у этой карты есть ограниченный диапазон, а toKey лежит за пределами границ диапазона

tailMap

NavigableMap<K,V> tailMap(K fromKey, boolean inclusive)

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

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

Parameters:: fromKey - нижняя граница ключей в возвращаемой карте; inclusive - true, если нижняя граница должна быть включена в возвращаемое представление
Returns:: представление части этой карты, ключи которой больше (или равны, если inclusive равно true) fromKey
Throws:: ClassCastException - если fromKey несовместим с компаратором этой карты (или, если у карты нет компаратора, если fromKey не реализует Comparable). Реализации могут, но не обязаны, выбрасывать это исключение, если fromKey нельзя сравнить с ключами, которые есть в данный момент в карте.; NullPointerException - если fromKey равно null, и эта карта не допускает null-ключей; IllegalArgumentException - если у этой карты есть ограниченный диапазон, а fromKey лежит за пределами границ диапазона

subMap

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

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

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

Эквивалентно subMap(fromKey, true, toKey, false).

Specified by:: subMap в интерфейсе SortedMap<K,V>
Parameters:: fromKey - нижняя граница (включительно) ключей в возвращаемой карте; toKey - верхняя граница (исключительно) ключей в возвращаемой карте
Returns:: представление части этой карты, ключи которой находятся в диапазоне от fromKey (включительно) до toKey (исключительно)
Throws:: ClassCastException - если fromKey и toKey нельзя сравнить друг с другом с помощью компаратора этой карты (или, если у карты нет компаратора, используя естественный порядок). Реализации могут, но не обязаны, выбрасывать это исключение, если fromKey или toKey нельзя сравнить с ключами, которые есть в данный момент в карте.; NullPointerException - если fromKey или toKey равно null, и эта карта не допускает null-ключей; IllegalArgumentException - если fromKey больше, чем toKey; или если у этой карты есть ограниченный диапазон, а fromKey или toKey лежит за пределами границ диапазона

headMap

SortedMap<K,V> headMap(K toKey)

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

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

Эквивалентно headMap(toKey, false).

Specified by:: headMap в интерфейсе SortedMap<K,V>
Parameters:: toKey - верхняя граница (исключительно) ключей в возвращаемой карте
Returns:: представление части этой карты, ключи которой строго меньше toKey
Throws:: ClassCastException - если toKey несовместим с компаратором этой карты (или, если у карты нет компаратора, если toKey не реализует Comparable). Реализации могут, но не обязаны, выбрасывать это исключение, если toKey нельзя сравнить с ключами, которые есть в данный момент в карте.; NullPointerException - если toKey равно null, и эта карта не допускает null-ключей; IllegalArgumentException - если у этой карты есть ограниченный диапазон, а toKey лежит за пределами границ диапазона

tailMap

SortedMap<K,V> tailMap(K fromKey)

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

Возвращаемое отображение выбросит IllegalArgumentException при попытке вставки ключа за пределами своего диапазона.

Эквивалентно tailMap(fromKey, true).

Specified by:: tailMap в интерфейсе SortedMap<K,V>
Parameters:: fromKey - нижняя граница (включительно) ключей в возвращаемом отображении
Returns:: представление части этого отображения, ключи которой больше или равны fromKey
Throws:: ClassCastException - если fromKey не совместим с компаратором этого отображения (или, если отображение не имеет компаратора, если fromKey не реализует Comparable). Реализации могут, но не обязаны, выбрасывать это исключение, если fromKey нельзя сравнить с ключами, которые сейчас находятся в отображении.; NullPointerException - если fromKey равно null, а это отображение не допускает null ключей; IllegalArgumentException - если у этого отображения ограниченный диапазон, а fromKey находится за пределами границ диапазона

reversed

default NavigableMap<K,V> reversed()

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

Этот метод эквивалентен методу descendingMap.

Specified by:: reversed в интерфейсе SequencedMap<K,V>
Specified by:: reversed в интерфейсе SortedMap<K,V>
Implementation Requirements:: Реализация в этом интерфейсе возвращает результат вызова метода descendingMap.
Returns:: отображение этого отображения с обратным порядком, как NavigableMap
Since:: 21

© 1993, 2025, Oracle and/or its affiliates. All rights reserved.
Documentation extracted from Debian's OpenJDK Development Kit package.
Licensed under the GNU General Public License, version 2, with the Classpath Exception.
Various third party code in OpenJDK is licensed under different licenses (see Debian package).
Java and OpenJDK are trademarks or registered trademarks of Oracle and/or its affiliates.
https://download.java.net/java/early_access/jdk24/docs/api/java.base/java/util/NavigableMap.html