* add copy constructors to AbstractRandomAccessIntList, ArrayIntList and ArrayUnsignedShortList

* more javadocs


git-svn-id: https://svn.apache.org/repos/asf/jakarta/commons/proper/collections/trunk@130940 13f79535-47bb-0310-9956-ffa450edef68

src/java/org/apache/commons/collections/primitives/AbstractRandomAccessIntList.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/AbstractRandomAccessIntList.java,v 1.7 2003/01/11 21:28:02 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/AbstractRandomAccessIntList.java,v 1.8 2003/01/13 12:59:45 rwaldhoff Exp $
  * ====================================================================
  * The Apache Software License, Version 1.1
  *
@@ -60,13 +60,46 @@ package org.apache.commons.collections.primitives;
 import java.util.ConcurrentModificationException;
 import java.util.NoSuchElementException;
 
-
+/**
+ * Abstract base class for {@link IntList}s backed 
+ * by random access structures like arrays.
+ * <p />
+ * Read-only subclasses must override {@link #get}
+ * and {@link #size}.  Mutable subclasses
+ * should also override {@link #set}.  Variably-sized
+ * subclasses should also override {@link #add} 
+ * and {@link #removeElementAt}.  All other methods
+ * have at least some base implementation derived from 
+ * these.  Subclasses may choose to override these methods
+ * to provide a more efficient implementation.
+ * 
+ * @since Commons Collections 2.2
+ * @version $Revision: 1.8 $ $Date: 2003/01/13 12:59:45 $
+ * 
+ * @author Rodney Waldhoff 
+ */
 public abstract class AbstractRandomAccessIntList extends AbstractIntCollection implements IntList {
 
     // constructors
     //-------------------------------------------------------------------------
 
-    protected AbstractRandomAccessIntList() { }    
+    /** Constructs any empty list. */
+    protected AbstractRandomAccessIntList() { 
+    }    
+
+    /** 
+     * Constructs a list containing the elements of the given collection, 
+     * in the order they are returned by that collection's iterator.
+     * 
+     * @see #addAll
+     * @param that the non-<code>null</code> collection of <code>int</code>s 
+     *        to add
+     * @throws NullPointerException if <i>that</i> is <code>null</code>
+     * @throws UnsupportedOperationException if {@link #addAll} does
+     */
+    protected AbstractRandomAccessIntList(IntCollection that) { 
+        addAll(that);
+    }    
 
     // fully abstract methods
     //-------------------------------------------------------------------------
@@ -77,19 +110,33 @@ public abstract class AbstractRandomAccessIntList extends AbstractIntCollection
     // unsupported in base
     //-------------------------------------------------------------------------
     
+    /** 
+     * Unsupported in this implementation. 
+     * @throws UnsupportedOperationException since this method is not supported
+     */
     public int removeElementAt(int index) {
         throw new UnsupportedOperationException();
     }
     
+    /** 
+     * Unsupported in this implementation. 
+     * @throws UnsupportedOperationException since this method is not supported
+     */
     public int set(int index, int element) {
         throw new UnsupportedOperationException();
     }
         
+    /** 
+     * Unsupported in this implementation. 
+     * @throws UnsupportedOperationException since this method is not supported
+     */
     public void add(int index, int element) {
         throw new UnsupportedOperationException();
     }
 
     //-------------------------------------------------------------------------
+
+    // javadocs here are inherited
     
     public boolean add(int element) {
         add(size(),element);
@@ -142,12 +189,6 @@ public abstract class AbstractRandomAccessIntList extends AbstractIntCollection
         return new RandomAccessIntSubList(this,fromIndex,toIndex);
     }
 
-    /** 
-     * Returns <code>true</code> iff <i>that</i> is 
-     * an {@link IntList} with the same {@link #size size}
-     * as me, and whose {@link #iterator iterator} returns the 
-     * same sequence of values as mine.
-     */
     public boolean equals(Object that) {
         if(this == that) { 
             return true; 
@@ -191,10 +232,12 @@ public abstract class AbstractRandomAccessIntList extends AbstractIntCollection
     // protected utilities
     //-------------------------------------------------------------------------
     
+    /** Get my count of structural modifications. */
     protected int getModCount() {
         return _modCount;
     }
 
+    /** Increment my count of structural modifications. */
     protected void incrModCount() {
         _modCount++;
     }
@@ -207,7 +250,7 @@ public abstract class AbstractRandomAccessIntList extends AbstractIntCollection
     // inner classes
     //-------------------------------------------------------------------------
     
-    protected static class ComodChecker {
+    private static class ComodChecker {
         ComodChecker(AbstractRandomAccessIntList source) {
             _source = source;  
             resyncModCount();             

src/java/org/apache/commons/collections/primitives/ArrayIntList.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/ArrayIntList.java,v 1.3 2003/01/11 21:28:02 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/ArrayIntList.java,v 1.4 2003/01/13 12:59:45 rwaldhoff Exp $
  * ====================================================================
  * The Apache Software License, Version 1.1
  *
@@ -58,9 +58,12 @@
 package org.apache.commons.collections.primitives;
 
 /**
- * A list of <code>int</code> elements backed by an <code>int</code> array.
+ * An {@link IntList} backed by an array of <code>int</code>s.
- *
+ * This implementation supports all optional methods.
- * @version $Revision: 1.3 $ $Date: 2003/01/11 21:28:02 $
+ * 
+ * @since Commons Collections 2.2
+ * @version $Revision: 1.4 $ $Date: 2003/01/13 12:59:45 $
+ * 
  * @author Rodney Waldhoff 
  */
 public class ArrayIntList extends AbstractRandomAccessIntList implements IntList {
@@ -68,11 +71,20 @@ public class ArrayIntList extends AbstractRandomAccessIntList implements IntList
     // constructors
     //-------------------------------------------------------------------------
 
-    protected ArrayIntList() {
+    /** 
+     * Construct an empty list with the default
+     * initial capacity.
+     */
+    public ArrayIntList() {
         this(8);
     }    
 
-    protected ArrayIntList(int initialCapacity) {
+    /**
+     * Construct an empty list with the given
+     * initial capacity.
+     * @throws IllegalArgumentException when <i>initialCapacity</i> is negative
+     */
+    public ArrayIntList(int initialCapacity) {
         if(initialCapacity < 0) {
             throw new IllegalArgumentException("capacity " + initialCapacity);
         }
@@ -80,6 +92,20 @@ public class ArrayIntList extends AbstractRandomAccessIntList implements IntList
         _size = 0;
     }    
 
+    /** 
+     * Constructs a list containing the elements of the given collection, 
+     * in the order they are returned by that collection's iterator.
+     * 
+     * @see ArrayIntList#addAll(org.apache.commons.collections.primitives.IntCollection)
+     * @param that the non-<code>null</code> collection of <code>int</code>s 
+     *        to add
+     * @throws NullPointerException if <i>that</i> is <code>null</code>
+     */
+    public ArrayIntList(IntCollection that) { 
+        this(that.size());
+        addAll(that);
+    }    
+
     // IntList methods
     //-------------------------------------------------------------------------
 
@@ -92,6 +118,20 @@ public class ArrayIntList extends AbstractRandomAccessIntList implements IntList
         return _size;
     }
     
+    /** 
+     * Removes the element at the specified position in 
+     * (optional operation).  Any subsequent elements 
+     * are shifted to the left, subtracting one from their 
+     * indices.  Returns the element that was removed from
+     * the list.
+     * 
+     * @param index the index of the element to remove
+     * @return the value of the element that was removed
+     * 
+     * @throws UnsupportedOperationException when this operation is not 
+     *         supported
+     * @throws IndexOutOfBoundsException if the specified index is out of range
+     */
     public int removeElementAt(int index) {
         checkRange(index);
         incrModCount();
@@ -104,6 +144,19 @@ public class ArrayIntList extends AbstractRandomAccessIntList implements IntList
         return oldval;
     }
     
+    /** 
+     * Replaces the element at the specified 
+     * position in me with the specified element
+     * (optional operation). 
+     * 
+     * @param index the index of the element to change
+     * @param element the value to be stored at the specified position
+     * @return the value previously stored at the specified position
+     * 
+     * @throws UnsupportedOperationException when this operation is not 
+     *         supported
+     * @throws IndexOutOfBoundsException if the specified index is out of range
+     */
     public int set(int index, int element) {
         checkRange(index);
         incrModCount();
@@ -112,6 +165,21 @@ public class ArrayIntList extends AbstractRandomAccessIntList implements IntList
         return oldval;
     }
         
+    /** 
+     * Inserts the specified element at the specified position 
+     * (optional operation). Shifts the element currently 
+     * at that position (if any) and any subsequent elements to the 
+     * right, increasing their indices.
+     * 
+     * @param index the index at which to insert the element
+     * @param element the value to insert
+     * 
+     * @throws UnsupportedOperationException when this operation is not 
+     *         supported
+     * @throws IllegalArgumentException if some aspect of the specified element 
+     *         prevents it from being added to me
+     * @throws IndexOutOfBoundsException if the specified index is out of range
+     */
     public void add(int index, int element) {
         checkRangeIncludingEndpoint(index);
         incrModCount();
@@ -125,6 +193,11 @@ public class ArrayIntList extends AbstractRandomAccessIntList implements IntList
     // capacity methods
     //-------------------------------------------------------------------------
 
+    /** 
+     * Increases my capacity, if necessary, to ensure that I can hold at 
+     * least the number of elements specified by the minimum capacity 
+     * argument without growing.
+     */
     public void ensureCapacity(int mincap) {
         incrModCount();
         if(mincap > _data.length) {
@@ -135,6 +208,10 @@ public class ArrayIntList extends AbstractRandomAccessIntList implements IntList
         }
     }
 
+    /** 
+     * Reduce my capacity, if necessary, to match my
+     * current {@link #size}.
+     */
     public void trimToSize() {
         incrModCount();
         if(_size < _data.length) {
@@ -146,6 +223,7 @@ public class ArrayIntList extends AbstractRandomAccessIntList implements IntList
 
     // private methods
     //-------------------------------------------------------------------------
+    
     private final void checkRange(int index) {
         if(index < 0 || index >= _size) {
             throw new IndexOutOfBoundsException("Should be at least 0 and less than " + _size + ", found " + index);

src/java/org/apache/commons/collections/primitives/ArrayUnsignedShortList.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/ArrayUnsignedShortList.java,v 1.2 2003/01/11 21:28:02 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/ArrayUnsignedShortList.java,v 1.3 2003/01/13 12:59:45 rwaldhoff Exp $
  * ====================================================================
  * The Apache Software License, Version 1.1
  *
@@ -63,11 +63,21 @@ import java.io.ObjectOutputStream;
 import java.io.Serializable;
 
 /**
- * A list of unsigned 16-bit values backed by a <code>short</code> array.
+ * An {@link IntList} backed by an array of unsigned
- * Mutators on this class will reject any <code>int</code> that does not
+ * <code>short</code> values.
- * express an unsigned 16-bit value.
+ * This list stores <code>int</code> values
- *
+ * in the range [{@link #MIN_VALUE <code>0</code>},
- * @version $Revision: 1.2 $ $Date: 2003/01/11 21:28:02 $
+ * {@link #MAX_VALUE <code>65535</code>}] in 16-bits 
+ * per element.  Attempts to use elements outside this 
+ * range may cause an 
+ * {@link IllegalArgumentException IllegalArgumentException} 
+ * to be thrown.
+ * <p />
+ * This implementation supports all optional methods.
+ * 
+ * @since Commons Collections 2.2
+ * @version $Revision: 1.3 $ $Date: 2003/01/13 12:59:45 $
+ * 
  * @author Rodney Waldhoff 
  */
 public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implements IntList, Serializable {
@@ -75,10 +85,19 @@ public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implemen
     // constructors
     //-------------------------------------------------------------------------
 
+    /** 
+     * Construct an empty list with the default
+     * initial capacity.
+     */
     protected ArrayUnsignedShortList() {
         this(8);
     }    
 
+    /**
+     * Construct an empty list with the given
+     * initial capacity.
+     * @throws IllegalArgumentException when <i>initialCapacity</i> is negative
+     */
     protected ArrayUnsignedShortList(int initialCapacity) {
         if(initialCapacity < 0) {
             throw new IllegalArgumentException("capacity " + initialCapacity);
@@ -87,9 +106,33 @@ public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implemen
         _size = 0;
     }    
 
+    /** 
+     * Constructs a list containing the elements of the given collection, 
+     * in the order they are returned by that collection's iterator.
+     * 
+     * @see ArrayIntList#addAll(org.apache.commons.collections.primitives.IntCollection)
+     * @param that the non-<code>null</code> collection of <code>int</code>s 
+     *        to add
+     * @throws NullPointerException if <i>that</i> is <code>null</code>
+     */
+    public ArrayUnsignedShortList(IntCollection that) { 
+        this(that.size());
+        addAll(that);
+    }    
+
     // IntList methods
     //-------------------------------------------------------------------------
 
+    /** 
+     * Returns the element at the specified position within 
+     * me. 
+     * By construction, the returned value will be 
+     * between {@link #MIN_VALUE} and {@link #MAX_VALUE}, inclusive.
+     * 
+     * @param index the index of the element to return
+     * @return the value of the element at the specified position
+     * @throws IndexOutOfBoundsException if the specified index is out of range
+     */
     public int get(int index) {
         checkRange(index);
         return toInt(_data[index]);
@@ -99,6 +142,22 @@ public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implemen
         return _size;
     }
     
+    /** 
+     * Removes the element at the specified position in 
+     * (optional operation).  Any subsequent elements 
+     * are shifted to the left, subtracting one from their 
+     * indices.  Returns the element that was removed from
+     * the list.
+     * By construction, the returned value will be 
+     * between {@link #MIN_VALUE} and {@link #MAX_VALUE}, inclusive.
+     * 
+     * @param index the index of the element to remove
+     * @return the value of the element that was removed
+     * 
+     * @throws UnsupportedOperationException when this operation is not 
+     *         supported
+     * @throws IndexOutOfBoundsException if the specified index is out of range
+     */
     public int removeElementAt(int index) {
         checkRange(index);
         incrModCount();
@@ -111,6 +170,21 @@ public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implemen
         return oldval;
     }
     
+    /** 
+     * Replaces the element at the specified 
+     * position in me with the specified element
+     * (optional operation). 
+     * Throws {@link IllegalArgumentException} if <i>element</i>
+     * is less than {@link #MIN_VALUE} or greater than {@link #MAX_VALUE}.
+     * 
+     * @param index the index of the element to change
+     * @param element the value to be stored at the specified position
+     * @return the value previously stored at the specified position
+     * 
+     * @throws UnsupportedOperationException when this operation is not 
+     *         supported
+     * @throws IndexOutOfBoundsException if the specified index is out of range
+     */
     public int set(int index, int element) {
         assertValidUnsignedShort(element);
         checkRange(index);
@@ -120,6 +194,23 @@ public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implemen
         return oldval;
     }
         
+    /** 
+     * Inserts the specified element at the specified position 
+     * (optional operation). Shifts the element currently 
+     * at that position (if any) and any subsequent elements to the 
+     * right, increasing their indices.
+     * Throws {@link IllegalArgumentException} if <i>element</i>
+     * is less than {@link #MIN_VALUE} or greater than {@link #MAX_VALUE}.
+     * 
+     * @param index the index at which to insert the element
+     * @param element the value to insert
+     * 
+     * @throws UnsupportedOperationException when this operation is not 
+     *         supported
+     * @throws IllegalArgumentException if some aspect of the specified element 
+     *         prevents it from being added to me
+     * @throws IndexOutOfBoundsException if the specified index is out of range
+     */
     public void add(int index, int element) {
         assertValidUnsignedShort(element);
         checkRangeIncludingEndpoint(index);
@@ -134,6 +225,11 @@ public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implemen
     // capacity methods
     //-------------------------------------------------------------------------
 
+    /** 
+     * Increases my capacity, if necessary, to ensure that I can hold at 
+     * least the number of elements specified by the minimum capacity 
+     * argument without growing.
+     */
     public void ensureCapacity(int mincap) {
         incrModCount();
         if(mincap > _data.length) {
@@ -144,6 +240,10 @@ public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implemen
         }
     }
 
+    /** 
+     * Reduce my capacity, if necessary, to match my
+     * current {@link #size}.
+     */
     public void trimToSize() {
         incrModCount();
         if(_size < _data.length) {
@@ -204,11 +304,11 @@ public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implemen
     // attributes
     //-------------------------------------------------------------------------
     
-    /** The maximum possible unsigned 16-bit value. */
+    /** The maximum possible unsigned 16-bit value (<code>0xFFFF</code>). */
     public static final int MAX_VALUE = 0xFFFF;
 
 
-    /** The minimum possible unsigned 16-bit value. */
+    /** The minimum possible unsigned 16-bit value  (<code>0x0000</code>). */
     public static final int MIN_VALUE = 0;
 
     private transient short[] _data = null;

src/java/org/apache/commons/collections/primitives/IntList.java

@@ -1,5 +1,5 @@
 /*
- * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/IntList.java,v 1.11 2003/01/12 15:23:19 rwaldhoff Exp $
+ * $Header: /home/jerenkrantz/tmp/commons/commons-convert/cvs/home/cvs/jakarta-commons//collections/src/java/org/apache/commons/collections/primitives/Attic/IntList.java,v 1.12 2003/01/13 12:59:45 rwaldhoff Exp $
  * ====================================================================
  * The Apache Software License, Version 1.1
  *
@@ -58,20 +58,42 @@
 package org.apache.commons.collections.primitives;
 
 /**
- * An ordered collection (a list) of <code>int</code> values.
+ * An ordered collection of <code>int</code> values.
  *
  * @see org.apache.commons.collections.primitives.adapters.IntListList
  * @see org.apache.commons.collections.primitives.adapters.ListIntList
  *
  * @since Commons Collections 2.2
- * @version $Revision: 1.11 $ $Date: 2003/01/12 15:23:19 $
+ * @version $Revision: 1.12 $ $Date: 2003/01/13 12:59:45 $
  * 
  * @author Rodney Waldhoff 
  */
 public interface IntList extends IntCollection {
+    /** 
+     * Appends the specified element to the end of me
+     * (optional operation).  Returns <code>true</code>
+     * if I changed as a result of this call.
+     * <p/>
+     * If a collection refuses to add the specified
+     * element for any reason other than that it already contains
+     * the element, it <i>must</i> throw an exception (rather than
+     * simply returning <tt>false</tt>).  This preserves the invariant
+     * that a collection always contains the specified element after 
+     * this call returns. 
+     * 
+     * @param element the value whose presence within me is to be ensured
+     * @return <code>true</code> iff I changed as a result of this call
+     * 
+     * @throws UnsupportedOperationException when this operation is not 
+     *         supported
+     * @throws IllegalArgumentException may be thrown if some aspect of the 
+     *         specified element prevents it from being added to me
+     */
+    boolean add(int element);
+       
     /** 
      * Inserts the specified element at the specified position 
-     * within me (optional operation). Shifts the element currently 
+     * (optional operation). Shifts the element currently 
      * at that position (if any) and any subsequent elements to the 
      * right, increasing their indices.
      * 
@@ -134,14 +156,14 @@ public interface IntList extends IntCollection {
         
     /**
      * Returns my hash code.
-     * <p>
+     * <p />
      * The hash code of an <code>IntList</code> is defined to be the
      * result of the following calculation:
      * <pre>int hash = 1;
      * for(IntIterator iter = iterator(); iter.hasNext(); ) {
      *   hash = 31*hash + iter.next();
      * }</pre>
-     * <p>
+     * <p />
      * This contract ensures that this method is consistent with 
      * {@link #equals} and with the {@link java.util.List#hashCode hashCode}
      * method of a {@link java.util.List List} of {@link Integer}s. 
@@ -174,20 +196,25 @@ public interface IntList extends IntCollection {
     int lastIndexOf(int element);
     
     /** 
-     * Returns a {@link IntListIterator list iterator} over all 
+     * Returns a 
-     * my elements in the appropriate sequence.
+     * {@link IntListIterator bidirectional iterator}
+     * over all my elements, in the appropriate sequence.
      */
     IntListIterator listIterator();
     
     /** 
-     * Returns a {@link IntListIterator list iterator}
+     * Returns a 
+     * {@link IntListIterator bidirectional iterator}
      * over my elements, in the appropriate sequence, 
      * starting at the specified position. The 
-     * specified index indicates the first element 
+     * specified <i>index</i> indicates the first 
-     * that would be returned by an initial call 
+     * element that would be returned by an initial 
-     * to the next method. An initial call to the 
+     * call to the 
-     * previous method would return the element 
+     * {@link IntListIterator#next next} 
-     * with the specified index minus one.
+     * method. An initial call to the 
+     * {@link IntListIterator#previous previous}
+     * method would return the element with the specified 
+     * <i>index</i> minus one.
      * 
      * @throws IndexOutOfBoundsException if the specified index is out of range
      */