java/util/NavigableSet.java

/*
 * Written by Doug Lea with assistance from members of JCP JSR-166
 * Expert Group and released to the public domain, as explained at
 * http://creativecommons.org/licenses/publicdomain
 */

package java.util;

/**
 * A {@link SortedSet} extended with navigation methods reporting
 * closest matches for given search targets. Methods <tt>lower</tt>,
 * <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return keys
 * respectively less than, less than or equal, greater than or equal,
 * and greater than a given key, returning <tt>null</tt> if there is
 * no such key.  A <tt>NavigableSet</tt> may be viewed and traversed
 * in either ascending or descending order.  The <tt>Collection</tt>
 * <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and
 * the additional method <tt>descendingIterator</tt> returns
 * descending iterator. The performance of ascending traversals is
 * likely to be faster than descending traversals.  This interface
 * additionally defines methods <tt>pollFirst</tt> and
 * <t>pollLast</tt> that return and remove the lowest and highest key,
 * if one exists, else returning <tt>null</tt>.
 * Methods <tt>navigableSubSet</tt>, <tt>navigableHeadSet</tt>, and
 * <tt>navigableTailSet</tt> differ from the similarly named
 * <tt>SortedSet</tt> methods only in that the returned sets
 * are guaranteed to obey the <tt>NavigableSet</tt> interface.
 *
 * <p> The return values of navigation methods may be ambiguous in
 * implementations that permit <tt>null</tt> elements. However, even
 * in this case the result can be disambiguated by checking
 * <tt>contains(null)</tt>. To avoid such issues, implementations of
 * this interface are encouraged <em>not</em> to permit insertion of
 * <tt>null</tt> elements. (Note that sorted sets of {@link
 * Comparable} elements intrinsically do not permit <tt>null</tt>.)
 *
 * <p>This interface is a member of the
 * <a href="{@docRoot}/../guide/collections/index.html">
 * Java Collections Framework</a>.
 *
 * @author Doug Lea
 * @param <E> the type of elements maintained by this set
 * @since 1.6
 */
public interface NavigableSet<E> extends SortedSet<E> {
    /**
     * Returns an element greater than or equal to the given element, or
     * <tt>null</tt> if there is no such element.
     *
     * @param e the value to match
     * @return an element greater than or equal to given element, or
     * <tt>null</tt> if there is no such element.
     * @throws ClassCastException if e cannot be compared with the elements
     *            currently in the set.
     * @throws NullPointerException if e is <tt>null</tt>
     * and this set does not permit <tt>null</tt> elements
     */
    E ceiling(E e);

    /**
     * Returns an element strictly less than the given element, or
     * <tt>null</tt> if there is no such element.
     *
     * @param e the value to match
     * @return the greatest element less than the given element, or
     * <tt>null</tt> if there is no such element.
     * @throws ClassCastException if e cannot be compared with the elements
     *            currently in the set.
     * @throws NullPointerException if e is <tt>null</tt>
     * and this set does not permit <tt>null</tt> elements
     */
    E lower(E e);

    /**
     * Returns an element less than or equal to the given element, or
     * <tt>null</tt> if there is no such element.
     *
     * @param e the value to match
     * @return the greatest element less than or equal to given
     * element, or <tt>null</tt> if there is no such element.
     * @throws ClassCastException if e cannot be compared with the elements
     *            currently in the set.
     * @throws NullPointerException if e is <tt>null</tt>.
     * and this set does not permit <tt>null</tt> elements
     */
    E floor(E e);

    /**
     * Returns an element strictly greater than the given element, or
     * <tt>null</tt> if there is no such element.
     *
     * @param e the value to match
     * @return the least element greater than the given element, or
     * <tt>null</tt> if there is no such element.
     * @throws ClassCastException if e cannot be compared with the elements
     *            currently in the set.
     * @throws NullPointerException if e is <tt>null</tt>
     * and this set does not permit <tt>null</tt> elements
     */
    E higher(E e);

    /**
     * Retrieves and removes the first (lowest) element.
     *
     * @return the first element, or <tt>null</tt> if empty.
     */
    E pollFirst();

    /**
     * Retrieves and removes the last (highest) element.
     *
     * @return the last element, or <tt>null</tt> if empty.
     */
    E pollLast();

    /**
     * Returns an iterator over the elements in this collection, in
     * descending order.
     *
     * @return an <tt>Iterator</tt> over the elements in this collection
     */
    Iterator<E> descendingIterator();

