diff --git a/src/share/classes/java/util/TreeMap.java b/src/share/classes/java/util/TreeMap.java index 884905014b3917bfc98f43e224c3625d80222c54..b0c9aa7d67a781c473e38c1576bbcaf8b8962eb6 100644 --- a/src/share/classes/java/util/TreeMap.java +++ b/src/share/classes/java/util/TreeMap.java @@ -32,25 +32,26 @@ package java.util; * creation time, depending on which constructor is used. * *

This implementation provides guaranteed log(n) time cost for the - * containsKey, get, put and remove + * {@code containsKey}, {@code get}, {@code put} and {@code remove} * operations. Algorithms are adaptations of those in Cormen, Leiserson, and - * Rivest's Introduction to Algorithms. + * Rivest's Introduction to Algorithms. * - *

Note that the ordering maintained by a sorted map (whether or not an - * explicit comparator is provided) must be consistent with equals if - * this sorted map is to correctly implement the Map interface. (See - * Comparable or Comparator for a precise definition of - * consistent with equals.) This is so because the Map - * interface is defined in terms of the equals operation, but a map performs - * all key comparisons using its compareTo (or compare) - * method, so two keys that are deemed equal by this method are, from the - * standpoint of the sorted map, equal. The behavior of a sorted map - * is well-defined even if its ordering is inconsistent with equals; it - * just fails to obey the general contract of the Map interface. + *

Note that the ordering maintained by a tree map, like any sorted map, and + * whether or not an explicit comparator is provided, must be consistent + * with {@code equals} if this sorted map is to correctly implement the + * {@code Map} interface. (See {@code Comparable} or {@code Comparator} for a + * precise definition of consistent with equals.) This is so because + * the {@code Map} interface is defined in terms of the {@code equals} + * operation, but a sorted map performs all key comparisons using its {@code + * compareTo} (or {@code compare}) method, so two keys that are deemed equal by + * this method are, from the standpoint of the sorted map, equal. The behavior + * of a sorted map is well-defined even if its ordering is + * inconsistent with {@code equals}; it just fails to obey the general contract + * of the {@code Map} interface. * *

Note that this implementation is not synchronized. * If multiple threads access a map concurrently, and at least one of the - * threads modifies the map structurally, it must be synchronized + * threads modifies the map structurally, it must be synchronized * externally. (A structural modification is any operation that adds or * deletes one or more mappings; merely changing the value associated * with an existing key is not a structural modification.) This is @@ -62,11 +63,11 @@ package java.util; * unsynchronized access to the map: 

  *   SortedMap m = Collections.synchronizedSortedMap(new TreeMap(...));
* - *

The iterators returned by the iterator method of the collections + *

The iterators returned by the {@code iterator} method of the collections * returned by all of this class's "collection view methods" are - * fail-fast: if the map is structurally modified at any time after the - * iterator is created, in any way except through the iterator's own - * remove method, the iterator will throw a {@link + * fail-fast: if the map is structurally modified at any time after + * the iterator is created, in any way except through the iterator's own + * {@code remove} method, the iterator will throw a {@link * ConcurrentModificationException}. Thus, in the face of concurrent * modification, the iterator fails quickly and cleanly, rather than risking * arbitrary, non-deterministic behavior at an undetermined time in the future. @@ -74,16 +75,16 @@ package java.util; *

Note that the fail-fast behavior of an iterator cannot be guaranteed * as it is, generally speaking, impossible to make any hard guarantees in the * presence of unsynchronized concurrent modification. Fail-fast iterators - * throw ConcurrentModificationException on a best-effort basis. + * throw {@code ConcurrentModificationException} on a best-effort basis. * Therefore, it would be wrong to write a program that depended on this - * exception for its correctness: the fail-fast behavior of iterators - * should be used only to detect bugs. + * exception for its correctness: the fail-fast behavior of iterators + * should be used only to detect bugs. * - *

All Map.Entry pairs returned by methods in this class + *

All {@code Map.Entry} pairs returned by methods in this class * and its views represent snapshots of mappings at the time they were - * produced. They do not support the Entry.setValue + * produced. They do not support the {@code Entry.setValue} * method. (Note however that it is possible to change mappings in the - * associated map using put.) + * associated map using {@code put}.) * *

