--- a/jdk/src/share/classes/java/util/TreeMap.java Tue Nov 09 18:57:12 2010 +0000
+++ b/jdk/src/share/classes/java/util/TreeMap.java Thu Nov 11 11:01:25 2010 -0800
@@ -32,25 +32,26 @@
* creation time, depending on which constructor is used.
*
* <p>This implementation provides guaranteed log(n) time cost for the
- * <tt>containsKey</tt>, <tt>get</tt>, <tt>put</tt> and <tt>remove</tt>
+ * {@code containsKey}, {@code get}, {@code put} and {@code remove}
* operations. Algorithms are adaptations of those in Cormen, Leiserson, and
- * Rivest's <I>Introduction to Algorithms</I>.
+ * Rivest's <em>Introduction to Algorithms</em>.
*
- * <p>Note that the ordering maintained by a sorted map (whether or not an
- * explicit comparator is provided) must be <i>consistent with equals</i> if
- * this sorted map is to correctly implement the <tt>Map</tt> interface. (See
- * <tt>Comparable</tt> or <tt>Comparator</tt> for a precise definition of
- * <i>consistent with equals</i>.) This is so because the <tt>Map</tt>
- * interface is defined in terms of the equals operation, but a map performs
- * all key comparisons using its <tt>compareTo</tt> (or <tt>compare</tt>)
- * 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
- * <i>is</i> well-defined even if its ordering is inconsistent with equals; it
- * just fails to obey the general contract of the <tt>Map</tt> interface.
+ * <p>Note that the ordering maintained by a tree map, like any sorted map, and
+ * whether or not an explicit comparator is provided, must be <em>consistent
+ * with {@code equals}</em> if this sorted map is to correctly implement the
+ * {@code Map} interface. (See {@code Comparable} or {@code Comparator} for a
+ * precise definition of <em>consistent with equals</em>.) 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 <em>is</em> well-defined even if its ordering is
+ * inconsistent with {@code equals}; it just fails to obey the general contract
+ * of the {@code Map} interface.
*
* <p><strong>Note that this implementation is not synchronized.</strong>
* If multiple threads access a map concurrently, and at least one of the
- * threads modifies the map structurally, it <i>must</i> be synchronized
+ * threads modifies the map structurally, it <em>must</em> 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 @@
* unsynchronized access to the map: <pre>
* SortedMap m = Collections.synchronizedSortedMap(new TreeMap(...));</pre>
*
- * <p>The iterators returned by the <tt>iterator</tt> method of the collections
+ * <p>The iterators returned by the {@code iterator} method of the collections
* returned by all of this class's "collection view methods" are
- * <i>fail-fast</i>: if the map is structurally modified at any time after the
- * iterator is created, in any way except through the iterator's own
- * <tt>remove</tt> method, the iterator will throw a {@link
+ * <em>fail-fast</em>: 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 @@
* <p>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 <tt>ConcurrentModificationException</tt> 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: <i>the fail-fast behavior of iterators
- * should be used only to detect bugs.</i>
+ * exception for its correctness: <em>the fail-fast behavior of iterators
+ * should be used only to detect bugs.</em>
*
- * <p>All <tt>Map.Entry</tt> pairs returned by methods in this class
+ * <p>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 <em>not</em> support the <tt>Entry.setValue</tt>
+ * produced. They do <strong>not</strong> support the {@code Entry.setValue}
* method. (Note however that it is possible to change mappings in the
- * associated map using <tt>put</tt>.)
+ * associated map using {@code put}.)
*
* <p>This class is a member of the
* <a href="{@docRoot}/../technotes/guides/collections/index.html">
@@ -130,13 +131,13 @@
* 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
- * <i>mutually comparable</i>: <tt>k1.compareTo(k2)</tt> must not throw
- * a <tt>ClassCastException</tt> for any keys <tt>k1</tt> and
- * <tt>k2</tt> in the map. If the user attempts to put a key into the
+ * <em>mutually comparable</em>: {@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
- * <tt>put(Object key, Object value)</tt> call will throw a
- * <tt>ClassCastException</tt>.
+ * {@code put(Object key, Object value)} call will throw a
+ * {@code ClassCastException}.
*/
public TreeMap() {
comparator = null;
@@ -144,16 +145,16 @@
/**
* Constructs a new, empty tree map, ordered according to the given
- * comparator. All keys inserted into the map must be <i>mutually
- * comparable</i> by the given comparator: <tt>comparator.compare(k1,
- * k2)</tt> must not throw a <tt>ClassCastException</tt> for any keys
- * <tt>k1</tt> and <tt>k2</tt> in the map. If the user attempts to put
- * a key into the map that violates this constraint, the <tt>put(Object
- * key, Object value)</tt> call will throw a
- * <tt>ClassCastException</tt>.
+ * comparator. All keys inserted into the map must be <em>mutually
+ * comparable</em> 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 <tt>null</tt>, the {@linkplain Comparable natural
+ * If {@code null}, the {@linkplain Comparable natural
* ordering} of the keys will be used.
*/
public TreeMap(Comparator<? super K> comparator) {
@@ -162,12 +163,12 @@
/**
* Constructs a new tree map containing the same mappings as the given
- * map, ordered according to the <i>natural ordering</i> of its keys.
+ * map, ordered according to the <em>natural ordering</em> of its keys.
* All keys inserted into the new map must implement the {@link
* Comparable} interface. Furthermore, all such keys must be
- * <i>mutually comparable</i>: <tt>k1.compareTo(k2)</tt> must not throw
- * a <tt>ClassCastException</tt> for any keys <tt>k1</tt> and
- * <tt>k2</tt> in the map. This method runs in n*log(n) time.
+ * <em>mutually comparable</em>: {@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 @@
}
/**
- * Returns <tt>true</tt> 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 <tt>true</tt> 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 @@
}
/**
- * Returns <tt>true</tt> if this map maps one or more keys to the
- * specified value. More formally, returns <tt>true</tt> if and only if
- * this map contains at least one mapping to a value <tt>v</tt> such
- * that <tt>(value==null ? v==null : value.equals(v))</tt>. 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 <tt>true</tt> if a mapping to <tt>value</tt> exists;
- * <tt>false</tt> 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 @@
* method returns {@code v}; otherwise it returns {@code null}.
* (There can be at most one such mapping.)
*
- * <p>A return value of {@code null} does not <i>necessarily</i>
+ * <p>A return value of {@code null} does not <em>necessarily</em>
* 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 @@
}
/**
- * Returns this map's entry for the given key, or <tt>null</tt> 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 <tt>null</tt> 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 @@
* 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 <tt>null</tt>.
+ * than the specified key), returns {@code null}.
*/
final Entry<K,V> getCeilingEntry(K key) {
Entry<K,V> p = root;
@@ -413,7 +414,7 @@
/**
* 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 <tt>null</tt>.
+ * key; if no such entry exists, returns {@code null}.
*/
final Entry<K,V> getFloorEntry(K key) {
Entry<K,V> p = root;
@@ -447,7 +448,7 @@
* 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 <tt>null</tt>.
+ * returns {@code null}.
*/
final Entry<K,V> getHigherEntry(K key) {
Entry<K,V> p = root;
@@ -478,7 +479,7 @@
/**
* 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 <tt>null</tt>.
+ * the specified key), returns {@code null}.
*/
final Entry<K,V> getLowerEntry(K key) {
Entry<K,V> p = root;
@@ -514,10 +515,10 @@
* @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 <tt>key</tt>, or
- * <tt>null</tt> if there was no mapping for <tt>key</tt>.
- * (A <tt>null</tt> return can also indicate that the map
- * previously associated <tt>null</tt> with <tt>key</tt>.)
+ * @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 @@
* 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 <tt>key</tt>, or
- * <tt>null</tt> if there was no mapping for <tt>key</tt>.
- * (A <tt>null</tt> return can also indicate that the map
- * previously associated <tt>null</tt> with <tt>key</tt>.)
+ * @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 @@
}
/**
- * Returns a shallow copy of this <tt>TreeMap</tt> 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 @@
* 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 <tt>remove</tt> 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
- * <tt>Iterator.remove</tt>, <tt>Set.remove</tt>,
- * <tt>removeAll</tt>, <tt>retainAll</tt>, and <tt>clear</tt>
- * operations. It does not support the <tt>add</tt> or <tt>addAll</tt>
+ * {@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<K> keySet() {
@@ -822,13 +823,13 @@
* 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 <tt>remove</tt> 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 <tt>Iterator.remove</tt>,
- * <tt>Collection.remove</tt>, <tt>removeAll</tt>,
- * <tt>retainAll</tt> and <tt>clear</tt> operations. It does not
- * support the <tt>add</tt> or <tt>addAll</tt> 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<V> values() {
Collection<V> vs = values;
@@ -841,14 +842,14 @@
* 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 <tt>remove</tt> operation, or through the
- * <tt>setValue</tt> 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 <tt>Iterator.remove</tt>,
- * <tt>Set.remove</tt>, <tt>removeAll</tt>, <tt>retainAll</tt> and
- * <tt>clear</tt> operations. It does not support the
- * <tt>add</tt> or <tt>addAll</tt> 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<Map.Entry<K,V>> entrySet() {
EntrySet es = entrySet;
@@ -868,7 +869,7 @@
/**
* @throws ClassCastException {@inheritDoc}
- * @throws NullPointerException if <tt>fromKey</tt> or <tt>toKey</tt> 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 @@
/**
* @throws ClassCastException {@inheritDoc}
- * @throws NullPointerException if <tt>toKey</tt> 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 @@
/**
* @throws ClassCastException {@inheritDoc}
- * @throws NullPointerException if <tt>fromKey</tt> 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 @@
/**
* @throws ClassCastException {@inheritDoc}
- * @throws NullPointerException if <tt>fromKey</tt> or <tt>toKey</tt> 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 @@
/**
* @throws ClassCastException {@inheritDoc}
- * @throws NullPointerException if <tt>toKey</tt> 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 @@
/**
* @throws ClassCastException {@inheritDoc}
- * @throws NullPointerException if <tt>fromKey</tt> 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 @@
/**
* Test two values for equality. Differs from o1.equals(o2) only in
- * that it copes with <tt>null</tt> 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 @@
/**
* Make a new cell with given key, value, and parent, and with
- * <tt>null</tt> child links, and BLACK color.
+ * {@code null} child links, and BLACK color.
*/
Entry(K key, V value, Entry<K,V> parent) {
this.key = key;
@@ -2249,10 +2250,10 @@
private static final long serialVersionUID = 919286545866124006L;
/**
- * Save the state of the <tt>TreeMap</tt> instance to a stream (i.e.,
+ * Save the state of the {@code TreeMap} instance to a stream (i.e.,
* serialize it).
*
- * @serialData The <i>size</i> of the TreeMap (the number of key-value
+ * @serialData The <em>size</em> 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 @@
}
/**
- * Reconstitute the <tt>TreeMap</tt> 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)