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/10 19:47:15 UTC
cvs commit: jakarta-commons/collections/src/java/org/apache/commons/collections/primitives IntCollection.java IntList.java
rwaldhoff 2003/01/10 10:47:15
Modified: collections/src/java/org/apache/commons/collections/primitives
IntCollection.java IntList.java
Log:
javadocs
also fix spelling of "acknowledgment" in the license text
Revision Changes Path
1.2 +122 -40 jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/IntCollection.java
Index: IntCollection.java
===================================================================
RCS file: /home/cvs/jakarta-commons/collections/src/java/org/apache/commons/collections/primitives/IntCollection.java,v
retrieving revision 1.1
retrieving revision 1.2
diff -u -r1.1 -r1.2
--- IntCollection.java 4 Jan 2003 15:00:57 -0000 1.1
+++ IntCollection.java 10 Jan 2003 18:47:15 -0000 1.2
@@ -1,7 +1,5 @@
/*
* $Header$
- * $Revision$
- * $Date$
*
* ====================================================================
*
@@ -23,11 +21,11 @@
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
- * any, must include the following acknowlegement:
+ * any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
- * Alternately, this acknowlegement may appear in the software itself,
- * if and wherever such third-party acknowlegements normally appear.
+ * Alternately, this acknowledgment may appear in the software itself,
+ * if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
@@ -62,98 +60,182 @@
package org.apache.commons.collections.primitives;
/**
- * A {@link java.util.Collection collection} of int values.
+ * A collection of <code>int</code> values.
*
+ * @see org.apache.commons.collections.primitives.adapters.IntCollectionCollection
+ * @see org.apache.commons.collections.primitives.adapters.CollectionIntCollection
+ *
+ * @since Commons Collections 2.2
+ * @version $Revision$ $Date$
+ *
* @version $Revision$ $Date$
* @author Rodney Waldhoff
*/
public interface IntCollection {
-
/**
* Ensures that I contain the specified element
- * (optional operation).
+ * (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);
/**
* {@link #add Adds} all of the elements in the
- * specified collection to me
- * (optional operation).
+ * specified collection to me (optional operation).
+ *
+ * @param c the collection of elements 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 some
+ * specified element prevents it from being added to me
*/
boolean addAll(IntCollection c);
/**
- * Removes all my elements
- * (optional operation).
+ * Removes all my elements (optional operation).
+ * This collection will be {@link #isEmpty empty} after this
+ * method successfully returns.
+ *
+ * @throws UnsupportedOperationException when this operation is not
+ * supported
*/
void clear();
/**
* Returns <code>true</code> iff I contain
* the specified element.
+ *
+ * @param element the value whose presence within me is to be tested
+ * @return <code>true</code> iff I contain the specified element
*/
boolean contains(int element);
/**
- * Returns <code>true</code> iff I contain
- * all of the elements in the given collection.
+ * Returns <code>true</code> iff I {@link #contains contain}
+ * all of the elements in the given collection.
+ *
+ * @param c the collection of elements whose presence within me is to
+ * be tested
+ * @return <code>true</code> iff I contain the all the specified elements
*/
boolean containsAll(IntCollection c);
/**
- * Compares the specified object with me for
- * equality.
- */
- boolean equals(Object o);
-
- /**
- * Returns my hash code value.
- */
- int hashCode();
-
- /**
- * Returns true iff I contains no elements.
+ * Returns <code>true</code> iff I contain no elements.
+ * @return <code>true</code> iff I contain no elements.
*/
boolean isEmpty();
/**
- * Returns an iterator over all my elements.
+ * Returns an {@link IntIterator iterator} over all my elements.
+ * This base interface places no constraints on the order
+ * in which the elements are returned by the returned iterator.
+ * @return an {@link IntIterator iterator} over all my elements.
*/
IntIterator iterator();
/**
- * Removes the first occurrence of the
- * specified element (optional operation).
+ * Removes a single occurrence of the specified element
+ * (optional operation).
+ *
+ * @param element the element to remove, if present
+ * @return <code>true</code> iff I contained the specified element,
+ * in other words, iff I changed as a result of this call
+ *
+ * @throws UnsupportedOperationException when this operation is not
+ * supported
*/
boolean removeElement(int element);
/**
- * Removes from all the elements that are
- * contained in the specified collection
- * (optional operation).
+ * Removes all of my elements that are contained in the
+ * specified collection (optional operation).
+ *
+ * @param c the collection of elements to remove
+ * @return <code>true</code> iff I contained the at least one of the
+ * specified elements, in other words, iff I changed as a result
+ * of this call
+ *
+ * @throws UnsupportedOperationException when this operation is not
+ * supported
*/
boolean removeAll(IntCollection c);
/**
- * Retains only the elements that are
- * contained in the specified collection
- * (optional operation).
+ * Removes all of my elements that are <i>not</i> contained in the
+ * specified collection (optional operation).
+ * (In other words, retains only my elements that are
+ * contained in the specified collection.
+ *
+ * @param c the collection of elements to retain
+ * @return <code>true</code> iff I changed as a result
+ * of this call
+ *
+ * @throws UnsupportedOperationException when this operation is not
+ * supported
*/
boolean retainAll(IntCollection c);
/**
* Returns the number of elements I contain.
+ * @return the number of elements I contain
*/
int size();
/**
- * Returns an array containing all my elements.
+ * Returns an array containing all of my elements.
+ * The length of the returned array should be equal
+ * to the my {@link #size size}.
+ * <p/>
+ * The returned array will be independent of this
+ * collection, so that callers may modify that
+ * returned array without modifying this collection.
+ * <p/>
+ * When this collection guarantees the order in which
+ * elements are returned by an {@link #iterator},
+ * the returned array will contain elements in the
+ * same order.
+ *
+ * @return an array containing all my elements
*/
int[] toArray();
/**
- * Returns an array containing all of the elements
- * in me, using the given array if it is large enough.
+ * Returns an array containing all of my elements,
+ * using the given array if it is large
+ * enough. When the length of the given array is
+ * larger than the number of elements I contain,
+ * values outside of my range will be unchanged.
+ * <p/>
+ * The returned array will be independent of this
+ * collection, so that callers may modify that
+ * returned array without modifying this collection.
+ * <p/>
+ * When this collection guarantees the order in which
+ * elements are returned by an {@link #iterator},
+ * the returned array will contain elements in the
+ * same order.
+ *
+ * @param a an array that may be used to contain the elements
+ * @return an array containing all my elements
*/
int[] toArray(int[] a);
}
1.5 +103 -17 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.4
retrieving revision 1.5
diff -u -r1.4 -r1.5
--- IntList.java 9 Jan 2003 13:40:10 -0000 1.4
+++ IntList.java 10 Jan 2003 18:47:15 -0000 1.5
@@ -1,8 +1,5 @@
/*
* $Header$
- * $Revision$
- * $Date$
- *
* ====================================================================
*
* The Apache Software License, Version 1.1
@@ -23,11 +20,11 @@
* distribution.
*
* 3. The end-user documentation included with the redistribution, if
- * any, must include the following acknowlegement:
+ * any, must include the following acknowledgment:
* "This product includes software developed by the
* Apache Software Foundation (http://www.apache.org/)."
- * Alternately, this acknowlegement may appear in the software itself,
- * if and wherever such third-party acknowlegements normally appear.
+ * Alternately, this acknowledgment may appear in the software itself,
+ * if and wherever such third-party acknowledgments normally appear.
*
* 4. The names "The Jakarta Project", "Commons", and "Apache Software
* Foundation" must not be used to endorse or promote products derived
@@ -64,23 +61,60 @@
import org.apache.commons.collections.primitives.adapters.IntListIterator;
/**
- * An ordered collection (a {@link java.util.List}) of int values.
+ * An ordered collection (a list) 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$ $Date$
+ *
* @author Rodney Waldhoff
*/
public interface IntList extends IntCollection {
/**
* Inserts the specified element at the specified position
- * within me (optional operation).
+ * within me (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 is some aspect of the specified element
+ * prevents it from being added to me
+ * @throws IndexOutOfBoundsException if the specified index is out of range
*/
void add(int index, int element);
+ /**
+ * Inserts all of the elements in the specified collection into me,
+ * 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. The new elements
+ * will appear in the order that they are returned by the given
+ * collection's {@link IntCollection#iterator iterator}.
+ *
+ * @param index the index at which to insert the first element from
+ * the specified collection
+ * @param collection the {@link IntCollection} of elements to add
+ * @return <code>true</code> iff I changed as a result of this call
+ *
+ * @throws UnsupportedOperationException when this operation is not
+ * supported
+ * @throws IndexOutOfBoundsException if the specified index is out of range
+ */
boolean addAll(int index, IntCollection collection);
/**
* Returns the element at the specified position within
* me.
+ *
+ * @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
*/
int get(int index);
@@ -88,36 +122,58 @@
* Returns the index of the first occurrence
* of the specified element within me,
* or <code>-1</code> if I do not contain
- * the this element.
+ * the element.
+ *
+ * @param element the element to search for
+ * @return the smallest index of an element matching the specified value,
+ * or <code>-1</code> if no such matching element can be found
*/
int indexOf(int element);
/**
* Returns the index of the last occurrence
* of the specified element within me,
- * or -1 if I do not contain this element.
+ * or -1 if I do not contain the element.
+ *
+ * @param element the element to search for
+ * @return the largest index of an element matching the specified value,
+ * or <code>-1</code> if no such matching element can be found
*/
int lastIndexOf(int element);
/**
- * Returns a list iterator over all my elements.
+ * Returns a {@link IntListIterator list iterator} over all
+ * my elements in the appropriate sequence.
*/
IntListIterator listIterator();
/**
- * Returns a list iterator over my elements,
+ * Returns a {@link IntListIterator list 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.
+ *
+ * @throws IndexOutOfBoundsException if the specified index is out of range
*/
IntListIterator listIterator(int index);
/**
* Removes the element at the specified position in
- * me (optional operation).
+ * (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
*/
int removeElementAt(int index);
@@ -125,13 +181,43 @@
* 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
*/
int set(int index, int element);
/**
* Returns a view of the elements within me
- * between the specified fromIndex, inclusive, and
- * toIndex, exclusive.
+ * between the specified <i>fromIndex</i>, inclusive, and
+ * <i>toIndex</i>, exclusive. The returned {@link IntList}
+ * is backed by me, so that any changes in
+ * the returned list are reflected in me, and vice-versa.
+ * The returned list supports all of the optional operations
+ * that I support.
+ * <p/>
+ * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
+ * the returned list is empty, and when
+ * <code><i>fromIndex</i> == 0 && <i>fromIndex</i> == {@link #size() size()}</code>
+ * the returned list is my "improper" sublist, containing all my elements.
+ * <p/>
+ * The semantics of the returned list become undefined
+ * if I am structurally modified in any way other than
+ * via the returned list.
+ *
+ * @param fromIndex the smallest index (inclusive) in me that appears in
+ * the returned list
+ * @param toIndex the largest index (exclusive) in me that appears in the
+ * returned list
+ * @return a view of this list from <i>fromIndex</i> (inclusive) to
+ * <i>toIndex</i> exclusive
+ *
+ * @throws IndexOutOfBoundsException if either specified index is out of range
*/
IntList subList(int fromIndex, int toIndex);
--
To unsubscribe, e-mail: <ma...@jakarta.apache.org>
For additional commands, e-mail: <ma...@jakarta.apache.org>