/[classpath]/classpath/java/util/Map.java
ViewVC logotype

Diff of /classpath/java/util/Map.java

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

revision 1.7 by bryce, Thu Oct 26 10:19:01 2000 UTC revision 1.8 by ericb, Mon Oct 15 14:53:51 2001 UTC
# Line 1  Line 1 
1  /* Map.java -- An object that maps keys to values  /* Map.java: interface Map -- An object that maps keys to values
2     Copyright (C) 1998 Free Software Foundation, Inc.               interface Map.Entry -- an Entry in a Map
3       Copyright (C) 1998, 2001 Free Software Foundation, Inc.
4    
5  This file is part of GNU Classpath.  This file is part of GNU Classpath.
6    
# Line 25  This exception does not however invalida Line 26  This exception does not however invalida
26  executable file might be covered by the GNU General Public License. */  executable file might be covered by the GNU General Public License. */
27    
28    
 // TO DO:  
 // ~ Doc comments for everything.  
   
29  package java.util;  package java.util;
30    
31    /**
32     * An object that maps keys onto values. Keys cannot be duplicated. This
33     * interface replaces the obsolete {@link Dictionary} abstract class.
34     * <p>
35     *
36     * The map has three collection views, which are backed by the map
37     * (modifications on one show up on the other): a set of keys, a collection
38     * of values, and a set of key-value mappings. Some maps have a guaranteed
39     * order, but not all do.
40     * <p>
41     *
42     * Note: Be careful about using mutable keys.  Behavior is unspecified if
43     * a key's comparison behavior is changed after the fact.  As a corollary
44     * to this rule, don't use a Map as one of its own keys or values, as it makes
45     * hashCode and equals have undefined behavior.
46     * <p>
47     *
48     * All maps are recommended to provide a no argument constructor, which builds
49     * an empty map, and one that accepts a Map parameter and copies the mappings
50     * (usually by putAll), to create an equivalent map.  Unfortunately, Java
51     * cannot enforce these suggestions.
52     * <p>
53     *
54     * The map may be unmodifiable, in which case unsupported operations will
55     * throw an UnsupportedOperationException.  Note that some operations may be
56     * safe, such as putAll(m) where m is empty, even if the operation would
57     * normally fail with a non-empty argument.
58     *
59     * @author Original author unknown
60     * @author Eric Blake <ebb9@email.byu.edu>
61     * @see HashMap
62     * @see TreeMap
63     * @see Hashtable
64     * @see SortedMap
65     * @see Collection
66     * @see Set
67     * @since 1.2
68     * @status updated to 1.4
69     */
70  public interface Map  public interface Map
71  {  {
72      /**
73       * Remove all entries from this Map (optional operation).
74       *
75       * @throws UnsupportedOperationException if clear is not supported
76       */
77    public void clear();    public void clear();
78    
79      /**
80       * Returns true if this contains a mapping for the given key.
81       *
82       * @param key the key to search for
83       * @return true if the map contains the key
84       * @throws ClassCastException if the key is of an inappropriate type
85       * @throws NullPointerException if key is <code>null</code> but the map
86       *         does not permit null keys
87       */
88    public boolean containsKey(Object key);    public boolean containsKey(Object key);
89    
90      /**
91       * Returns true if this contains at least one mapping with the given value.
92       * In other words, returns true if a value v exists where
93       * <code>(value == null ? v == null : value.equals(v))</code>. This usually
94       * requires linear time.
95       *
96       * @param value the value to search for
97       * @return true if the map contains the value
98       */
99    public boolean containsValue(Object value);    public boolean containsValue(Object value);
100    
101      /**
102       * Returns a set view of the mappings in this Map.  Each element in the
103       * set is a Map.Entry.  The set is backed by the map, so that changes in
104       * one show up in the other.  Modifications made while an iterator is
105       * in progress cause undefined behavior.  If the set supports removal,
106       * these methods remove the underlying mapping from the map:
107       * <code>Iterator.remove</code>, <code>Set.remove</code>,
108       * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
109       * Element addition, via <code>add</code> or <code>addAll</code>, is
110       * not supported via this set.
111       *
112       * @return the set view of all mapping entries
113       * @see Map.Entry
114       */
115    public Set entrySet();    public Set entrySet();
116    
117      /**
118       * Compares the specified object with this map for equality. Returns
119       * <code>true</code> if the other object is a Map with the same mappings,
120       * that is,<br>
121       * <code>o instanceof Map && entrySet().equals(((Map) o).entrySet();</code>
122       * This allows comparison of maps, regardless of implementation.
123       *
124       * @param o the object to be compared
125       * @return true if the object equals this map
126       * @see Set#equals(Object)
127       */
128    public boolean equals(Object o);    public boolean equals(Object o);
129    
130      /**
131       * Returns the value mapped by the given key. Returns <code>null</code> if
132       * there is no mapping.  However, in Maps that accept null values, you
133       * must rely on <code>containsKey</code> to determine if a mapping exists.
134       *
135       * @param key the key to look up
136       * @return the value associated with the key, or null if key not in map
137       * @throws ClassCastException if the key is an inappropriate type
138       * @throws NullPointerException if this map does not accept null keys
139       * @see #containsKey(Object)
140       */
141    public Object get(Object key);    public Object get(Object key);
142    
143      /**
144       * Associates the given key to the given value (optional operation). If the
145       * map already contains the key, its value is replaced. Be aware that in
146       * a map that permits <code>null</code> values, a null return does not
147       * always imply that the mapping was created.
148       *
149       * @param key the key to map
150       * @param value the value to be mapped
151       * @return the previous value of the key, or null if there was no mapping
152       * @throws UnsupportedOperationException if the operation is not supported
153       * @throws ClassCastException if the key or value is of the wrong type
154       * @throws IllegalArgumentException if something about this key or value
155       *         prevents it from existing in this map
156       * @throws NullPointerException if the map forbids null keys or values
157       * @see #containsKey(Object)
158       */
159    public Object put(Object key, Object value);    public Object put(Object key, Object value);
160    
161      /**
162       * Returns the hash code for this map. This is the sum of all hashcodes
163       * for each Map.Entry object in entrySet.  This allows comparison of maps,
164       * regardless of implementation, and satisfies the contract of
165       * Object.hashCode.
166       *
167       * @return the hash code
168       * @see Map.Entry#hashCode()
169       */
170    public int hashCode();    public int hashCode();
171    
172      /**
173       * Returns true if the map contains no mappings.
174       *
175       * @return true if the map is empty
176       */
177    public boolean isEmpty();    public boolean isEmpty();
178    
179      /**
180       * Returns a set view of the keys in this Map.  The set is backed by the
181       * map, so that changes in one show up in the other.  Modifications made
182       * while an iterator is in progress cause undefined behavior.  If the set
183       * supports removal, these methods remove the underlying mapping from
184       * the map: <code>Iterator.remove</code>, <code>Set.remove</code>,
185       * <code>removeAll</code>, <code>retainAll</code>, and <code>clear</code>.
186       * Element addition, via <code>add</code> or <code>addAll</code>, is
187       * not supported via this set.
188       *
189       * @return the set view of all keys
190       */
191    public Set keySet();    public Set keySet();
192    
193      /**
194       * Copies all entries of the given map to this one (optional operation). If
195       * the map already contains a key, its value is replaced.
196       *
197       * @param m the mapping to load into this map
198       * @throws UnsupportedOperationException if the operation is not supported
199       * @throws ClassCastException if a key or value is of the wrong type
200       * @throws IllegalArgumentException if something about a key or value
201       *         prevents it from existing in this map
202       * @throws NullPointerException if the map forbids null keys or values, or
203       *         if <code>m</code> is null.
204       * @see #put(Object, Object)
205       */
206    public void putAll(Map m);    public void putAll(Map m);
207    
208      /**
209       * Removes the mapping for this key if present (optional operation). If
210       * the key is not present, this returns null. Note that maps which permit
211       * null values may also return null if the key was removed.
212       *
213       * @param key the key to remove
214       * @return the value the key mapped to, or null if not present
215       * @throws UnsupportedOperationException if deletion is unsupported
216       */
217    public Object remove(Object o);    public Object remove(Object o);
218    
219      /**
220       * Returns the number of key-value mappings in the map. If there are more
221       * than Integer.MAX_VALUE mappings, return Integer.MAX_VALUE.
222       *
223       * @return the number of mappings
224       */
225    public int size();    public int size();
226    
227      /**
228       * Returns a collection (or bag) view of the values in this Map.  The
229       * collection is backed by the map, so that changes in one show up in
230       * the other.  Modifications made while an iterator is in progress cause
231       * undefined behavior.  If the collection supports removal, these methods
232       * remove the underlying mapping from the map: <code>Iterator.remove</code>,
233       * <code>Collection.remove</code>, <code>removeAll</code>,
234       * <code>retainAll</code>, and <code>clear</code>. Element addition, via
235       * <code>add</code> or <code>addAll</code>, is not supported via this
236       * collection.
237       *
238       * @return the collection view of all values
239       */
240    public Collection values();    public Collection values();
241    
242      /**
243       * A map entry (key-value pair). The Map.entrySet() method returns a set
244       * view of these objects; there is no other valid way to come across them.
245       * These objects are only valid for the duration of an iteration; in other
246       * words, if you mess with one after modifying the map, you are asking
247       * for undefined behavior.
248       *
249       * @author Original author unknown
250       * @author Eric Blake <ebb9@email.byu.edu>
251       * @see Map
252       * @see Map#entrySet()
253       * @since 1.2
254       * @status updated to 1.4
255       */
256    public static interface Entry    public static interface Entry
257    {    {
258        /**
259         * Get the key corresponding to this entry.
260         *
261         * @return the key
262         */
263      public Object getKey();      public Object getKey();
264    
265        /**
266         * Get the value corresponding to this entry. If you already called
267         * Iterator.remove(), this is undefined.
268         *
269         * @return the value
270         */
271      public Object getValue();      public Object getValue();
272    
273        /**
274         * Replaces the value with the specified object (optional operation).
275         * This writes through to the map, and is undefined if you already
276         * called Iterator.remove().
277         *
278         * @param value the new value to store
279         * @return the old value
280         * @throws UnsupportedOperationException if the operation is not supported
281         * @throws ClassCastException if the value is of the wrong type
282         * @throws IllegalArgumentException if something about the value
283         *         prevents it from existing in this map
284         * @throws NullPointerException if the map forbids null values
285         */
286      public Object setValue(Object value);      public Object setValue(Object value);
287    
288        /**
289         * Returns the hash code of the entry.  This is defined as the exclusive-or
290         * of the hashcodes of the key and value (using 0 for null). In other
291         * words, this must be:
292         * <pre>
293         *  (getKey() == null ? 0 : getKey().hashCode()) ^
294         *  (getValue() == null ? 0 : getValue().hashCode())
295         * </pre>
296         *
297         * @return the hash code
298         */
299      public int hashCode();      public int hashCode();
300    
301        /**
302         * Compares the specified object with this entry. Returns true only if
303         * the object is a mapping of identical key and value. In other words,
304         * this must be:
305         * <pre>
306         * (o instanceof Map.Entry)
307         * && (getKey() == null ? ((HashMap) o).getKey() == null
308         *                      : getKey().equals(((HashMap) o).getKey()))
309         * && (getValue() == null ? ((HashMap) o).getValue() == null
310         *                        : getValue().equals(((HashMap) o).getValue()))
311         * </pre>
312         *
313         * @param o the object to compare
314         * @return true if it is equal
315         */
316      public boolean equals(Object o);      public boolean equals(Object o);
317    }    }
318  }  }

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

savannah-hackers-public@gnu.org
ViewVC Help
Powered by ViewVC 1.1.26