1 files changed, 81 insertions, 14 deletions
diff --git a/libjava/java/util/BasicMapEntry.java b/libjava/java/util/BasicMapEntry.java
index f858cb4ebd9..48fcc146664 100644
--- a/libjava/java/util/BasicMapEntry.java
+++ b/libjava/java/util/BasicMapEntry.java
@@ -1,6 +1,6 @@
 /* BasicMapEntry.java -- a class providing a plain-vanilla implementation of
    the Map.Entry interface; could be used anywhere in java.util
-   Copyright (C) 1998, 2000 Free Software Foundation, Inc.
+   Copyright (C) 1998, 2000, 2001 Free Software Foundation, Inc.
 
 This file is part of GNU Classpath.
 
@@ -29,52 +29,113 @@ executable file might be covered by the GNU General Public License. */
 package java.util;
 
 /**
- * A class which implements Map.Entry. It is shared by HashMap, TreeMap, and
- * Hashtable.
+ * A class which implements Map.Entry. It is shared by HashMap, TreeMap,
+ * Hashtable, and Collections. It is not specified by the JDK, but makes
+ * life much easier.
  *
- * @author      Jon Zeppieri
+ * @author Jon Zeppieri
+ * @author Eric Blake <ebb9@email.byu.edu>
  */
 class BasicMapEntry implements Map.Entry
 {
+  /**
+   * The key. Package visible for direct manipulation.
+   */
   Object key;
+
+  /**
+   * The value. Package visible for direct manipulation.
+   */
   Object value;
 
+  /**
+   * Basic constructor initializes the fields.
+   * @param newKey the key
+   * @param newValue the value
+   */
   BasicMapEntry(Object newKey, Object newValue)
   {
     key = newKey;
     value = newValue;
   }
 
+  /**
+   * Compares the specified object with this entry. Returns true only if
+   * the object is a mapping of identical key and value. In other words,
+   * this must be:
+   * <pre>
+   * (o instanceof Map.Entry) &&
+   * (getKey() == null ? ((HashMap) o).getKey() == null
+   *                   : getKey().equals(((HashMap) o).getKey())) &&
+   * (getValue() == null ? ((HashMap) o).getValue() == null
+   *                   : getValue().equals(((HashMap) o).getValue()))
+   * </pre>
+   *
+   * @param o the object to compare
+   * @return true if it is equal
+   */
   public final boolean equals(Object o)
   {
-    if (!(o instanceof Map.Entry))
+    if (! (o instanceof Map.Entry))
       return false;
+    // Optimize for our own entries.
+    if (o instanceof BasicMapEntry)
+      {
+        BasicMapEntry e = (BasicMapEntry) o;
+        return (AbstractCollection.equals(key, e.key)
+                && AbstractCollection.equals(value, e.value));
+      }
     Map.Entry e = (Map.Entry) o;
-    return (key == null ? e.getKey() == null : key.equals(e.getKey())
-            && value == null ? e.getValue() == null 
-			     : value.equals(e.getValue()));
+    return (AbstractCollection.equals(key, e.getKey())
+            && AbstractCollection.equals(value, e.getValue()));
   }
 
+  /**
+   * Get the key corresponding to this entry.
+   *
+   * @return the key
+   */
   public final Object getKey()
   {
     return key;
   }
 
+  /**
+   * Get the value corresponding to this entry. If you already called
+   * Iterator.remove(), the behavior undefined, but in this case it works.
+   *
+   * @return the value
+   */
   public final Object getValue()
   {
     return value;
   }
 
+  /**
+   * Returns the hash code of the entry.  This is defined as the exclusive-or
+   * of the hashcodes of the key and value (using 0 for null). In other
+   * words, this must be:
+   * <pre>
+   *  (getKey() == null ? 0 : getKey().hashCode()) ^
+   *  (getValue() == null ? 0 : getValue().hashCode())
+   * </pre>
+   *
+   * @return the hash code
+   */
   public final int hashCode()
   {
-    int kc = (key == null ? 0 : key.hashCode());
-    int vc = (value == null ? 0 : value.hashCode());
-    return kc ^ vc;
+    return (AbstractCollection.hashCode(key)
+            ^ AbstractCollection.hashCode(value));
   }
 
-  /** 
-   * sets the value of this Map.Entry. Note that this is overriden by 
-   * Hashtable.Entry, which does not permit a null value.
+  /**
+   * Replaces the value with the specified object. This writes through
+   * to the map, unless you have already called Iterator.remove(). It
+   * may be overridden to restrict a null value.
+   *
+   * @param newVal the new value to store
+   * @return the old value
+   * @throws NullPointerException if the map forbids null values
    */
   public Object setValue(Object newVal)
   {
@@ -83,6 +144,12 @@ class BasicMapEntry implements Map.Entry
     return r;
   }
 
+  /**
+   * This provides a string representation of the entry. It is of the form
+   * "key=value", where string concatenation is used on key and value.
+   *
+   * @return the string representation
+   */
   public final String toString()
   {
     return key + "=" + value;