Interface NavigableMap<K,V>

Type Parameters:: K - тип ключей, поддерживаемых этой картой; V - тип сопоставленных значений

All Superinterfaces:: Map<K,V>, SequencedMap<K,V>, SortedMap<K,V>

All Known Subinterfaces:: ConcurrentNavigableMap<K,V>

All Known Implementing Classes:: ConcurrentSkipListMap, TreeMap

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

A 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.

Since:: 1.6

Nested Class Summary

Nested classes/interfaces declared in interface java.util.Map

Map.Entry<K,V>

Method Summary

Modifier and Type	Method	Description
`Map.Entry<K,V>`	`ceilingEntry(K key)`	Возвращает сопоставление ключ-значение, связанное с наименьшим ключом, большим или равным заданному ключу, или `null`, если такого ключа нет.
`K`	`ceilingKey(K key)`	Возвращает наименьший ключ, больший или равный заданному ключу, или `null`, если такого ключа нет.
`NavigableSet<K>`	`descendingKeySet()`	Возвращает представление набора ключей этой карты в обратном порядке.
`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()`	Возвращает представление набора ключей этой карты.
`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`.

Methods declared in interface 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

Methods declared in interface java.util.SequencedMap

sequencedEntrySet, sequencedKeySet, sequencedValues

Methods declared in interface java.util.SortedMap

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

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

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 , если эта карта пуста

pollLastEntry

Map.Entry<K,V> pollLastEntry()

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

Указано в:: pollLastEntry в интерфейсе SequencedMap<K,V>
Возвращает:: удаленный последний элемент этой карты, или null , если эта карта пуста

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

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

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

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

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

Эквивалентно 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.

Указано в:: reversed в интерфейсе SequencedMap<K,V>
Указано в:: reversed в интерфейсе SortedMap<K,V>
Требования к реализации:: Реализация в этом интерфейсе возвращает результат вызова метода descendingMap.
Возвращает:: представление этой карты в обратном порядке в виде NavigableMap
С:: 21

© 1993, 2023, 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://docs.oracle.com/en/java/javase/21/docs/api/java.base/java/util/NavigableMap.html