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

Diff of /classpath/java/util/SortedMap.java

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

revision 1.4 by bryce, Thu Oct 26 10:19:01 2000 UTC revision 1.5 by ericb, Mon Oct 15 14:53:51 2001 UTC
# Line 1  Line 1 
1  /* SortedMap.java -- A map that makes guarantees about the order of its keys  /* SortedMap.java -- A map that makes guarantees about the order of its keys
2     Copyright (C) 1998 Free Software Foundation, Inc.     Copyright (C) 1998, 2001 Free Software Foundation, Inc.
3    
4  This file is part of GNU Classpath.  This file is part of GNU Classpath.
5    
# Line 25  This exception does not however invalida Line 25  This exception does not however invalida
25  executable file might be covered by the GNU General Public License. */  executable file might be covered by the GNU General Public License. */
26    
27    
 // TO DO:  
 // ~ Doc comments for everything.  
   
28  package java.util;  package java.util;
29    
30    /**
31     * A map which guarantees its key's iteration order. The entries in the
32     * map are related by the <i>natural ordering</i> of the keys if they
33     * are Comparable, or by the provided Comparator.  Additional operations
34     * take advantage of the sorted nature of the map.
35     * <p>
36     *
37     * All keys entered in the map must be mutually comparable; in other words,
38     * <code>k1.compareTo(k2)</code> or <code>comparator.compare(k1, k2)</code>
39     * must not throw a ClassCastException. The ordering must be <i>consistent
40     * with equals</i> (see {@link Comparator} for this definition), if the
41     * map is to obey the general contract of the Map interface.  If not,
42     * the results are well-defined, but probably not what you wanted.
43     * <p>
44     *
45     * It is recommended that all implementing classes provide four constructors:
46     * 1) one that takes no arguments and builds an empty map sorted by natural
47     * order of the keys; 2) one that takes a Comparator for the sorting order;
48     * 3) one that takes a Map and sorts according to the natural order of its
49     * keys; and 4) one that takes a SortedMap and sorts by the same comparator.
50     * Unfortunately, the Java language does not provide a way to enforce this.
51     *
52     * @author Original author unknown
53     * @author Eric Blake <ebb9@email.byu.edu>
54     * @see Map
55     * @see TreeMap
56     * @see SortedSet
57     * @see Comparable
58     * @see Comparator
59     * @see Collection
60     * @see ClassCastException
61     * @since 1.2
62     * @status updated to 1.4
63     */
64  public interface SortedMap extends Map  public interface SortedMap extends Map
65  {  {
66      /**
67       * Returns the comparator used in sorting this map, or null if it is
68       * the keys' natural ordering.
69       *
70       * @return the sorting comparator
71       */
72    Comparator comparator();    Comparator comparator();
73    
74      /**
75       * Returns the first (lowest sorted) key in the map.
76       *
77       * @return the first key
78       */
79    Object firstKey();    Object firstKey();
80    
81      /**
82       * Returns a view of the portion of the map strictly less than toKey. The
83       * view is backed by this map, so changes in one show up in the other.
84       * The submap supports all optional operations of the original.
85       * <p>
86       *
87       * The returned map throws an IllegalArgumentException any time a key is
88       * used which is out of the range of toKey. Note that the endpoint is not
89       * included; if you want the endpoint, pass the successor object in to
90       * toKey.  For example, for Strings, you can request
91       * <code>headMap(limit + "\0")</code>.
92       *
93       * @param toKey the exclusive upper range of the submap
94       * @return the submap
95       * @throws ClassCastException if toKey is not comparable to the map contents
96       * @throws IllegalArgumentException if this is a subMap, and toKey is out
97       *         of range
98       * @throws NullPointerException if toKey is null but the map does not allow
99       *         null keys
100       */
101    SortedMap headMap(Object toKey);    SortedMap headMap(Object toKey);
102    
103      /**
104       * Returns the last (highest sorted) key in the map.
105       *
106       * @return the last key
107       */
108    Object lastKey();    Object lastKey();
109    
110      /**
111       * Returns a view of the portion of the map greater than or equal to
112       * fromKey, and strictly less than toKey. The view is backed by this map,
113       * so changes in one show up in the other. The submap supports all
114       * optional operations of the original.
115       * <p>
116       *
117       * The returned map throws an IllegalArgumentException any time a key is
118       * used which is out of the range of fromKey and toKey. Note that the
119       * lower endpoint is included, but the upper is not; if you want to
120       * change the inclusion or exclusion of an endpoint, pass the successor
121       * object in instead.  For example, for Strings, you can request
122       * <code>subMap(lowlimit + "\0", highlimit + "\0")</code> to reverse
123       * the inclusiveness of both endpoints.
124       *
125       * @param fromKey the inclusive lower range of the submap
126       * @param toKey the exclusive upper range of the submap
127       * @return the submap
128       * @throws ClassCastException if fromKey or toKey is not comparable to
129       *         the map contents
130       * @throws IllegalArgumentException if this is a subMap, and fromKey or
131       *         toKey is out of range
132       * @throws NullPointerException if fromKey or toKey is null but the map
133       *         does not allow null keys
134       */
135    SortedMap subMap(Object fromKey, Object toKey);    SortedMap subMap(Object fromKey, Object toKey);
136    
137      /**
138       * Returns a view of the portion of the map greater than or equal to
139       * fromKey. The view is backed by this map, so changes in one show up
140       * in the other. The submap supports all optional operations of the original.
141       * <p>
142       *
143       * The returned map throws an IllegalArgumentException any time a key is
144       * used which is out of the range of fromKey. Note that the endpoint is
145       * included; if you do not want the endpoint, pass the successor object in
146       * to fromKey.  For example, for Strings, you can request
147       * <code>tailMap(limit + "\0")</code>.
148       *
149       * @param fromKey the inclusive lower range of the submap
150       * @return the submap
151       * @throws ClassCastException if fromKey is not comparable to the map
152       *         contents
153       * @throws IllegalArgumentException if this is a subMap, and fromKey is out
154       *         of range
155       * @throws NullPointerException if fromKey is null but the map does not allow
156       *         null keys
157       */
158    SortedMap tailMap(Object fromKey);    SortedMap tailMap(Object fromKey);
159  }  }

Legend:
Removed from v.1.4  
changed lines
  Added in v.1.5

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