[PATCH] [collections] SequencedHashMap doc: put, iterators

[Thomas Plümpe <th...@gmx.de>]

I have recently started using the SequencedHashMap and now found that
one of my assumptions (namely, that a previously added entry would keep
its position in the sequence when unnecessarily readded) was wrong.

Taking a closer look at the source code I also noticed that all the
iterators obtained via

    .iterator(),
    .keySet().iterator(),
    .values().iterator(), and
    .entrySet().iterator()

(and .values().toArray(...) for that matter) will definitely be in the
sequence in which they where added to the SeqHashMap. Great! While I did
expect this for .iterator(), I wasn't sure about the others (having
learned never to expect any order from a set or collection) and so I
never used them when order was important. I have attached a
documentation patch that I hope clarifies this behavior. It also fixes a
minor typo in the documentation of a private field (Essientially ->
Essentially).



Index: SequencedHashMap.java
===================================================================
RCS file: /home/cvspublic/jakarta-commons/collections/src/java/org/apache/commons/collections/SequencedHashMap.java,v
retrieving revision 1.21
diff -u -r1.21 SequencedHashMap.java
--- SequencedHashMap.java	23 Nov 2003 14:40:41 -0000	1.21
+++ SequencedHashMap.java	25 Nov 2003 00:58:45 -0000
@@ -456,7 +456,9 @@
     }

     /**
-     *  Implements {@link Map#put(Object, Object)}.
+     *  Implements {@link Map#put(Object, Object)}.  Regardless of whether
+     *  the entry has previously been contained in this map the added entry
+     *  becomes the last entry of the sequence.
      */
     public Object put(Object key, Object value) {
         modCount++;
@@ -591,7 +593,8 @@
     }

     /**
-     *  Implements {@link Map#keySet()}.
+     *  Implements {@link Map#keySet()}.  Iterators provided by the returned
+     *  Set are sequenced based on the order in which entries were added.
      */
     public Set keySet() {
         return new AbstractSet() {
@@ -623,7 +626,9 @@
     }

     /**
-     *  Implements {@link Map#values()}.
+     *  Implements {@link Map#values()}.  Iterators and arrays provided by
+     *  the returned Collection are sequenced based on the order in which
+     *  entries were added.
      */
     public Collection values() {
         return new AbstractCollection() {
@@ -671,7 +676,8 @@
     }

     /**
-     *  Implements {@link Map#entrySet()}.
+     *  Implements {@link Map#entrySet()}.  Iterators provided by the returned
+     *  Set are sequenced based on the order in which entries were added.
      */
     public Set entrySet() {
         return new AbstractSet() {
@@ -730,7 +736,7 @@
          *  should be either {@link #KEY}, {@link #VALUE}, or {@link #ENTRY}.  To
          *  save a tiny bit of memory, this field is also used as a marker for when
          *  remove has been called on the current object to prevent a second remove
-         *  on the same element.  Essientially, if this value is negative (i.e. the
+         *  on the same element.  Essentially, if this value is negative (i.e. the
          *  bit specified by {@link #REMOVED_MASK} is set), the current position
          *  has been removed.  If positive, remove can still be called.
          */
@@ -960,9 +966,10 @@
     }

     /**
-     * Gets an iterator over the keys.
+     * Gets an iterator over the keys.  Its elements are sequenced based
+     * on the order in which elements were added.
      * 
-     * @return an iterator over the keys
+     * @return an ordered iterator over the keys
      */
     public Iterator iterator() {
         return keySet().iterator();



---------------------------------------------------------------------
To unsubscribe, e-mail: commons-dev-unsubscribe@jakarta.apache.org
For additional commands, e-mail: commons-dev-help@jakarta.apache.org