    /**
     * Returns a view of the portion of this set whose elements range
     * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
     * exclusive.  (If <tt>fromElement</tt> and <tt>toElement</tt> are
     * equal, the returned navigable set is empty.)  The returned
     * navigable set is backed by this set, so changes in the returned
     * navigable set are reflected in this set, and vice-versa.
     *
     * @param fromElement low endpoint (inclusive) of the subSet.
     * @param toElement high endpoint (exclusive) of the subSet.
     * @return a view of the portion of this set whose elements range from
     *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
     *         exclusive.
     * @throws ClassCastException if <tt>fromElement</tt> and
     *         <tt>toElement</tt> cannot be compared to one another using
     *         this set's comparator (or, if the set has no comparator,
     *         using natural ordering).
     * @throws IllegalArgumentException if <tt>fromElement</tt> is
     * greater than <tt>toElement</tt>.
     * @throws NullPointerException if <tt>fromElement</tt> or
     *         <tt>toElement</tt> is <tt>null</tt>
     * and this set does not permit <tt>null</tt> elements
     */
    NavigableSet<E> navigableSubSet(E fromElement, E toElement);

    /**
     * Returns a view of the portion of this set whose elements are
     * strictly less than <tt>toElement</tt>.  The returned navigable
     * set is backed by this set, so changes in the returned navigable
     * set are reflected in this set, and vice-versa.
     * @param toElement high endpoint (exclusive) of the headSet.
     * @return a view of the portion of this set whose elements are strictly
     *         less than toElement.
     * @throws ClassCastException if <tt>toElement</tt> is not compatible
     *         with this set's comparator (or, if the set has no comparator,
     *         if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
     * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt>
     * and this set does not permit <tt>null</tt> elements
     */
    NavigableSet<E> navigableHeadSet(E toElement);

