You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@commons.apache.org by rw...@apache.org on 2003/01/13 13:59:45 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections/primitives AbstractRandomAccessIntList.java ArrayIntList.java ArrayUnsignedShortList.java IntList.java
rwaldhoff 2003/01/13 04:59:45
Modified: collections/src/java/org/apache/commons/collections/primitives
AbstractRandomAccessIntList.java ArrayIntList.java
ArrayUnsignedShortList.java IntList.java
Log:
* add copy constructors to AbstractRandomAccessIntList, ArrayIntList and ArrayUnsignedShortList
* more javadocs
Revision Changes Path
1.8 +53 -10 jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/AbstractRandomAccessIntList.java
Index: AbstractRandomAccessIntList.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/AbstractRandomAccessIntList.java,v
retrieving revision 1.7
retrieving revision 1.8
diff -u -r1.7 -r1.8
--- AbstractRandomAccessIntList.java 11 Jan 2003 21:28:02 -0000 1.7
+++ AbstractRandomAccessIntList.java 13 Jan 2003 12:59:45 -0000 1.8
@@ -60,13 +60,46 @@
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$ $Date$
+ *
+ * @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 @@
// 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 @@
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 @@
// 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 @@
// inner classes
//-------------------------------------------------------------------------
- protected static class ComodChecker {
+ private static class ComodChecker {
ComodChecker(AbstractRandomAccessIntList source) {
_source = source;
resyncModCount();
1.4 +84 -6 jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/ArrayIntList.java
Index: ArrayIntList.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/ArrayIntList.java,v
retrieving revision 1.3
retrieving revision 1.4
diff -u -r1.3 -r1.4
--- ArrayIntList.java 11 Jan 2003 21:28:02 -0000 1.3
+++ ArrayIntList.java 13 Jan 2003 12:59:45 -0000 1.4
@@ -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.
+ *
+ * @since Commons Collections 2.2
* @version $Revision$ $Date$
+ *
* @author Rodney Waldhoff
*/
public class ArrayIntList extends AbstractRandomAccessIntList implements IntList {
@@ -68,11 +71,20 @@
// 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 @@
_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 @@
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 @@
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 @@
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 @@
// 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 @@
}
}
+ /**
+ * Reduce my capacity, if necessary, to match my
+ * current {@link #size}.
+ */
public void trimToSize() {
incrModCount();
if(_size < _data.length) {
@@ -146,6 +223,7 @@
// 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);
1.3 +108 -8 jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/ArrayUnsignedShortList.java
Index: ArrayUnsignedShortList.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/ArrayUnsignedShortList.java,v
retrieving revision 1.2
retrieving revision 1.3
diff -u -r1.2 -r1.3
--- ArrayUnsignedShortList.java 11 Jan 2003 21:28:02 -0000 1.2
+++ ArrayUnsignedShortList.java 13 Jan 2003 12:59:45 -0000 1.3
@@ -63,11 +63,21 @@
import java.io.Serializable;
/**
- * A list of unsigned 16-bit values backed by a <code>short</code> array.
- * Mutators on this class will reject any <code>int</code> that does not
- * express an unsigned 16-bit value.
- *
+ * An {@link IntList} backed by an array of unsigned
+ * <code>short</code> values.
+ * This list stores <code>int</code> values
+ * in the range [{@link #MIN_VALUE <code>0</code>},
+ * {@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$ $Date$
+ *
* @author Rodney Waldhoff
*/
public class ArrayUnsignedShortList extends AbstractRandomAccessIntList implements IntList, Serializable {
@@ -75,10 +85,19 @@
// 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 @@
_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 @@
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 @@
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 @@
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 @@
// 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 @@
}
}
+ /**
+ * Reduce my capacity, if necessary, to match my
+ * current {@link #size}.
+ */
public void trimToSize() {
incrModCount();
if(_size < _data.length) {
@@ -204,11 +304,11 @@
// 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;
1.12 +41 -14 jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/IntList.java
Index: IntList.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/IntList.java,v
retrieving revision 1.11
retrieving revision 1.12
diff -u -r1.11 -r1.12
--- IntList.java 12 Jan 2003 15:23:19 -0000 1.11
+++ IntList.java 13 Jan 2003 12:59:45 -0000 1.12
@@ -58,7 +58,7 @@
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
@@ -70,8 +70,30 @@
*/
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 @@
/**
* 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 @@
int lastIndexOf(int element);
/**
- * Returns a {@link IntListIterator list iterator} over all
- * my elements in the appropriate sequence.
+ * Returns a
+ * {@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
- * that would be returned by an initial call
- * to the next method. An initial call to the
- * previous method would return the element
- * with the specified index minus one.
+ * specified <i>index</i> indicates the first
+ * element that would be returned by an initial
+ * call to the
+ * {@link IntListIterator#next next}
+ * 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
*/
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>