java.util
介面 NavigableSet<E>

型別參數：

E - 此 set 維護的元素型別

所有父級介面：

Collection<E>, Iterable<E>, Set<E>, SortedSet<E>

所有已知實作類別：

ConcurrentSkipListSet, TreeSet

public interface NavigableSet<E>
extends SortedSet<E>

擴展的 SortedSet，具有了為給定搜尋目標報告最接近比對項的導航方法。方法 lower、floor、ceiling 和 higher 分別返回小於、小於等於、大於等於、大於給定元素的元素，如果不存在這樣的元素，則返回 null。可以按升序或降序存取和遍歷 NavigableSet。descendingSet 方法返回 set 的一個視圖，該視圖表示的所有關係方法和方向方法都是逆向的。升序操作和視圖的性能很可能比降序操作和視圖的性能要好。此外，此介面還定義了 pollFirst 和 pollLast 方法，它們返回並移除最小和最大的元素（如果存在），否則返回 null。subSet、headSet 和 tailSet 方法與名稱相似的 SortedSet 方法的不同之處在於：可以接受用於描述是否包括（或不包括）下邊界和上邊界的附加參數。任何 NavigableSet 的 Submap 必須實作 NavigableSet 介面。

導航方法的返回值在允許 null 元素的實作中可能是不確定的。不過，即使在這種情況下，也可以通過檢查 contains(null) 來明確結果。為了避免這樣的問題，建議在此介面的實作中不 允許插入 null 元素。（注意，Comparable 元素的有序集本身不允許 null。）

subSet(E, E)、headSet(E) 和 tailSet(E) 方法被指定為返回 SortedSet，以允許現有 SortedSet 實作能相容地改進為實作 NavigableMap，但鼓勵此介面的擴展和實作覆寫這些方法以返回 NavigableSet。

此介面是 Java Collections Framework 的成員。

從以下版本開始：

1.6

方法摘要

E	ceiling(E e) 返回此 set 中大於等於給定元素的最小元素；如果不存在這樣的元素，則返回 null。
Iterator<E>	descendingIterator() 以降序返回在此 set 的元素上進行迭代的迭代器。
NavigableSet<E>	descendingSet() 返回此 set 中所包含元素的逆序視圖。
E	floor(E e) 返回此 set 中小於等於給定元素的最大元素；如果不存在這樣的元素，則返回 null。
SortedSet<E>	headSet(E toElement) 返回此 set 的部分視圖，其元素嚴格小於 toElement。
NavigableSet<E>	headSet(E toElement, boolean inclusive) 返回此 set 的部分視圖，其元素小於（或等於，如果 inclusive 為 true）toElement。
E	higher(E e) 返回此 set 中嚴格大於給定元素的最小元素；如果不存在這樣的元素，則返回 null。
Iterator<E>	iterator() 以升序返回在此 set 的元素上進行迭代的迭代器。
E	lower(E e) 返回此 set 中嚴格小於給定元素的最大元素；如果不存在這樣的元素，則返回 null。
E	pollFirst() 獲取並移除第一個（最低）元素；如果此 set 為空，則返回 null。
E	pollLast() 獲取並移除最後一個（最高）元素；如果此 set 為空，則返回 null。
NavigableSet<E>	subSet(E fromElement, boolean fromInclusive, E toElement, boolean toInclusive) 返回此 set 的部分視圖，其元素範圍從 fromElement 到 toElement。
SortedSet<E>	subSet(E fromElement, E toElement) 返回此 set 的部分視圖，其元素從 fromElement（包括）到 toElement（不包括）。
SortedSet<E>	tailSet(E fromElement) 返回此 set 的部分視圖，其元素大於等於 fromElement。
NavigableSet<E>	tailSet(E fromElement, boolean inclusive) 返回此 set 的部分視圖，其元素大於（或等於，如果 inclusive 為 true）fromElement。

從介面 java.util.SortedSet 繼承的方法

comparator, first, last

從介面 java.util.Set 繼承的方法

add, addAll, clear, contains, containsAll, equals, hashCode, isEmpty, remove, removeAll, retainAll, size, toArray, toArray

方法詳細資訊

lower

E lower(E e)

返回此 set 中嚴格小於給定元素的最大元素；如果不存在這樣的元素，則返回 null。

參數：

e - 要比對的值

返回：

小於 e 的最大元素；如果不存在這樣的元素，則返回 null

拋出：

ClassCastException - 如果指定元素不能與 set 中的當前元素進行比較

NullPointerException - 如果指定元素為 null 並且此 set 不允許 null 元素

floor

E floor(E e)

返回此 set 中小於等於給定元素的最大元素；如果不存在這樣的元素，則返回 null。

參數：

e - 要比對的值

返回：

小於等於 e 的最大元素；如果不存在這樣的元素，則返回 null

拋出：

ClassCastException - 如果指定元素不能與 set 中的當前元素進行比較

NullPointerException - 如果指定元素為 null 並且此 set 不允許 null 元素

