001: /*
002: * Primitive Collections for Java.
003: * Copyright (C) 2002 S�ren Bak
004: *
005: * This library is free software; you can redistribute it and/or
006: * modify it under the terms of the GNU Lesser General Public
007: * License as published by the Free Software Foundation; either
008: * version 2.1 of the License, or (at your option) any later version.
009: *
010: * This library is distributed in the hope that it will be useful,
011: * but WITHOUT ANY WARRANTY; without even the implied warranty of
012: * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
013: * Lesser General Public License for more details.
014: *
015: * You should have received a copy of the GNU Lesser General Public
016: * License along with this library; if not, write to the Free Software
017: * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
018: */
019: package com.uwyn.rife.pcj;
020:
021: /**
022: * This interface defines collections of int values.
023: *
024: * @see java.util.Collection
025: *
026: * @author Søren Bak
027: * @version 1.1 2002/30/12
028: * @since 1.0
029: */
030: public interface IntCollection {
031:
032: /**
033: * Adds an element to this collection.
034: *
035: * @param v
036: * the element to add to this collection.
037: *
038: * @return <tt>true</tt> if this collection was modified
039: * as a result of adding <tt>v</tt>; returns
040: * <tt>false</tt> otherwise.
041: *
042: * @throws UnsupportedOperationException
043: * if the operation is not supported by this
044: * collection.
045: *
046: * @see #addAll(IntCollection)
047: */
048: boolean add(int v);
049:
050: /**
051: * Adds all the elements of a specified collection to
052: * this collection.
053: *
054: * @param c
055: * the collection whose elements to add to this
056: * collection.
057: *
058: * @return <tt>true</tt> if this collection was modified
059: * as a result of adding the elements of <tt>c</tt>;
060: * returns <tt>false</tt> otherwise.
061: *
062: * @throws UnsupportedOperationException
063: * if the operation is not supported by this
064: * collection.
065: *
066: * @throws NullPointerException
067: * if <tt>c</tt> is <tt>null</tt>.
068: *
069: * @see #add(int)
070: */
071: boolean addAll(IntCollection c);
072:
073: /**
074: * Clears this collection.
075: *
076: * @throws UnsupportedOperationException
077: * if the operation is not supported by this
078: * collection.
079: */
080: void clear();
081:
082: /**
083: * Indicates whether this collection contains a specified
084: * element.
085: *
086: * @param v
087: * the element to test for containment.
088: *
089: * @return <tt>true</tt> if <tt>v</tt> is contained in this
090: * collection; returns <tt>false</tt> otherwise.
091: *
092: * @see #containsAll(IntCollection)
093: */
094: boolean contains(int v);
095:
096: /**
097: * Indicates whether all elements of a specified
098: * collection is contained in this collection.
099: *
100: * @param c
101: * the collection whose elements to test for
102: * containment.
103: *
104: * @return <tt>true</tt> if all the elements of <tt>c</tt>
105: * are contained in this collection; returns
106: * <tt>false</tt> otherwise.
107: *
108: * @throws NullPointerException
109: * if <tt>c</tt> is <tt>null</tt>.
110: *
111: * @see #contains(int)
112: */
113: boolean containsAll(IntCollection c);
114:
115: /**
116: * Indicates whether this collection is equal to some object.
117: *
118: * @param obj
119: * the object with which to compare this collection.
120: *
121: * @return <tt>true</tt> if this collection is equals to
122: * <tt>obj</tt>; returns <tt>false</tt> otherwise.
123: */
124: boolean equals(Object obj);
125:
126: /**
127: * Returns a hash code value for this collection.
128: *
129: * @return a hash code value for this collection.
130: */
131: int hashCode();
132:
133: /**
134: * Indicates whether this collection is empty.
135: *
136: * @return <tt>true</tt> if this collection is empty; returns
137: * <tt>false</tt> otherwise.
138: */
139: boolean isEmpty();
140:
141: /**
142: * Returns an iterator over this collection.
143: *
144: * @return an iterator over this collection.
145: */
146: IntIterator iterator();
147:
148: /**
149: * Removes a specified element from this collection.
150: *
151: * @param v
152: * the int value to remove from this collection.
153: *
154: * @return <tt>true</tt> if this collection was modified
155: * as a result of removing <tt>v</tt>; returns
156: * <tt>false</tt> otherwise.
157: *
158: * @throws UnsupportedOperationException
159: * if the operation is not supported by this
160: * collection.
161: */
162: boolean remove(int v);
163:
164: /**
165: * Removes all the elements of a specified collection from
166: * this collection.
167: *
168: * @param c
169: * the collection whose elements to remove from this
170: * collection.
171: *
172: * @return <tt>true</tt> if this collection was modified
173: * as a result of removing the elements of <tt>c</tt>;
174: * returns <tt>false</tt> otherwise.
175: *
176: * @throws UnsupportedOperationException
177: * if the operation is not supported by this
178: * collection.
179: *
180: * @throws NullPointerException
181: * if <tt>c</tt> is <tt>null</tt>.
182: */
183: boolean removeAll(IntCollection c);
184:
185: /**
186: * Retains only the elements of a specified collection in
187: * this collection.
188: *
189: * @param c
190: * the collection whose elements to retain in this
191: * collection.
192: *
193: * @return <tt>true</tt> if this collection was modified
194: * as a result of removing the elements not contained
195: * in <tt>c</tt>;
196: * returns <tt>false</tt> otherwise.
197: *
198: * @throws UnsupportedOperationException
199: * if the operation is not supported by this
200: * collection.
201: *
202: * @throws NullPointerException
203: * if <tt>c</tt> is <tt>null</tt>.
204: */
205: boolean retainAll(IntCollection c);
206:
207: /**
208: * Returns the number of elements in this collection.
209: *
210: * @return the number of elements in this collection.
211: */
212: int size();
213:
214: /**
215: * Returns the elements of this collection as an array.
216: *
217: * @return a new array containing the elements of this
218: * collection.
219: */
220: int[] toArray();
221:
222: /**
223: * Returns the elements of this collection as an array.
224: *
225: * @param a
226: * an array to fill with the elements of this
227: * collection; if <tt>a</tt> is <tt>null</tt> or not
228: * big enough to contain all the elements of this
229: * collection, an new array is allocated,
230: * and <tt>a</tt> is not changed.
231: *
232: * @return <tt>a</tt>, if <tt>a</tt> has room for all the
233: * elements of this collection; otherwise a new
234: * array is allocated, filled with the elements of
235: * this collection, and returned.
236: */
237: int[] toArray(int[] a);
238:
239: /**
240: * Minimizes the memory used by this collection. The exact
241: * operation of this method depends on the class implementing it.
242: * Implementors may choose to ignore it completely.
243: */
244: void trimToSize();
245:
246: }
|