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