< prev index next >
src/java.base/share/classes/java/util/IdentityHashMap.java
Print this page
@@ -29,22 +29,22 @@
import java.util.function.BiConsumer;
import java.util.function.BiFunction;
import java.util.function.Consumer;
/**
- * This class implements the <tt>Map</tt> interface with a hash table, using
+ * This class implements the {@code Map} interface with a hash table, using
* reference-equality in place of object-equality when comparing keys (and
- * values). In other words, in an <tt>IdentityHashMap</tt>, two keys
- * <tt>k1</tt> and <tt>k2</tt> are considered equal if and only if
- * <tt>(k1==k2)</tt>. (In normal <tt>Map</tt> implementations (like
- * <tt>HashMap</tt>) two keys <tt>k1</tt> and <tt>k2</tt> are considered equal
- * if and only if <tt>(k1==null ? k2==null : k1.equals(k2))</tt>.)
- *
- * <p><b>This class is <i>not</i> a general-purpose <tt>Map</tt>
- * implementation! While this class implements the <tt>Map</tt> interface, it
- * intentionally violates <tt>Map's</tt> general contract, which mandates the
- * use of the <tt>equals</tt> method when comparing objects. This class is
+ * values). In other words, in an {@code IdentityHashMap}, two keys
+ * {@code k1} and {@code k2} are considered equal if and only if
+ * {@code (k1==k2)}. (In normal {@code Map} implementations (like
+ * {@code HashMap}) two keys {@code k1} and {@code k2} are considered equal
+ * if and only if {@code (k1==null ? k2==null : k1.equals(k2))}.)
+ *
+ * <p><b>This class is <i>not</i> a general-purpose {@code Map}
+ * implementation! While this class implements the {@code Map} interface, it
+ * intentionally violates {@code Map's} general contract, which mandates the
+ * use of the {@code equals} method when comparing objects. This class is
* designed for use only in the rare cases wherein reference-equality
* semantics are required.</b>
*
* <p>A typical use of this class is <i>topology-preserving object graph
* transformations</i>, such as serialization or deep-copying. To perform such
@@ -54,16 +54,16 @@
* Another typical use of this class is to maintain <i>proxy objects</i>. For
* example, a debugging facility might wish to maintain a proxy object for
* each object in the program being debugged.
*
* <p>This class provides all of the optional map operations, and permits
- * <tt>null</tt> values and the <tt>null</tt> key. This class makes no
+ * {@code null} values and the {@code null} key. This class makes no
* guarantees as to the order of the map; in particular, it does not guarantee
* that the order will remain constant over time.
*
* <p>This class provides constant-time performance for the basic
- * operations (<tt>get</tt> and <tt>put</tt>), assuming the system
+ * operations ({@code get} and {@code put}), assuming the system
* identity hash function ({@link System#identityHashCode(Object)})
* disperses elements properly among the buckets.
*
* <p>This class has one tuning parameter (which affects performance but not
* semantics): <i>expected maximum size</i>. This parameter is the maximum
@@ -94,24 +94,24 @@
* {@link Collections#synchronizedMap Collections.synchronizedMap}
* method. This is best done at creation time, to prevent accidental
* unsynchronized access to the map:<pre>
* Map m = Collections.synchronizedMap(new IdentityHashMap(...));</pre>
*
- * <p>The iterators returned by the <tt>iterator</tt> method of the
+ * <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
+ * 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.
*
* <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>fail-fast iterators should be used only
* to detect bugs.</i>
*
* <p>Implementation note: This is a simple <i>linear-probe</i> hash table,
@@ -215,11 +215,11 @@
* Putting more than the expected number of key-value mappings into
* the map may cause the internal data structure to grow, which may be
* somewhat time-consuming.
*
* @param expectedMaxSize the expected maximum size of the map
- * @throws IllegalArgumentException if <tt>expectedMaxSize</tt> is negative
+ * @throws IllegalArgumentException if {@code expectedMaxSize} is negative
*/
public IdentityHashMap(int expectedMaxSize) {
if (expectedMaxSize < 0)
throw new IllegalArgumentException("expectedMaxSize is negative: "
+ expectedMaxSize);
@@ -275,14 +275,14 @@
public int size() {
return size;
}
/**
- * Returns <tt>true</tt> if this identity hash map contains no key-value
+ * Returns {@code true} if this identity hash map contains no key-value
* mappings.
*
- * @return <tt>true</tt> if this identity hash map contains no key-value
+ * @return {@code true} if this identity hash map contains no key-value
* mappings
*/
public boolean isEmpty() {
return size == 0;
}
@@ -339,11 +339,11 @@
/**
* Tests whether the specified object reference is a key in this identity
* hash map.
*
* @param key possible key
- * @return <code>true</code> if the specified object reference is a key
+ * @return {@code true} if the specified object reference is a key
* in this map
* @see #containsValue(Object)
*/
public boolean containsKey(Object key) {
Object k = maskNull(key);
@@ -363,11 +363,11 @@
/**
* Tests whether the specified object reference is a value in this identity
* hash map.
*
* @param value value whose presence in this map is to be tested
- * @return <tt>true</tt> if this map maps one or more keys to the
+ * @return {@code true} if this map maps one or more keys to the
* specified object reference
* @see #containsKey(Object)
*/
public boolean containsValue(Object value) {
Object[] tab = table;
@@ -381,11 +381,11 @@
/**
* Tests if the specified key-value mapping is in the map.
*
* @param key possible key
* @param value possible value
- * @return <code>true</code> if and only if the specified key-value
+ * @return {@code true} if and only if the specified key-value
* mapping is in the map
*/
private boolean containsMapping(Object key, Object value) {
Object k = maskNull(key);
Object[] tab = table;
@@ -406,14 +406,14 @@
* hash map. If the map previously contained a mapping for the key, the
* old value is replaced.
*
* @param key the key with which the specified value is to be associated
* @param value the 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}.)
* @see Object#equals(Object)
* @see #get(Object)
* @see #containsKey(Object)
*/
public V put(K key, V value) {
@@ -508,14 +508,14 @@
/**
* Removes the mapping for this key from this map if present.
*
* @param key key whose mapping is to be removed from the map
- * @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}.)
*/
public V remove(Object key) {
Object k = maskNull(key);
Object[] tab = table;
int len = tab.length;
@@ -542,11 +542,11 @@
/**
* Removes the specified key-value mapping from the map if it is present.
*
* @param key possible key
* @param value possible value
- * @return <code>true</code> if and only if the specified key-value
+ * @return {@code true} if and only if the specified key-value
* mapping was in the map
*/
private boolean removeMapping(Object key, Object value) {
Object k = maskNull(key);
Object[] tab = table;
@@ -619,23 +619,23 @@
size = 0;
}
/**
* Compares the specified object with this map for equality. Returns
- * <tt>true</tt> if the given object is also a map and the two maps
+ * {@code true} if the given object is also a map and the two maps
* represent identical object-reference mappings. More formally, this
- * map is equal to another map <tt>m</tt> if and only if
- * <tt>this.entrySet().equals(m.entrySet())</tt>.
+ * map is equal to another map {@code m} if and only if
+ * {@code this.entrySet().equals(m.entrySet())}.
*
* <p><b>Owing to the reference-equality-based semantics of this map it is
* possible that the symmetry and transitivity requirements of the
- * <tt>Object.equals</tt> contract may be violated if this map is compared
- * to a normal map. However, the <tt>Object.equals</tt> contract is
- * guaranteed to hold among <tt>IdentityHashMap</tt> instances.</b>
+ * {@code Object.equals} contract may be violated if this map is compared
+ * to a normal map. However, the {@code Object.equals} contract is
+ * guaranteed to hold among {@code IdentityHashMap} instances.</b>
*
* @param o object to be compared for equality with this map
- * @return <tt>true</tt> if the specified object is equal to this map
+ * @return {@code true} if the specified object is equal to this map
* @see Object#equals(Object)
*/
public boolean equals(Object o) {
if (o == this) {
return true;
@@ -660,21 +660,21 @@
}
/**
* Returns the hash code value for this map. The hash code of a map is
* defined to be the sum of the hash codes of each entry in the map's
- * <tt>entrySet()</tt> view. This ensures that <tt>m1.equals(m2)</tt>
- * implies that <tt>m1.hashCode()==m2.hashCode()</tt> for any two
- * <tt>IdentityHashMap</tt> instances <tt>m1</tt> and <tt>m2</tt>, as
+ * {@code entrySet()} view. This ensures that {@code m1.equals(m2)}
+ * implies that {@code m1.hashCode()==m2.hashCode()} for any two
+ * {@code IdentityHashMap} instances {@code m1} and {@code m2}, as
* required by the general contract of {@link Object#hashCode}.
*
* <p><b>Owing to the reference-equality-based semantics of the
- * <tt>Map.Entry</tt> instances in the set returned by this map's
- * <tt>entrySet</tt> method, it is possible that the contractual
- * requirement of <tt>Object.hashCode</tt> mentioned in the previous
+ * {@code Map.Entry} instances in the set returned by this map's
+ * {@code entrySet} method, it is possible that the contractual
+ * requirement of {@code Object.hashCode} mentioned in the previous
* paragraph will be violated if one of the two objects being compared is
- * an <tt>IdentityHashMap</tt> instance and the other is a normal map.</b>
+ * an {@code IdentityHashMap} instance and the other is a normal map.</b>
*
* @return the hash code value for this map
* @see Object#equals(Object)
* @see #equals(Object)
*/
@@ -928,36 +928,36 @@
* Returns an identity-based set view of the keys contained in this map.
* 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, 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> methods. It does not support the <tt>add</tt> or
- * <tt>addAll</tt> methods.
+ * corresponding mapping from the map, via the {@code Iterator.remove},
+ * {@code Set.remove}, {@code removeAll}, {@code retainAll}, and
+ * {@code clear} methods. It does not support the {@code add} or
+ * {@code addAll} methods.
*
* <p><b>While the object returned by this method implements the
- * <tt>Set</tt> interface, it does <i>not</i> obey <tt>Set's</tt> general
+ * {@code Set} interface, it does <i>not</i> obey {@code Set's} general
* contract. Like its backing map, the set returned by this method
* defines element equality as reference-equality rather than
- * object-equality. This affects the behavior of its <tt>contains</tt>,
- * <tt>remove</tt>, <tt>containsAll</tt>, <tt>equals</tt>, and
- * <tt>hashCode</tt> methods.</b>
+ * object-equality. This affects the behavior of its {@code contains},
+ * {@code remove}, {@code containsAll}, {@code equals}, and
+ * {@code hashCode} methods.</b>
*
- * <p><b>The <tt>equals</tt> method of the returned set returns <tt>true</tt>
+ * <p><b>The {@code equals} method of the returned set returns {@code true}
* only if the specified object is a set containing exactly the same
* object references as the returned set. The symmetry and transitivity
- * requirements of the <tt>Object.equals</tt> contract may be violated if
+ * requirements of the {@code Object.equals} contract may be violated if
* the set returned by this method is compared to a normal set. However,
- * the <tt>Object.equals</tt> contract is guaranteed to hold among sets
+ * the {@code Object.equals} contract is guaranteed to hold among sets
* returned by this method.</b>
*
- * <p>The <tt>hashCode</tt> method of the returned set returns the sum of
+ * <p>The {@code hashCode} method of the returned set returns the sum of
* the <i>identity hashcodes</i> of the elements in the set, rather than
* the sum of their hashcodes. This is mandated by the change in the
- * semantics of the <tt>equals</tt> method, in order to enforce the
- * general contract of the <tt>Object.hashCode</tt> method among sets
+ * semantics of the {@code equals} method, in order to enforce the
+ * general contract of the {@code Object.hashCode} method among sets
* returned by this method.
*
* @return an identity-based set view of the keys contained in this map
* @see Object#equals(Object)
* @see System#identityHashCode(Object)
@@ -1052,22 +1052,22 @@
* 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,
* 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> methods. It does not
- * support the <tt>add</tt> or <tt>addAll</tt> methods.
+ * mapping from the map, via the {@code Iterator.remove},
+ * {@code Collection.remove}, {@code removeAll},
+ * {@code retainAll} and {@code clear} methods. It does not
+ * support the {@code add} or {@code addAll} methods.
*
* <p><b>While the object returned by this method implements the
- * <tt>Collection</tt> interface, it does <i>not</i> obey
- * <tt>Collection's</tt> general contract. Like its backing map,
+ * {@code Collection} interface, it does <i>not</i> obey
+ * {@code Collection's} general contract. Like its backing map,
* the collection returned by this method defines element equality as
* reference-equality rather than object-equality. This affects the
- * behavior of its <tt>contains</tt>, <tt>remove</tt> and
- * <tt>containsAll</tt> methods.</b>
+ * behavior of its {@code contains}, {@code remove} and
+ * {@code containsAll} methods.</b>
*/
public Collection<V> values() {
Collection<V> vs = values;
if (vs != null)
return vs;
@@ -1134,40 +1134,40 @@
}
/**
* Returns a {@link Set} view of the mappings contained in this map.
* Each element in the returned set is a reference-equality-based
- * <tt>Map.Entry</tt>. The set is backed by the map, so changes
+ * {@code Map.Entry}. 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,
* 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>
- * methods. It does not support the <tt>add</tt> or
- * <tt>addAll</tt> methods.
+ * the map, via the {@code Iterator.remove}, {@code Set.remove},
+ * {@code removeAll}, {@code retainAll} and {@code clear}
+ * methods. It does not support the {@code add} or
+ * {@code addAll} methods.
*
- * <p>Like the backing map, the <tt>Map.Entry</tt> objects in the set
+ * <p>Like the backing map, the {@code Map.Entry} objects in the set
* returned by this method define key and value equality as
* reference-equality rather than object-equality. This affects the
- * behavior of the <tt>equals</tt> and <tt>hashCode</tt> methods of these
- * <tt>Map.Entry</tt> objects. A reference-equality based <tt>Map.Entry
- * e</tt> is equal to an object <tt>o</tt> if and only if <tt>o</tt> is a
- * <tt>Map.Entry</tt> and <tt>e.getKey()==o.getKey() &&
- * e.getValue()==o.getValue()</tt>. To accommodate these equals
- * semantics, the <tt>hashCode</tt> method returns
- * <tt>System.identityHashCode(e.getKey()) ^
- * System.identityHashCode(e.getValue())</tt>.
+ * behavior of the {@code equals} and {@code hashCode} methods of these
+ * {@code Map.Entry} objects. A reference-equality based {@code Map.Entry
+ * e} is equal to an object {@code o} if and only if {@code o} is a
+ * {@code Map.Entry} and {@code e.getKey()==o.getKey() &&
+ * e.getValue()==o.getValue()}. To accommodate these equals
+ * semantics, the {@code hashCode} method returns
+ * {@code System.identityHashCode(e.getKey()) ^
+ * System.identityHashCode(e.getValue())}.
*
* <p><b>Owing to the reference-equality-based semantics of the
- * <tt>Map.Entry</tt> instances in the set returned by this method,
+ * {@code Map.Entry} instances in the set returned by this method,
* it is possible that the symmetry and transitivity requirements of
* the {@link Object#equals(Object)} contract may be violated if any of
* the entries in the set is compared to a normal map entry, or if
* the set returned by this method is compared to a set of normal map
* entries (such as would be returned by a call to this method on a normal
- * map). However, the <tt>Object.equals</tt> contract is guaranteed to
+ * map). However, the {@code Object.equals} contract is guaranteed to
* hold among identity-based map entries, and among sets of such entries.
* </b>
*
* @return a set view of the identity-mappings contained in this map
*/
@@ -1258,15 +1258,15 @@
private static final long serialVersionUID = 8188218128353913216L;
/**
- * Saves the state of the <tt>IdentityHashMap</tt> instance to a stream
+ * Saves the state of the {@code IdentityHashMap} instance to a stream
* (i.e., serializes it).
*
* @serialData The <i>size</i> of the HashMap (the number of key-value
- * mappings) (<tt>int</tt>), followed by the key (Object) and
+ * mappings) ({@code int}), followed by the key (Object) and
* value (Object) for each key-value mapping represented by the
* IdentityHashMap. The key-value mappings are emitted in no
* particular order.
*/
private void writeObject(java.io.ObjectOutputStream s)
@@ -1287,11 +1287,11 @@
}
}
}
/**
- * Reconstitutes the <tt>IdentityHashMap</tt> instance from a stream (i.e.,
+ * Reconstitutes the {@code IdentityHashMap} instance from a stream (i.e.,
* deserializes it).
*/
private void readObject(java.io.ObjectInputStream s)
throws java.io.IOException, ClassNotFoundException {
// Read in any hidden stuff
< prev index next >