From 41878ce27efa7dac17cc1f3b283303cd6bbedd1e Mon Sep 17 00:00:00 2001 From: Bryce McKinlay Date: Tue, 16 Oct 2001 06:47:01 +0100 Subject: [multiple changes] 2001-10-15 Bryce McKinlay * java/util/HashMap.java (HashEntry.clone): Removed. (HashMap(Map)): Use putAllInternal. (clone): Likewise. (putAllInternal): New method. Efficient counterpart to putAll which does not call put(). * java/util/LinkedHashMap.java (rethread): Removed. (putAllInternal): New method. Clear "head" and "tail". (addEntry): New argument "callRemove". Don't call removeEldestEntry() if callRemove == false. * Makefile.am: Add new classes RandomAccess and LinkedHashMap. * Makefile.in: Rebuilt. 2001-10-15 Eric Blake * java/util/Collection.java: Updated javadoc. * java/util/Comparator.java: Updated javadoc. * java/util/Enumeration.java: Updated javadoc. * java/util/Iterator.java: Updated javadoc. * java/util/List.java: Updated javadoc. * java/util/ListIterator.java: Updated javadoc. * java/util/Map.java: Updated javadoc. * java/util/RandomAccess.java: New file. * java/util/Set.java: Updated javadoc. * java/util/SortedMap.java: Updated javadoc. * java/util/SortedSet.java: Updated javadoc. From-SVN: r46277 --- libjava/java/util/SortedMap.java | 126 +++++++++++++++++++++++++++++++++++++-- 1 file changed, 122 insertions(+), 4 deletions(-) (limited to 'libjava/java/util/SortedMap.java') diff --git a/libjava/java/util/SortedMap.java b/libjava/java/util/SortedMap.java index 2de57a175ac..5be6c19d919 100644 --- a/libjava/java/util/SortedMap.java +++ b/libjava/java/util/SortedMap.java @@ -1,5 +1,5 @@ /* SortedMap.java -- A map that makes guarantees about the order of its keys - Copyright (C) 1998 Free Software Foundation, Inc. + Copyright (C) 1998, 2001 Free Software Foundation, Inc. This file is part of GNU Classpath. @@ -25,17 +25,135 @@ This exception does not however invalidate any other reasons why the executable file might be covered by the GNU General Public License. */ -// TO DO: -// ~ Doc comments for everything. - package java.util; +/** + * A map which guarantees its key's iteration order. The entries in the + * map are related by the natural ordering of the keys if they + * are Comparable, or by the provided Comparator. Additional operations + * take advantage of the sorted nature of the map. + *

+ * + * All keys entered in the map must be mutually comparable; in other words, + * k1.compareTo(k2) or comparator.compare(k1, k2) + * must not throw a ClassCastException. The ordering must be consistent + * with equals (see {@link Comparator} for this definition), if the + * map is to obey the general contract of the Map interface. If not, + * the results are well-defined, but probably not what you wanted. + *

+ * + * It is recommended that all implementing classes provide four constructors: + * 1) one that takes no arguments and builds an empty map sorted by natural + * order of the keys; 2) one that takes a Comparator for the sorting order; + * 3) one that takes a Map and sorts according to the natural order of its + * keys; and 4) one that takes a SortedMap and sorts by the same comparator. + * Unfortunately, the Java language does not provide a way to enforce this. + * + * @author Original author unknown + * @author Eric Blake + * @see Map + * @see TreeMap + * @see SortedSet + * @see Comparable + * @see Comparator + * @see Collection + * @see ClassCastException + * @since 1.2 + * @status updated to 1.4 + */ public interface SortedMap extends Map { + /** + * Returns the comparator used in sorting this map, or null if it is + * the keys' natural ordering. + * + * @return the sorting comparator + */ Comparator comparator(); + + /** + * Returns the first (lowest sorted) key in the map. + * + * @return the first key + */ Object firstKey(); + + /** + * Returns a view of the portion of the map strictly less than toKey. The + * view is backed by this map, so changes in one show up in the other. + * The submap supports all optional operations of the original. + *

+ * + * The returned map throws an IllegalArgumentException any time a key is + * used which is out of the range of toKey. Note that the endpoint is not + * included; if you want the endpoint, pass the successor object in to + * toKey. For example, for Strings, you can request + * headMap(limit + "\0"). + * + * @param toKey the exclusive upper range of the submap + * @return the submap + * @throws ClassCastException if toKey is not comparable to the map contents + * @throws IllegalArgumentException if this is a subMap, and toKey is out + * of range + * @throws NullPointerException if toKey is null but the map does not allow + * null keys + */ SortedMap headMap(Object toKey); + + /** + * Returns the last (highest sorted) key in the map. + * + * @return the last key + */ Object lastKey(); + + /** + * Returns a view of the portion of the map greater than or equal to + * fromKey, and strictly less than toKey. The view is backed by this map, + * so changes in one show up in the other. The submap supports all + * optional operations of the original. + *

+ * + * The returned map throws an IllegalArgumentException any time a key is + * used which is out of the range of fromKey and toKey. Note that the + * lower endpoint is included, but the upper is not; if you want to + * change the inclusion or exclusion of an endpoint, pass the successor + * object in instead. For example, for Strings, you can request + * subMap(lowlimit + "\0", highlimit + "\0") to reverse + * the inclusiveness of both endpoints. + * + * @param fromKey the inclusive lower range of the submap + * @param toKey the exclusive upper range of the submap + * @return the submap + * @throws ClassCastException if fromKey or toKey is not comparable to + * the map contents + * @throws IllegalArgumentException if this is a subMap, and fromKey or + * toKey is out of range + * @throws NullPointerException if fromKey or toKey is null but the map + * does not allow null keys + */ SortedMap subMap(Object fromKey, Object toKey); + + /** + * Returns a view of the portion of the map greater than or equal to + * fromKey. The view is backed by this map, so changes in one show up + * in the other. The submap supports all optional operations of the original. + *

+ * + * The returned map throws an IllegalArgumentException any time a key is + * used which is out of the range of fromKey. Note that the endpoint is + * included; if you do not want the endpoint, pass the successor object in + * to fromKey. For example, for Strings, you can request + * tailMap(limit + "\0"). + * + * @param fromKey the inclusive lower range of the submap + * @return the submap + * @throws ClassCastException if fromKey is not comparable to the map + * contents + * @throws IllegalArgumentException if this is a subMap, and fromKey is out + * of range + * @throws NullPointerException if fromKey is null but the map does not allow + * null keys + */ SortedMap tailMap(Object fromKey); } -- cgit v1.2.3