--- jsr166/src/jsr166x/NavigableSet.java 2004/09/07 11:37:57 1.2 +++ jsr166/src/jsr166x/NavigableSet.java 2004/12/21 17:27:44 1.3 @@ -13,14 +13,17 @@ import java.util.*; * floor, ceiling, and higher return keys * respectively less than, less than or equal, greater than or equal, * and greater than a given key, returning null if there is - * no such key. These methods are designed for locating, not - * traversing entries. To traverse, use view iterators and/or - * subset. This interface additionally defines methods - * pollFirst and pollLast that return and remove the - * lowest and highest key, if one exists, else returning - * null. + * no such key. A NavigableSet may be viewed and traversed + * in either ascending or descending order. The Collection + * iterator method returns an ascending Iterator and + * the additional method descendingIterator returns + * descending iterator. The performance of ascending traversals is + * likely to be faster than descending traversals. This interface + * additionally defines methods pollFirst and + * pollLast that return and remove the lowest and highest key, + * if one exists, else returning null. * - *

The return values of these methods may be ambiguous in + *

The return values of navigation methods may be ambiguous in * implementations that permit null elements. However, even * in this case the result can be disambiguated by checking * contains(null). To avoid such issues, implementations of @@ -103,6 +106,14 @@ public interface NavigableSet extends public E pollLast(); /** + * Returns an iterator over the elements in this collection, in + * descending order. + * + * @return an Iterator over the elements in this collection + */ + Iterator descendingIterator(); + + /** * Returns a view of the portion of this set whose elements range from * fromElement, inclusive, to toElement, exclusive. (If * fromElement and toElement are equal, the returned