    /**
     * Returns a view of the portion of this set whose elements are
     * greater than or equal to <tt>fromElement</tt>.  The returned
     * navigable set is backed by this set, so changes in the returned
     * navigable set are reflected in this set, and vice-versa.
     * @param fromElement low endpoint (inclusive) of the tailSet.
     * @return a view of the portion of this set whose elements are
     * greater than or equal to <tt>fromElement</tt>.
     * @throws ClassCastException if <tt>fromElement</tt> is not
     * compatible with this set's comparator (or, if the set has no
     * comparator, if <tt>fromElement</tt> does not implement
     * <tt>Comparable</tt>).
     * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
     * and this set does not permit <tt>null</tt> elements
     */
    NavigableSet<E> navigableTailSet(E fromElement);
}
Revision:	1.8
Committed:	Tue May 3 02:52:07 2005 UTC (19 years ago) by jsr166
Branch:	MAIN
Changes since 1.7:	+4 -0 lines
Log Message:	Update collections framework pointer
#	Content
1	/*
2	* Written by Doug Lea with assistance from members of JCP JSR-166
3	* Expert Group and released to the public domain, as explained at
4	* http://creativecommons.org/licenses/publicdomain
5	*/
6
7	package java.util;
8
9	/**
10	* A {@link SortedSet} extended with navigation methods reporting
11	* closest matches for given search targets. Methods <tt>lower</tt>,
12	* <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return keys
13	* respectively less than, less than or equal, greater than or equal,
14	* and greater than a given key, returning <tt>null</tt> if there is
15	* no such key. A <tt>NavigableSet</tt> may be viewed and traversed
16	* in either ascending or descending order. The <tt>Collection</tt>
17	* <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and
18	* the additional method <tt>descendingIterator</tt> returns
19	* descending iterator. The performance of ascending traversals is
20	* likely to be faster than descending traversals. This interface
21	* additionally defines methods <tt>pollFirst</tt> and
22	* <t>pollLast</tt> that return and remove the lowest and highest key,
23	* if one exists, else returning <tt>null</tt>.
24	* Methods <tt>navigableSubSet</tt>, <tt>navigableHeadSet</tt>, and
25	* <tt>navigableTailSet</tt> differ from the similarly named
26	* <tt>SortedSet</tt> methods only in that the returned sets
27	* are guaranteed to obey the <tt>NavigableSet</tt> interface.
28	*
29	* <p> The return values of navigation methods may be ambiguous in
30	* implementations that permit <tt>null</tt> elements. However, even
31	* in this case the result can be disambiguated by checking
32	* <tt>contains(null)</tt>. To avoid such issues, implementations of
33	* this interface are encouraged <em>not</em> to permit insertion of
34	* <tt>null</tt> elements. (Note that sorted sets of {@link
35	* Comparable} elements intrinsically do not permit <tt>null</tt>.)
36	*
37	* <p>This interface is a member of the
38	* <a href="{@docRoot}/../guide/collections/index.html">
39	* Java Collections Framework</a>.
40	*
41	* @author Doug Lea
42	* @param <E> the type of elements maintained by this set
43	* @since 1.6
44	*/
45	public interface NavigableSet<E> extends SortedSet<E> {
46	/**
47	* Returns an element greater than or equal to the given element, or
48	* <tt>null</tt> if there is no such element.
49	*
50	* @param e the value to match
51	* @return an element greater than or equal to given element, or
52	* <tt>null</tt> if there is no such element.
53	* @throws ClassCastException if e cannot be compared with the elements
54	* currently in the set.
55	* @throws NullPointerException if e is <tt>null</tt>
56	* and this set does not permit <tt>null</tt> elements
57	*/
58	E ceiling(E e);
59
60	/**
61	* Returns an element strictly less than the given element, or
62	* <tt>null</tt> if there is no such element.
63	*
64	* @param e the value to match
65	* @return the greatest element less than the given element, or
66	* <tt>null</tt> if there is no such element.
67	* @throws ClassCastException if e cannot be compared with the elements
68	* currently in the set.
69	* @throws NullPointerException if e is <tt>null</tt>
70	* and this set does not permit <tt>null</tt> elements
71	*/
72	E lower(E e);
73
74	/**
75	* Returns an element less than or equal to the given element, or
76	* <tt>null</tt> if there is no such element.
77	*
78	* @param e the value to match
79	* @return the greatest element less than or equal to given
80	* element, or <tt>null</tt> if there is no such element.
81	* @throws ClassCastException if e cannot be compared with the elements
82	* currently in the set.
83	* @throws NullPointerException if e is <tt>null</tt>.
84	* and this set does not permit <tt>null</tt> elements
85	*/
86	E floor(E e);
87
88	/**
89	* Returns an element strictly greater than the given element, or
90	* <tt>null</tt> if there is no such element.
91	*
92	* @param e the value to match
93	* @return the least element greater than the given element, or
94	* <tt>null</tt> if there is no such element.
95	* @throws ClassCastException if e cannot be compared with the elements
96	* currently in the set.
97	* @throws NullPointerException if e is <tt>null</tt>
98	* and this set does not permit <tt>null</tt> elements
99	*/
100	E higher(E e);
101
102	/**
103	* Retrieves and removes the first (lowest) element.
104	*
105	* @return the first element, or <tt>null</tt> if empty.
106	*/
107	E pollFirst();
108
109	/**
110	* Retrieves and removes the last (highest) element.
111	*
112	* @return the last element, or <tt>null</tt> if empty.
113	*/
114	E pollLast();
115
116	/**
117	* Returns an iterator over the elements in this collection, in
118	* descending order.
119	*
120	* @return an <tt>Iterator</tt> over the elements in this collection
121	*/
122	Iterator<E> descendingIterator();
123
124	/**
125	* Returns a view of the portion of this set whose elements range
126	* from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
127	* exclusive. (If <tt>fromElement</tt> and <tt>toElement</tt> are
128	* equal, the returned navigable set is empty.) The returned
129	* navigable set is backed by this set, so changes in the returned
130	* navigable set are reflected in this set, and vice-versa.
131	*
132	* @param fromElement low endpoint (inclusive) of the subSet.
133	* @param toElement high endpoint (exclusive) of the subSet.
134	* @return a view of the portion of this set whose elements range from
135	* <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
136	* exclusive.
137	* @throws ClassCastException if <tt>fromElement</tt> and
138	* <tt>toElement</tt> cannot be compared to one another using
139	* this set's comparator (or, if the set has no comparator,
140	* using natural ordering).
141	* @throws IllegalArgumentException if <tt>fromElement</tt> is
142	* greater than <tt>toElement</tt>.
143	* @throws NullPointerException if <tt>fromElement</tt> or
144	* <tt>toElement</tt> is <tt>null</tt>
145	* and this set does not permit <tt>null</tt> elements
146	*/
147	NavigableSet<E> navigableSubSet(E fromElement, E toElement);
148
149	/**
150	* Returns a view of the portion of this set whose elements are
151	* strictly less than <tt>toElement</tt>. The returned navigable
152	* set is backed by this set, so changes in the returned navigable
153	* set are reflected in this set, and vice-versa.
154	* @param toElement high endpoint (exclusive) of the headSet.
155	* @return a view of the portion of this set whose elements are strictly
156	* less than toElement.
157	* @throws ClassCastException if <tt>toElement</tt> is not compatible
158	* with this set's comparator (or, if the set has no comparator,
159	* if <tt>toElement</tt> does not implement <tt>Comparable</tt>).
160	* @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt>
161	* and this set does not permit <tt>null</tt> elements
162	*/
163	NavigableSet<E> navigableHeadSet(E toElement);
164
165	/**
166	* Returns a view of the portion of this set whose elements are
167	* greater than or equal to <tt>fromElement</tt>. The returned
168	* navigable set is backed by this set, so changes in the returned
169	* navigable set are reflected in this set, and vice-versa.
170	* @param fromElement low endpoint (inclusive) of the tailSet.
171	* @return a view of the portion of this set whose elements are
172	* greater than or equal to <tt>fromElement</tt>.
173	* @throws ClassCastException if <tt>fromElement</tt> is not
174	* compatible with this set's comparator (or, if the set has no
175	* comparator, if <tt>fromElement</tt> does not implement
176	* <tt>Comparable</tt>).
177	* @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>
178	* and this set does not permit <tt>null</tt> elements
179	*/
180	NavigableSet<E> navigableTailSet(E fromElement);
181	}