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

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

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

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

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

Реализации методов, возвращающих записи, должны возвращать Map.Entry пары, представляющие снимки сопоставлений на момент их создания, и поэтому обычно не поддерживают необязательный метод Entry.setValue. Однако, обратите внимание, что можно изменить сопоставления в связанной карте, используя метод put.

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

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

Методы

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 если отображение пустое.

Возвращает:

запись с наименьшим ключом, или null если это отображение пустое

lastEntry

Map.Entry<K,V> lastEntry()

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

Возвращает:

запись с наибольшим ключом, или null если это отображение пустое

pollFirstEntry

Map.Entry<K,V> pollFirstEntry()

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

Возвращает:

удаленная первая запись этого отображения, или null если это отображение пустое

pollLastEntry

Map.Entry<K,V> pollLastEntry()

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

Возвращает:

удаленная последняя запись этого отображения, или null если это отображение пустое

descendingMap

NavigableMap<K,V> descendingMap()

Возвращает:

представление этого отображения в обратном порядке

navigableKeySet

NavigableSet<K> navigableKeySet()

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

Возвращает:

представление навигационного множества ключей в этом отображении

descendingKeySet

NavigableSet<K> descendingKeySet()

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

Возвращает:

представление навигационного множества ключей в этом отображении в обратном порядке

subMap

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

Параметры:

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 включать ли верхнюю границу в возвращаемый вид

Возвращает:

вид части этой карты, ключи которой меньше (или равны, если inclusive истинно) toKey

Исключения:

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

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

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

tailMap

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

Параметры:

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

inclusive - true включать ли нижнюю границу в возвращаемый вид

Возвращает:

вид части этой карты, ключи которой больше (или равны, если inclusive истинно) fromKey

Исключения:

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

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

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

subMap

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

Определено в:

subMap в интерфейсе SortedMap<K,V>

Параметры:

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)

Определено в:

headMap в интерфейсе SortedMap<K,V>

Параметры:

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

Возвращает:

вид части этой карты, ключи которой строго меньше toKey

Исключения:

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

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

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

tailMap

SortedMap<K,V> tailMap(K fromKey)

Определено в:

tailMap в интерфейсе SortedMap<K,V>

Параметры:

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

Возвращает:

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

Исключения:

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

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

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