This class is a member of the * @@ -130,13 +131,13 @@ public class TreeMap * Constructs a new, empty tree map, using the natural ordering of its * keys. All keys inserted into the map must implement the {@link * Comparable} interface. Furthermore, all such keys must be - * mutually comparable: k1.compareTo(k2) must not throw - * a ClassCastException for any keys k1 and - * k2 in the map. If the user attempts to put a key into the + * mutually comparable: {@code k1.compareTo(k2)} must not throw + * a {@code ClassCastException} for any keys {@code k1} and + * {@code k2} in the map. If the user attempts to put a key into the * map that violates this constraint (for example, the user attempts to * put a string key into a map whose keys are integers), the - * put(Object key, Object value) call will throw a - * ClassCastException. + * {@code put(Object key, Object value)} call will throw a + * {@code ClassCastException}. */ public TreeMap() { comparator = null; @@ -144,16 +145,16 @@ public class TreeMap /** * Constructs a new, empty tree map, ordered according to the given - * comparator. All keys inserted into the map must be mutually - * comparable by the given comparator: comparator.compare(k1, - * k2) must not throw a ClassCastException for any keys - * k1 and k2 in the map. If the user attempts to put - * a key into the map that violates this constraint, the put(Object - * key, Object value) call will throw a - * ClassCastException. + * comparator. All keys inserted into the map must be mutually + * comparable by the given comparator: {@code comparator.compare(k1, + * k2)} must not throw a {@code ClassCastException} for any keys + * {@code k1} and {@code k2} in the map. If the user attempts to put + * a key into the map that violates this constraint, the {@code put(Object + * key, Object value)} call will throw a + * {@code ClassCastException}. * * @param comparator the comparator that will be used to order this map. - * If null, the {@linkplain Comparable natural + * If {@code null}, the {@linkplain Comparable natural * ordering} of the keys will be used. */ public TreeMap(Comparator comparator) { @@ -162,12 +163,12 @@ public class TreeMap /** * Constructs a new tree map containing the same mappings as the given - * map, ordered according to the natural ordering of its keys. + * map, ordered according to the natural ordering of its keys. * All keys inserted into the new map must implement the {@link * Comparable} interface. Furthermore, all such keys must be - * mutually comparable: k1.compareTo(k2) must not throw - * a ClassCastException for any keys k1 and - * k2 in the map. This method runs in n*log(n) time. + * mutually comparable: {@code k1.compareTo(k2)} must not throw + * a {@code ClassCastException} for any keys {@code k1} and + * {@code k2} in the map. This method runs in n*log(n) time. * * @param m the map whose mappings are to be placed in this map * @throws ClassCastException if the keys in m are not {@link Comparable}, @@ -210,11 +211,11 @@ public class TreeMap } /** - * Returns true if this map contains a mapping for the specified + * Returns {@code true} if this map contains a mapping for the specified * key. * * @param key key whose presence in this map is to be tested - * @return true if this map contains a mapping for the + * @return {@code true} if this map contains a mapping for the * specified key * @throws ClassCastException if the specified key cannot be compared * with the keys currently in the map @@ -227,16 +228,16 @@ public class TreeMap } /** - * Returns true if this map maps one or more keys to the - * specified value. More formally, returns true if and only if - * this map contains at least one mapping to a value v such - * that (value==null ? v==null : value.equals(v)). This + * Returns {@code true} if this map maps one or more keys to the + * specified value. More formally, returns {@code true} if and only if + * this map contains at least one mapping to a value {@code v} such + * that {@code (value==null ? v==null : value.equals(v))}. This * operation will probably require time linear in the map size for * most implementations. * * @param value value whose presence in this map is to be tested - * @return true if a mapping to value exists; - * false otherwise + * @return {@code true} if a mapping to {@code value} exists; + * {@code false} otherwise * @since 1.2 */ public boolean containsValue(Object value) { @@ -256,7 +257,7 @@ public class TreeMap * method returns {@code v}; otherwise it returns {@code null}. * (There can be at most one such mapping.) * - *

A return value of {@code null} does not necessarily + *

A return value of {@code null} does not necessarily * indicate that the map contains no mapping for the key; it's also * possible that the map explicitly maps the key to {@code null}. * The {@link #containsKey containsKey} operation may be used to @@ -322,10 +323,10 @@ public class TreeMap } /** - * Returns this map's entry for the given key, or null if the map + * Returns this map's entry for the given key, or {@code null} if the map * does not contain an entry for the key. * - * @return this map's entry for the given key, or null if the map + * @return this map's entry for the given key, or {@code null} if the map * does not contain an entry for the key * @throws ClassCastException if the specified key cannot be compared * with the keys currently in the map @@ -381,7 +382,7 @@ public class TreeMap * Gets the entry corresponding to the specified key; if no such entry * exists, returns the entry for the least key greater than the specified * key; if no such entry exists (i.e., the greatest key in the Tree is less - * than the specified key), returns null. + * than the specified key), returns {@code null}. */ final Entry getCeilingEntry(K key) { Entry p = root; @@ -413,7 +414,7 @@ public class TreeMap /** * Gets the entry corresponding to the specified key; if no such entry * exists, returns the entry for the greatest key less than the specified - * key; if no such entry exists, returns null. + * key; if no such entry exists, returns {@code null}. */ final Entry getFloorEntry(K key) { Entry p = root; @@ -447,7 +448,7 @@ public class TreeMap * Gets the entry for the least key greater than the specified * key; if no such entry exists, returns the entry for the least * key greater than the specified key; if no such entry exists - * returns null. + * returns {@code null}. */ final Entry getHigherEntry(K key) { Entry p = root; @@ -478,7 +479,7 @@ public class TreeMap /** * Returns the entry for the greatest key less than the specified key; if * no such entry exists (i.e., the least key in the Tree is greater than - * the specified key), returns null. + * the specified key), returns {@code null}. */ final Entry getLowerEntry(K key) { Entry p = root; @@ -514,10 +515,10 @@ public class TreeMap * @param key key with which the specified value is to be associated * @param value value to be associated with the specified key * - * @return the previous value associated with key, or - * null if there was no mapping for key. - * (A null return can also indicate that the map - * previously associated null with key.) + * @return the previous value associated with {@code key}, or + * {@code null} if there was no mapping for {@code key}. + * (A {@code null} return can also indicate that the map + * previously associated {@code null} with {@code key}.) * @throws ClassCastException if the specified key cannot be compared * with the keys currently in the map * @throws NullPointerException if the specified key is null @@ -583,10 +584,10 @@ public class TreeMap * Removes the mapping for this key from this TreeMap if present. * * @param key key for which mapping should be removed - * @return the previous value associated with key, or - * null if there was no mapping for key. - * (A null return can also indicate that the map - * previously associated null with key.) + * @return the previous value associated with {@code key}, or + * {@code null} if there was no mapping for {@code key}. + * (A {@code null} return can also indicate that the map + * previously associated {@code null} with {@code key}.) * @throws ClassCastException if the specified key cannot be compared * with the keys currently in the map * @throws NullPointerException if the specified key is null @@ -614,7 +615,7 @@ public class TreeMap } /** - * Returns a shallow copy of this TreeMap instance. (The keys and + * Returns a shallow copy of this {@code TreeMap} instance. (The keys and * values themselves are not cloned.) * * @return a shallow copy of this map @@ -788,12 +789,12 @@ public class TreeMap * The set is backed by the map, so changes to the map are * reflected in the set, and vice-versa. If the map is modified * while an iteration over the set is in progress (except through - * the iterator's own remove operation), the results of + * the iterator's own {@code remove} operation), the results of * the iteration are undefined. The set supports element removal, * which removes the corresponding mapping from the map, via the - * Iterator.remove, Set.remove, - * removeAll, retainAll, and clear - * operations. It does not support the add or addAll + * {@code Iterator.remove}, {@code Set.remove}, + * {@code removeAll}, {@code retainAll}, and {@code clear} + * operations. It does not support the {@code add} or {@code addAll} * operations. */ public Set keySet() { @@ -822,13 +823,13 @@ public class TreeMap * The collection is backed by the map, so changes to the map are * reflected in the collection, and vice-versa. If the map is * modified while an iteration over the collection is in progress - * (except through the iterator's own remove operation), + * (except through the iterator's own {@code remove} operation), * the results of the iteration are undefined. The collection * supports element removal, which removes the corresponding - * mapping from the map, via the Iterator.remove, - * Collection.remove, removeAll, - * retainAll and clear operations. It does not - * support the add or addAll operations. + * mapping from the map, via the {@code Iterator.remove}, + * {@code Collection.remove}, {@code removeAll}, + * {@code retainAll} and {@code clear} operations. It does not + * support the {@code add} or {@code addAll} operations. */ public Collection values() { Collection vs = values; @@ -841,14 +842,14 @@ public class TreeMap * The set is backed by the map, so changes to the map are * reflected in the set, and vice-versa. If the map is modified * while an iteration over the set is in progress (except through - * the iterator's own remove operation, or through the - * setValue operation on a map entry returned by the + * the iterator's own {@code remove} operation, or through the + * {@code setValue} operation on a map entry returned by the * iterator) the results of the iteration are undefined. The set * supports element removal, which removes the corresponding - * mapping from the map, via the Iterator.remove, - * Set.remove, removeAll, retainAll and - * clear operations. It does not support the - * add or addAll operations. + * mapping from the map, via the {@code Iterator.remove}, + * {@code Set.remove}, {@code removeAll}, {@code retainAll} and + * {@code clear} operations. It does not support the + * {@code add} or {@code addAll} operations. */ public Set> entrySet() { EntrySet es = entrySet; @@ -868,7 +869,7 @@ public class TreeMap /** * @throws ClassCastException {@inheritDoc} - * @throws NullPointerException if fromKey or toKey is + * @throws NullPointerException if {@code fromKey} or {@code toKey} is * null and this map uses natural ordering, or its comparator * does not permit null keys * @throws IllegalArgumentException {@inheritDoc} @@ -883,7 +884,7 @@ public class TreeMap /** * @throws ClassCastException {@inheritDoc} - * @throws NullPointerException if toKey is null + * @throws NullPointerException if {@code toKey} is null * and this map uses natural ordering, or its comparator * does not permit null keys * @throws IllegalArgumentException {@inheritDoc} @@ -897,7 +898,7 @@ public class TreeMap /** * @throws ClassCastException {@inheritDoc} - * @throws NullPointerException if fromKey is null + * @throws NullPointerException if {@code fromKey} is null * and this map uses natural ordering, or its comparator * does not permit null keys * @throws IllegalArgumentException {@inheritDoc} @@ -911,7 +912,7 @@ public class TreeMap /** * @throws ClassCastException {@inheritDoc} - * @throws NullPointerException if fromKey or toKey is + * @throws NullPointerException if {@code fromKey} or {@code toKey} is * null and this map uses natural ordering, or its comparator * does not permit null keys * @throws IllegalArgumentException {@inheritDoc} @@ -922,7 +923,7 @@ public class TreeMap /** * @throws ClassCastException {@inheritDoc} - * @throws NullPointerException if toKey is null + * @throws NullPointerException if {@code toKey} is null * and this map uses natural ordering, or its comparator * does not permit null keys * @throws IllegalArgumentException {@inheritDoc} @@ -933,7 +934,7 @@ public class TreeMap /** * @throws ClassCastException {@inheritDoc} - * @throws NullPointerException if fromKey is null + * @throws NullPointerException if {@code fromKey} is null * and this map uses natural ordering, or its comparator * does not permit null keys * @throws IllegalArgumentException {@inheritDoc} @@ -1193,7 +1194,7 @@ public class TreeMap /** * Test two values for equality. Differs from o1.equals(o2) only in - * that it copes with null o1 properly. + * that it copes with {@code null} o1 properly. */ final static boolean valEquals(Object o1, Object o2) { return (o1==null ? o2==null : o1.equals(o2)); @@ -1897,7 +1898,7 @@ public class TreeMap /** * Make a new cell with given key, value, and parent, and with - * null child links, and BLACK color. + * {@code null} child links, and BLACK color. */ Entry(K key, V value, Entry parent) { this.key = key; @@ -2249,10 +2250,10 @@ public class TreeMap private static final long serialVersionUID = 919286545866124006L; /** - * Save the state of the TreeMap instance to a stream (i.e., + * Save the state of the {@code TreeMap} instance to a stream (i.e., * serialize it). * - * @serialData The size of the TreeMap (the number of key-value + * @serialData The size of the TreeMap (the number of key-value * mappings) is emitted (int), followed by the key (Object) * and value (Object) for each key-value mapping represented * by the TreeMap. The key-value mappings are emitted in @@ -2277,7 +2278,7 @@ public class TreeMap } /** - * Reconstitute the TreeMap instance from a stream (i.e., + * Reconstitute the {@code TreeMap} instance from a stream (i.e., * deserialize it). */ private void readObject(final java.io.ObjectInputStream s)