[cvs] / jsr166 / src / main / java / util / NavigableSet.java Repository:
ViewVC logotype

Diff of /jsr166/src/main/java/util/NavigableSet.java

Parent Directory Parent Directory | Revision Log Revision Log | View Patch Patch

revision 1.8, Tue May 3 02:52:07 2005 UTC revision 1.9, Mon May 16 06:27:52 2005 UTC
# Line 9  Line 9 
9  /**  /**
10   * A {@link SortedSet} extended with navigation methods reporting   * A {@link SortedSet} extended with navigation methods reporting
11   * closest matches for given search targets. Methods <tt>lower</tt>,   * closest matches for given search targets. Methods <tt>lower</tt>,
12   * <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return keys   * <tt>floor</tt>, <tt>ceiling</tt>, and <tt>higher</tt> return elements
13   * respectively less than, less than or equal, greater than or equal,   * 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   * and greater than a given element, returning <tt>null</tt> if there is
15   * no such key.  A <tt>NavigableSet</tt> may be viewed and traversed   * no such element.  A <tt>NavigableSet</tt> may be viewed and traversed
16   * in either ascending or descending order.  The <tt>Collection</tt>   * in either ascending or descending order.  The <tt>Collection</tt>
17   * <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and   * <tt>iterator</tt> method returns an ascending <tt>Iterator</tt> and
18   * the additional method <tt>descendingIterator</tt> returns   * the additional method <tt>descendingIterator</tt> returns a
19   * descending iterator. The performance of ascending traversals is   * descending iterator. The performance of ascending traversals is
20   * likely to be faster than descending traversals.  This interface   * likely to be faster than descending traversals.  This interface
21   * additionally defines methods <tt>pollFirst</tt> and   * additionally defines methods <tt>pollFirst</tt> and
22   * <t>pollLast</tt> that return and remove the lowest and highest key,   * <tt>pollLast</tt> that return and remove the lowest and highest
23   * if one exists, else returning <tt>null</tt>.   * element, if one exists, else returning <tt>null</tt>.
24   * Methods <tt>navigableSubSet</tt>, <tt>navigableHeadSet</tt>, and   * Methods <tt>navigableSubSet</tt>, <tt>navigableHeadSet</tt>, and
25   * <tt>navigableTailSet</tt> differ from the similarly named   * <tt>navigableTailSet</tt> differ from the similarly named
26   * <tt>SortedSet</tt> methods only in that the returned sets   * <tt>SortedSet</tt> methods only in that the returned sets
# Line 30  Line 30 
30   * implementations that permit <tt>null</tt> elements. However, even   * implementations that permit <tt>null</tt> elements. However, even
31   * in this case the result can be disambiguated by checking   * in this case the result can be disambiguated by checking
32   * <tt>contains(null)</tt>. To avoid such issues, implementations of   * <tt>contains(null)</tt>. To avoid such issues, implementations of
33   * this interface are encouraged <em>not</em> to permit insertion of   * this interface are encouraged to <em>not</em> permit insertion of
34   * <tt>null</tt> elements. (Note that sorted sets of {@link   * <tt>null</tt> elements. (Note that sorted sets of {@link
35   * Comparable} elements intrinsically do not permit <tt>null</tt>.)   * Comparable} elements intrinsically do not permit <tt>null</tt>.)
36   *   *
# Line 44  Line 44 
44   */   */
45  public interface NavigableSet<E> extends SortedSet<E> {  public interface NavigableSet<E> extends SortedSet<E> {
46      /**      /**
47       * Returns an element greater than or equal to the given element, or       * Returns the greatest element in this set strictly less than the
48       * <tt>null</tt> if there is no such element.       * given element, or <tt>null</tt> if there is no such element.
49       *       *
50       * @param e the value to match       * @param e the value to match
51       * @return an element greater than or equal to given element, or       * @return the greatest element less than <tt>e</tt>,
52       * <tt>null</tt> if there is no such element.       *         or <tt>null</tt> if there is no such element
53       * @throws ClassCastException if e cannot be compared with the elements       * @throws ClassCastException if the specified element cannot be
54       *            currently in the set.       *         compared with the elements currently in the set
55       * @throws NullPointerException if e is <tt>null</tt>       * @throws NullPointerException if the specified element is null
56       * and this set does not permit <tt>null</tt> elements       *         and this set does not permit null elements
57       */       */
58      E ceiling(E e);      E lower(E e);
59    
60      /**      /**
61       * Returns an element strictly less than the given element, or       * Returns the greatest element in this set less than or equal to
62       * <tt>null</tt> if there is no such element.       * the given element, or <tt>null</tt> if there is no such element.
63       *       *
64       * @param e the value to match       * @param e the value to match
65       * @return the greatest element less than the given element, or       * @return the greatest element less than or equal to <tt>e</tt>,
66       * <tt>null</tt> if there is no such element.       *         or <tt>null</tt> if there is no such element
67       * @throws ClassCastException if e cannot be compared with the elements       * @throws ClassCastException if the specified element cannot be
68       *            currently in the set.       *         compared with the elements currently in the set
69       * @throws NullPointerException if e is <tt>null</tt>       * @throws NullPointerException if the specified element is null
70       * and this set does not permit <tt>null</tt> elements       *         and this set does not permit null elements
71       */       */
72      E lower(E e);      E floor(E e);
73    
74      /**      /**
75       * Returns an element less than or equal to the given element, or       * Returns the least element in this set greater than or equal to
76       * <tt>null</tt> if there is no such element.       * the given element, or <tt>null</tt> if there is no such element.
77       *       *
78       * @param e the value to match       * @param e the value to match
79       * @return the greatest element less than or equal to given       * @return the least element greater than or equal to <tt>e</tt>,
80       * element, or <tt>null</tt> if there is no such element.       *         or <tt>null</tt> if there is no such element
81       * @throws ClassCastException if e cannot be compared with the elements       * @throws ClassCastException if the specified element cannot be
82       *            currently in the set.       *         compared with the elements currently in the set
83       * @throws NullPointerException if e is <tt>null</tt>.       * @throws NullPointerException if the specified element is null
84       * and this set does not permit <tt>null</tt> elements       *         and this set does not permit null elements
85       */       */
86      E floor(E e);      E ceiling(E e);
87    
88      /**      /**
89       * Returns an element strictly greater than the given element, or       * Returns the least element in this set strictly greater than the
90       * <tt>null</tt> if there is no such element.       * given element, or <tt>null</tt> if there is no such element.
91       *       *
92       * @param e the value to match       * @param e the value to match
93       * @return the least element greater than the given element, or       * @return the least element greater than <tt>e</tt>,
94       * <tt>null</tt> if there is no such element.       *         or <tt>null</tt> if there is no such element
95       * @throws ClassCastException if e cannot be compared with the elements       * @throws ClassCastException if the specified element cannot be
96       *            currently in the set.       *         compared with the elements currently in the set
97       * @throws NullPointerException if e is <tt>null</tt>       * @throws NullPointerException if the specified element is null
98       * and this set does not permit <tt>null</tt> elements       *         and this set does not permit null elements
99       */       */
100      E higher(E e);      E higher(E e);
101    
102      /**      /**
103       * Retrieves and removes the first (lowest) element.       * Retrieves and removes the first (lowest) element.
104       *       *
105       * @return the first element, or <tt>null</tt> if empty.       * @return the first element, or <tt>null</tt> if this set is empty
106       */       */
107      E pollFirst();      E pollFirst();
108    
109      /**      /**
110       * Retrieves and removes the last (highest) element.       * Retrieves and removes the last (highest) element.
111       *       *
112       * @return the last element, or <tt>null</tt> if empty.       * @return the last element, or <tt>null</tt> if this set is empty
113       */       */
114      E pollLast();      E pollLast();
115    
116      /**      /**
117       * Returns an iterator over the elements in this collection, in       * Returns an iterator over the elements in this set, in
118       * descending order.       * descending order.
119       *       *
120       * @return an <tt>Iterator</tt> over the elements in this collection       * @return an <tt>Iterator</tt> over the elements in this set
121       */       */
122      Iterator<E> descendingIterator();      Iterator<E> descendingIterator();
123    
# Line 125  Line 125 
125       * Returns a view of the portion of this set whose elements range       * Returns a view of the portion of this set whose elements range
126       * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,       * from <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,
127       * exclusive.  (If <tt>fromElement</tt> and <tt>toElement</tt> are       * exclusive.  (If <tt>fromElement</tt> and <tt>toElement</tt> are
128       * equal, the returned navigable set is empty.)  The returned       * equal, the returned set is empty.)  The returned set is backed
129       * navigable set is backed by this set, so changes in the returned       * by this set, so changes in the returned set are reflected in
130       * navigable set are reflected in this set, and vice-versa.       * this set, and vice-versa.  The returned set supports all
131         * optional set operations that this set supports.
132         *
133         * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
134         * on an attempt to insert an element outside its range.
135       *       *
136       * @param fromElement low endpoint (inclusive) of the subSet.       * @param fromElement low endpoint (inclusive) of the returned set
137       * @param toElement high endpoint (exclusive) of the subSet.       * @param toElement high endpoint (exclusive) of the returned set
138       * @return a view of the portion of this set whose elements range from       * @return a view of the portion of this set whose elements range from
139       *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>,       *         <tt>fromElement</tt>, inclusive, to <tt>toElement</tt>, exclusive
      *         exclusive.  
140       * @throws ClassCastException if <tt>fromElement</tt> and       * @throws ClassCastException if <tt>fromElement</tt> and
141       *         <tt>toElement</tt> cannot be compared to one another using       *         <tt>toElement</tt> cannot be compared to one another using this
142       *         this set's comparator (or, if the set has no comparator,       *         set's comparator (or, if the set has no comparator, using
143       *         using natural ordering).       *         natural ordering).  Implementations may, but are not required
144       * @throws IllegalArgumentException if <tt>fromElement</tt> is       *         to, throw this exception if <tt>fromElement</tt> or
145       * greater than <tt>toElement</tt>.       *         <tt>toElement</tt> cannot be compared to elements currently in
146         *         the set.
147       * @throws NullPointerException if <tt>fromElement</tt> or       * @throws NullPointerException if <tt>fromElement</tt> or
148       *         <tt>toElement</tt> is <tt>null</tt>       *         <tt>toElement</tt> is null and this set does
149       * and this set does not permit <tt>null</tt> elements       *         not permit null elements
150         * @throws IllegalArgumentException if <tt>fromElement</tt> is
151         *         greater than <tt>toElement</tt>; or if this set itself
152         *         has a restricted range, and <tt>fromElement</tt> or
153         *         <tt>toElement</tt> lies outside the bounds of the range.
154       */       */
155      NavigableSet<E> navigableSubSet(E fromElement, E toElement);      NavigableSet<E> navigableSubSet(E fromElement, E toElement);
156    
157      /**      /**
158       * Returns a view of the portion of this set whose elements are       * Returns a view of the portion of this set whose elements are
159       * strictly less than <tt>toElement</tt>.  The returned navigable       * strictly less than <tt>toElement</tt>.  The returned set is
160       * set is backed by this set, so changes in the returned navigable       * backed by this set, so changes in the returned set are
161       * set are reflected in this set, and vice-versa.       * reflected in this set, and vice-versa.  The returned set
162       * @param toElement high endpoint (exclusive) of the headSet.       * supports all optional set operations that this set supports.
163         *
164         * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
165         * on an attempt to insert an element outside its range.
166         *
167         * @param toElement high endpoint (exclusive) of the returned set
168       * @return a view of the portion of this set whose elements are strictly       * @return a view of the portion of this set whose elements are strictly
169       *         less than toElement.       *         less than <tt>toElement</tt>
170       * @throws ClassCastException if <tt>toElement</tt> is not compatible       * @throws ClassCastException if <tt>toElement</tt> is not compatible
171       *         with this set's comparator (or, if the set has no comparator,       *         with this set's comparator (or, if the set has no comparator,
172       *         if <tt>toElement</tt> does not implement <tt>Comparable</tt>).       *         if <tt>toElement</tt> does not implement {@link Comparable}).
173       * @throws NullPointerException if <tt>toElement</tt> is <tt>null</tt>       *         Implementations may, but are not required to, throw this
174       * and this set does not permit <tt>null</tt> elements       *         exception if <tt>toElement</tt> cannot be compared to elements
175         *         currently in the set.
176         * @throws NullPointerException if <tt>toElement</tt> is null and
177         *         this set does not permit null elements
178         * @throws IllegalArgumentException if this set itself has a
179         *         restricted range, and <tt>toElement</tt> lies outside the
180         *         bounds of the range
181       */       */
182      NavigableSet<E> navigableHeadSet(E toElement);      NavigableSet<E> navigableHeadSet(E toElement);
183    
184      /**      /**
185       * Returns a view of the portion of this set whose elements are       * Returns a view of the portion of this set whose elements are
186       * greater than or equal to <tt>fromElement</tt>.  The returned       * greater than or equal to <tt>fromElement</tt>.  The returned
187       * navigable set is backed by this set, so changes in the returned       * set is backed by this set, so changes in the returned set are
188       * navigable set are reflected in this set, and vice-versa.       * reflected in this set, and vice-versa.  The returned set
189       * @param fromElement low endpoint (inclusive) of the tailSet.       * supports all optional set operations that this set supports.
190       * @return a view of the portion of this set whose elements are       *
191       * greater than or equal to <tt>fromElement</tt>.       * <p>The returned set will throw an <tt>IllegalArgumentException</tt>
192       * @throws ClassCastException if <tt>fromElement</tt> is not       * on an attempt to insert an element outside its range.
193       * compatible with this set's comparator (or, if the set has no       *
194       * comparator, if <tt>fromElement</tt> does not implement       * @param fromElement low endpoint (inclusive) of the returned set
195       * <tt>Comparable</tt>).       * @return a view of the portion of this set whose elements are greater
196       * @throws NullPointerException if <tt>fromElement</tt> is <tt>null</tt>       *         than or equal to <tt>fromElement</tt>
197       * and this set does not permit <tt>null</tt> elements       * @throws ClassCastException if <tt>fromElement</tt> is not compatible
198         *         with this set's comparator (or, if the set has no comparator,
199         *         if <tt>fromElement</tt> does not implement {@link Comparable}).
200         *         Implementations may, but are not required to, throw this
201         *         exception if <tt>fromElement</tt> cannot be compared to elements
202         *         currently in the set.
203         * @throws NullPointerException if <tt>fromElement</tt> is null
204         *         and this set does not permit null elements
205         * @throws IllegalArgumentException if this set itself has a
206         *         restricted range, and <tt>fromElement</tt> lies outside the
207         *         bounds of the range
208       */       */
209      NavigableSet<E> navigableTailSet(E fromElement);      NavigableSet<E> navigableTailSet(E fromElement);
210  }  }

Legend:
Removed from v.1.8  
changed lines
  Added in v.1.9

Doug Lea
ViewVC Help
Powered by ViewVC 1.0.8