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 bak.pcj.list;
020:
021: import bak.pcj.IntIterator;
022: import bak.pcj.IntCollection;
023:
024: /**
025: * This interface represents lists of int values.
026: *
027: * @see java.util.List
028: *
029: * @author Søren Bak
030: * @version 1.2 24-08-2003 20:34
031: * @since 1.0
032: */
033: public interface IntList extends IntCollection {
034:
035: /**
036: * Adds an element to this list at a specified index. All
037: * elements from the specified index and forward are pushed
038: * to their successor's indices.
039: *
040: * @param index
041: * the index at which to add the element. If
042: * <tt>index == size()</tt> the element is appended
043: * to this list.
044: *
045: * @param v
046: * the int value to add to this list.
047: *
048: * @throws UnsupportedOperationException
049: * if the operation is not supported by this
050: * list.
051: *
052: * @throws IndexOutOfBoundsException
053: * if <tt>index</tt> does not denote a valid insertion
054: * position (valid: <tt>0 - size()</tt>).
055: *
056: * @see #add(int)
057: * @see #addAll(IntCollection)
058: * @see #addAll(int,IntCollection)
059: */
060: void add(int index, int v);
061:
062: /**
063: * Adds all the elements of a specified collection to
064: * this list starting at a specified index. The elements are
065: * inserted in the specified collection's iteration order.
066: * All elements from the specified index and forward are pushed
067: * to their successors' indices (<tt>c.size()</tt> indices).
068: *
069: * @param index
070: * the index at which to insert the elements of
071: * the specified collection. If
072: * <tt>index == size()</tt> the elements are appended
073: * to this list.
074: *
075: * @param c
076: * the collection whose elements to add to this
077: * list.
078: *
079: * @return <tt>true</tt> if this list was modified
080: * as a result of adding the elements of <tt>c</tt>;
081: * returns <tt>false</tt> otherwise.
082: *
083: * @throws UnsupportedOperationException
084: * if the operation is not supported by this
085: * list.
086: *
087: * @throws NullPointerException
088: * if <tt>c</tt> is <tt>null</tt>.
089: *
090: * @throws IndexOutOfBoundsException
091: * if <tt>index</tt> does not denote a valid insertion
092: * position (valid: <tt>0 - size()</tt>).
093: *
094: * @see #add(int)
095: * @see #add(int, int)
096: * @see #addAll(IntCollection)
097: */
098: boolean addAll(int index, IntCollection c);
099:
100: /**
101: * Returns the element at a specified position in this list.
102: *
103: * @param index
104: * the position of the element to return.
105: *
106: * @return the element at the specified position.
107: *
108: * @throws IndexOutOfBoundsException
109: * if <tt>index</tt> does not denote a valid index
110: * in this list.
111: */
112: int get(int index);
113:
114: /**
115: * Returns the index of the first occurance of a specified
116: * element in this list.
117: *
118: * @param c
119: * the element to find.
120: *
121: * @return the index of the first occurance of the specified
122: * element in this list; returns <tt>-1</tt>, if the
123: * element is not contained in this list.
124: */
125: int indexOf(int c);
126:
127: /**
128: * Returns the index of the first occurance of a specified
129: * element in this list after or at a specified index.
130: *
131: * @param c
132: * the element to find.
133: *
134: * @param index
135: * the index at which to start the search.
136: *
137: * @return the index of the first occurance of the specified
138: * element in this list; returns <tt>-1</tt>, if the
139: * element is not contained in this list.
140: *
141: * @throws IndexOutOfBoundsException
142: * if <tt>index</tt> does not denote a valid
143: * iteration position (valid: <tt>0 - size()</tt>).
144: *
145: * @since 1.2
146: */
147: int indexOf(int index, int c);
148:
149: /**
150: * Returns the index of the last occurance of a specified
151: * element in this list.
152: *
153: * @param c
154: * the element to find.
155: *
156: * @return the index of the last occurance of the specified
157: * element in this list; returns <tt>-1</tt>, if the
158: * element is not contained in this list.
159: */
160: int lastIndexOf(int c);
161:
162: /**
163: * Returns the index of the last occurance of a specified
164: * element in this list before a specified index.
165: *
166: * @param c
167: * the element to find.
168: *
169: * @param index
170: * the index at which to start the search. Note that
171: * the element at <code>index</code> is not included
172: * in the search.
173: *
174: * @return the index of the last occurance of the specified
175: * element in this list; returns <tt>-1</tt>, if the
176: * element is not contained in this list.
177: *
178: * @throws IndexOutOfBoundsException
179: * if <tt>index</tt> does not denote a valid
180: * iteration position (valid: <tt>0 - size()</tt>).
181: *
182: * @since 1.2
183: */
184: int lastIndexOf(int index, int c);
185:
186: /**
187: * Returns a list iterator over this list.
188: *
189: * @return a list iterator over this list.
190: */
191: IntListIterator listIterator();
192:
193: /**
194: * Returns a list iterator over this list, starting from a
195: * specified index.
196: *
197: * @param index
198: * the index at which to begin the iteration.
199: *
200: * @return a list iterator over this list.
201: *
202: * @throws IndexOutOfBoundsException
203: * if <tt>index</tt> does not denote a valid
204: * iteration position (valid: <tt>0 - size()</tt>).
205: */
206: IntListIterator listIterator(int index);
207:
208: /**
209: * Removes the element at a specified index in this list. All
210: * elements following the removed element are pushed to their
211: * predecessor's indices.
212: *
213: * @param index
214: * the index of the element to remove.
215: *
216: * @return the value of the element removed.
217: *
218: * @throws UnsupportedOperationException
219: * if the operation is not supported by this
220: * list.
221: *
222: * @throws IndexOutOfBoundsException
223: * if <tt>index</tt> does not denote a valid
224: * element position (valid: <tt>0 - size()-1</tt>).
225: */
226: int removeElementAt(int index);
227:
228: /**
229: * Sets a specified element to a new value.
230: *
231: * @param index
232: * the index of the element whose value to set.
233: *
234: * @param v
235: * the new value of the specified element.
236: *
237: * @return the previous value of the element.
238: *
239: * @throws UnsupportedOperationException
240: * if the operation is not supported by this
241: * list.
242: *
243: * @throws IndexOutOfBoundsException
244: * if <tt>index</tt> does not denote a valid
245: * element position (valid: <tt>0 - size()-1</tt>).
246: */
247: int set(int index, int v);
248:
249: }
|