ViewVC Help
View File | Revision Log | Show Annotations | Download File | Root Listing
root/jsr166/jsr166/src/jsr166x/NavigableMap.java
(Generate patch)

Comparing jsr166/src/jsr166x/NavigableMap.java (file contents):
Revision 1.1 by dl, Mon Sep 6 17:01:54 2004 UTC vs.
Revision 1.2 by dl, Tue Sep 7 11:37:57 2004 UTC

# Line 9 | Line 9 | package jsr166x;
9   import java.util.*;
10  
11   /**
12 < * A {@link SortedMap} extended with methods returning key-value pairs
13 < * holding the closest matches for given search targets. Methods
14 < * <tt>lowerEntry</tt>, <tt>floorEntry</tt>, <tt>ceilingEntry</tt>,
15 < * and <tt>higherEntry</tt> return {@link Map.Entry} objects
16 < * associated with keys respectively less than, less than or equal,
17 < * greater than or equal, and greater than a given key, returning
18 < * <tt>null</tt> if there is no such key.  These methods are designed
19 < * for locating, not traversing entries. To traverse, use view
20 < * iterators and/or <tt>submap</tt>. This interface additionally
21 < * defines methods <tt>firstEntry</tt>, <tt>pollFirstEntry</tt>
22 < * <tt>lastEntry</tt>, and <tt>pollLastEntry</tt> that return and/or
23 < * remove the least and greatest mappings, if any exist, else
24 < * returning <tt>null</tt>.
12 > * A {@link SortedMap} extended with navigation methods returning
13 > * key-value pairs holding the closest matches for given search
14 > * targets. Methods <tt>lowerEntry</tt>, <tt>floorEntry</tt>,
15 > * <tt>ceilingEntry</tt>, and <tt>higherEntry</tt> return
16 > * <tt>Map.Entry</tt> objects associated with keys respectively less
17 > * than, less than or equal, greater than or equal, and greater than a
18 > * given key, returning <tt>null</tt> if there is no such key.  These
19 > * methods are designed for locating, not traversing entries. To
20 > * traverse, use view iterators and/or <tt>submap</tt>. This interface
21 > * additionally defines methods <tt>firstEntry</tt>,
22 > * <tt>pollFirstEntry</tt>, <tt>lastEntry</tt>, and
23 > * <tt>pollLastEntry</tt> that return and/or remove the least and
24 > * greatest mappings, if any exist, else returning <tt>null</tt>.
25   *
26   * <p> Implementations of these methods are expected to return
27   * <tt>Map.Entry</tt> pairs representing snapshots of mappings at the
# Line 37 | Line 37 | import java.util.*;
37   public interface NavigableMap<K,V> extends SortedMap<K,V> {
38      /**
39       * Returns a key-value mapping associated with the least key
40 <     * greater than or equal to the given key, or null if there is
40 >     * greater than or equal to the given key, or <tt>null</tt> if there is
41       * no such entry.
42       *
43       * @param key the key.
44 <     * @return an Entry associated with ceiling of given key, or null
44 >     * @return an Entry associated with ceiling of given key, or <tt>null</tt>
45       * if there is no such Entry.
46       * @throws ClassCastException if key cannot be compared with the keys
47       *            currently in the map.
# Line 52 | Line 52 | public interface NavigableMap<K,V> exten
52  
53      /**
54       * Returns a key-value mapping associated with the greatest
55 <     * key strictly less than the given key, or null if there is no
55 >     * key strictly less than the given key, or <tt>null</tt> if there is no
56       * such entry.
57       *
58       * @param key the key.
59       * @return an Entry with greatest key less than the given
60 <     * key, or null if there is no such Entry.
60 >     * key, or <tt>null</tt> if there is no such Entry.
61       * @throws ClassCastException if key cannot be compared with the keys
62       *            currently in the map.
63       * @throws NullPointerException if key is <tt>null</tt> and this map
# Line 67 | Line 67 | public interface NavigableMap<K,V> exten
67  
68      /**
69       * Returns a key-value mapping associated with the greatest
70 <     * key less than or equal to the given key, or null if there is no
70 >     * key less than or equal to the given key, or <tt>null</tt> if there is no
71       * such entry.
72       *
73       * @param key the key.
74 <     * @return an Entry associated with floor of given key, or null
74 >     * @return an Entry associated with floor of given key, or <tt>null</tt>
75       * if there is no such Entry.
76       * @throws ClassCastException if key cannot be compared with the keys
77       *            currently in the map.
# Line 82 | Line 82 | public interface NavigableMap<K,V> exten
82  
83      /**
84       * Returns a key-value mapping associated with the least
85 <     * key strictly greater than the given key, or null if there is no
85 >     * key strictly greater than the given key, or <tt>null</tt> if there is no
86       * such entry.
87       *
88       * @param key the key.
89       * @return an Entry with least key greater than the given key, or
90 <     * null if there is no such Entry.
90 >     * <tt>null</tt> if there is no such Entry.
91       * @throws ClassCastException if key cannot be compared with the keys
92       *            currently in the map.
93       * @throws NullPointerException if key is <tt>null</tt> and this map
# Line 97 | Line 97 | public interface NavigableMap<K,V> exten
97  
98      /**
99       * Returns a key-value mapping associated with the least
100 <     * key in this map, or null if the map is empty.
100 >     * key in this map, or <tt>null</tt> if the map is empty.
101       *
102 <     * @return an Entry with least key, or null
102 >     * @return an Entry with least key, or <tt>null</tt>
103       * if the map is empty.
104       */
105      public Map.Entry<K,V> firstEntry();
106  
107      /**
108       * Returns a key-value mapping associated with the greatest
109 <     * key in this map, or null if the map is empty.
109 >     * key in this map, or <tt>null</tt> if the map is empty.
110       *
111 <     * @return an Entry with greatest key, or null
111 >     * @return an Entry with greatest key, or <tt>null</tt>
112       * if the map is empty.
113       */
114      public Map.Entry<K,V> lastEntry();
115  
116      /**
117       * Removes and returns a key-value mapping associated with
118 <     * the least key in this map, or null if the map is empty.
118 >     * the least key in this map, or <tt>null</tt> if the map is empty.
119       *
120 <     * @return the removed first entry of this map, or null
120 >     * @return the removed first entry of this map, or <tt>null</tt>
121       * if the map is empty.
122       */
123      public Map.Entry<K,V> pollFirstEntry();
124  
125      /**
126       * Removes and returns a key-value mapping associated with
127 <     * the greatest key in this map, or null if the map is empty.
127 >     * the greatest key in this map, or <tt>null</tt> if the map is empty.
128       *
129 <     * @return the removed last entry of this map, or null
129 >     * @return the removed last entry of this map, or <tt>null</tt>
130       * if the map is empty.
131       */
132      public Map.Entry<K,V> pollLastEntry();

Diff Legend

– Removed lines
+ Added lines
< Changed lines
> Changed lines