ceiling

E ceiling(E e)

返回此 set 中大於等於給定元素的最小元素；如果不存在這樣的元素，則返回 null。

參數：

e - 要比對的值

返回：

大於等於 e 的最小元素；如果不存在這樣的元素，則返回 null

拋出：

ClassCastException - 如果指定元素不能與 set 中的當前元素進行比較

NullPointerException - 如果指定元素為 null 並且此 set 不允許 null 元素

higher

E higher(E e)

返回此 set 中嚴格大於給定元素的最小元素；如果不存在這樣的元素，則返回 null。

參數：

e - 要比對的值

返回：

大於 e 的最小元素；如果不存在這樣的元素，則返回 null

拋出：

ClassCastException - 如果指定元素不能與 set 中的當前元素進行比較

NullPointerException - 如果指定元素為 null 並且此 set 不允許 null 元素

pollFirst

E pollFirst()

獲取並移除第一個（最低）元素；如果此 set 為空，則返回 null。

返回：

第一個元素；如果此 set 為空，則返回 null

pollLast

E pollLast()

獲取並移除最後一個（最高）元素；如果此 set 為空，則返回 null。

返回：

最後一個元素；如果此 set 為空，則返回 null

iterator

Iterator<E> iterator()

以升序返回在此 set 的元素上進行迭代的迭代器。

指定者：

介面 Collection<E> 中的 iterator

指定者：

介面 Iterable<E> 中的 iterator

指定者：

介面 Set<E> 中的 iterator

返回：

以升序返回在此 set 的元素上進行迭代的迭代器

descendingSet

NavigableSet<E> descendingSet()

返回此 set 中所包含元素的逆序視圖。降序 set 受此 set 的支持，因此對此 set 的更改將反映在降序 set 中，反之亦然。如果在對任一 set 進行迭代的同時修改了任一 set（通過迭代器自己的 remove 操作除外），則迭代結果是不確定的。

返回 set 的順序等於 Collections.reverseOrder(comparator())。表達式 s.descendingSet().descendingSet() 返回的 s 視圖基本等於 s。

返回：

此 set 的逆序視圖

descendingIterator

Iterator<E> descendingIterator()

以降序返回在此 set 的元素上進行迭代的迭代器。效果等同於 descendingSet().iterator()。

返回：

在此 set 的元素上以降序進行迭代的迭代器

subSet

NavigableSet<E> subSet(E fromElement,
                       boolean fromInclusive,
                       E toElement,
                       boolean toInclusive)

返回此 set 的部分視圖，其元素範圍從 fromElement 到 toElement。如果 fromElement 和 toElement 相等，則返回的 set 為空，除非 fromExclusive 和 toExclusive 都為 true。返回的 set 受此 set 支持，所以在返回 set 中的更改將反映在此 set 中，反之亦然。返回 set 支持此 set 支持的所有可選 set 操作。

如果試圖在返回 set 的範圍之外插入元素，則返回的 set 將拋出 IllegalArgumentException。

參數：

fromElement - 返回 set 的低端點

fromInclusive - 如果低端點要包含在返回的視圖中，則為 true

toElement - 返回 set 的高端點

toInclusive - 如果高端點要包含在返回的視圖中，則為 true

返回：

此 set 的部分視圖，其元素範圍從 fromElement（包括）到 toElement（不包括）

拋出：

ClassCastException - 如果不能使用此 set 的比較器或者使用自然順序（如果 set 沒有比較器）比較 fromElement 和 toElement。如果 fromElement 或 toElement 不能與 set 中的當前元素進行比較，則實作可以（但不是必須）拋出此異常。

NullPointerException - 如果 fromElement 或 toElement 為 null 並且此 set 不允許 null 元素

IllegalArgumentException - 如果 fromElement 大於 toElement；如果此 set 本身有範圍限制，並且 fromElement 或 toElement 位於範圍的邊界之外。

headSet

NavigableSet<E> headSet(E toElement,
                        boolean inclusive)

返回此 set 的部分視圖，其元素小於（或等於，如果 inclusive 為 true）toElement。返回的 set 受此 set 支持，所以在返回 set 中的更改將反映在此 set 中，反之亦然。返回 set 支持此 set 支持的所有可選 set 操作。

如果試圖在返回 set 的範圍之外插入元素，則返回的 set 將拋出 IllegalArgumentException。

參數：

toElement - 返回 set 的高端點

inclusive - 如果高端點要包含在返回的視圖中，則為 true

返回：

此 set 的部分視圖，其元素小於（或等於，如果 inclusive 為 true）toElement

拋出：

ClassCastException - 如果 toElement 與此 set 的比較器不相容（如果 set 沒有比較器；如果 toElement 沒有實作 Comparable）。如果 toElement 不能與 set 中的當前元素進行比較，則實作可以（但不是必須）拋出此異常。

NullPointerException - 如果 toElement 為 null 並且此 set 不允許 null 元素

