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

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

Модификатор и тип	Метод	Описание
`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)`	Возвращает представление той части этой карты, ключи которой меньше `toKey` (или равны ему, если `inclusive` имеет значение true).
`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)`	Возвращает представление той части этой карты, ключи которой больше `fromKey` (или равны ему, если `inclusive` имеет значение true).

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

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

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

sequencedEntrySet, sequencedKeySet, sequencedValues

Методы, объявленные в интерфейсе 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, если эта карта пуста
Вызывает исключения:: 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)

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