IllegalArgumentException - 如果此 set 本身有範圍限制，並且 toElement 位於範圍的邊界之外

tailSet

NavigableSet<E> tailSet(E fromElement,
                        boolean inclusive)

返回此 set 的部分視圖，其元素大於（或等於，如果 inclusive 為 true）fromElement。返回的 set 受此 set 支持，所以在返回 set 中的更改將反映在此 set 中，反之亦然。返回 set 支持此 set 支持的所有可選 set 操作。

如果試圖在返回 set 的範圍之外插入元素，則返回的 set 將拋出 IllegalArgumentException。

參數：

fromElement - 返回 set 的低端點

inclusive - 如果低端點要包含在返回的視圖中，則為 true

返回：

此 set 的部分視圖，其元素大於等於 fromElement

拋出：

ClassCastException - 如果 fromElement 與此 set 的比較器不相容（如果 set 沒有任何比較器；如果 fromElement 沒有實作 Comparable）。如果 fromElement 不能與 set 中的當前元素進行比較，則實作可以（但不是必須）拋出此異常。

NullPointerException - 如果 fromElement 為 null 並且此 set 不允許 null 元素

IllegalArgumentException - 如果此 set 本身有範圍限制，並且 fromElement 位於範圍的邊界之外

subSet

SortedSet<E> subSet(E fromElement,
                    E toElement)

返回此 set 的部分視圖，其元素從 fromElement（包括）到 toElement（不包括）。（如果 fromElement 和 toElement 相等，則返回空的 set）。返回的 set 受此 set 支持，所以在返回 set 中的更改將反映在此 set 中，反之亦然。返回的 set 支持此 set 支持的所有可選 set 操作。

如果試圖在返回 set 的範圍之外插入元素，則返回的 set 將拋出 IllegalArgumentException。

等效於 subSet(fromElement, true, toElement, false)。

指定者：

介面 SortedSet<E> 中的 subSet

參數：

fromElement - 返回 set 的低端點（包括）

toElement - 返回 set 的高端點（不包括）

返回：

此 set 的部分視圖，其元素的範圍從 fromElement（包括）到 toElement（不包括）

拋出：

ClassCastException - 如果無法使用此 set 的比較器（如果 set 沒有比較器，則使用自然順序）比較 fromElement 和 toElement。如果 fromElement 或 toElement 不能與 set 中的當前元素進行比較，則實作可以（但不是必須）拋出此異常。

NullPointerException - 如果 fromElement 或 toElement 為 null，並且此 set 不允許 null 元素

IllegalArgumentException - 如果 fromElement 大於 toElement；如果此 set 本身有範圍限制，並且 fromElement 或 toElement 位於範圍的邊界之外

headSet

SortedSet<E> headSet(E toElement)

返回此 set 的部分視圖，其元素嚴格小於 toElement。返回的 set 受此 set 支持，所以在返回 set 中的更改將反映在此 set 中，反之亦然。返回的 set 支持此 set 支持的所有可選 set 操作。

如果試圖在返回 set 的範圍之外插入元素，則返回的 set 將拋出 IllegalArgumentException。

等效於 headSet(toElement, false)。

指定者：

介面 SortedSet<E> 中的 headSet

參數：

toElement - 返回 set 的高端點（不包括）

返回：

此 set 的部分視圖，其元素嚴格小於 toElement

拋出：

ClassCastException - 如果 toElement 與此 set 的比較器不相容（如果 set 沒有比較器；如果 toElement 沒有實作 Comparable）。如果 toElement 不能與 set 中的當前元素進行比較，則實作可以（但不是必須）拋出此異常。

NullPointerException - 如果 toElement 為 null，並且此 set 不允許 null 元素

IllegalArgumentException - 如果此 set 本身有範圍限制，並且 toElement 位於範圍的邊界之外

tailSet

SortedSet<E> tailSet(E fromElement)

返回此 set 的部分視圖，其元素大於等於 fromElement。返回的 set 受此 set 支持，所以在返回 set 中的更改將反映在此 set 中，反之亦然。返回的 set 支持此 set 支持的所有可選 set 操作。

如果試圖在返回 set 的範圍之外插入元素，則返回的 set 將拋出 IllegalArgumentException。

等效於 tailSet(fromElement, true)。

指定者：

介面 SortedSet<E> 中的 tailSet

參數：

fromElement - 返回 set 的低端點（包括）

返回：

此 set 的部分視圖，其元素大於等於 fromElement

拋出：

ClassCastException - 如果 fromElement 與此 set 的比較器不相容（如果 set 沒有比較器；如果 fromElement 沒有實作 Comparable）。如果 fromElement 不能與 set 中的當前元素進行比較，則實作可以（但不是必須）拋出此異常。

NullPointerException - 如果 fromElement 為 null，並且此 set 不允許 null 元素

IllegalArgumentException - 如果此 set 本身有範圍限制，並且 fromElement 位於範圍的邊界之外