1 /*
2 * Licensed to the Apache Software Foundation (ASF) under one or more
3 * contributor license agreements. See the NOTICE file distributed with
4 * this work for additional information regarding copyright ownership.
5 * The ASF licenses this file to You under the Apache License, Version 2.0
6 * (the "License"); you may not use this file except in compliance with
7 * the License. You may obtain a copy of the License at
8 *
9 * http://www.apache.org/licenses/LICENSE-2.0
10 *
11 * Unless required by applicable law or agreed to in writing, software
12 * distributed under the License is distributed on an "AS IS" BASIS,
13 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14 * See the License for the specific language governing permissions and
15 * limitations under the License.
16 */
17 package org.apache.commons.collections.primitives;
18
19 /**
20 * An ordered collection of <code>byte</code> values.
21 *
22 * @see org.apache.commons.collections.primitives.adapters.ByteListList
23 * @see org.apache.commons.collections.primitives.adapters.ListByteList
24 *
25 * @since Commons Primitives 1.0
26 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
27 *
28 * @author Rodney Waldhoff
29 */
30 public interface ByteList extends ByteCollection {
31 /**
32 * Appends the specified element to the end of me
33 * (optional operation). Returns <code>true</code>
34 * iff I changed as a result of this call.
35 * <p/>
36 * If a collection refuses to add the specified
37 * element for any reason other than that it already contains
38 * the element, it <i>must</i> throw an exception (rather than
39 * simply returning <tt>false</tt>). This preserves the invariant
40 * that a collection always contains the specified element after
41 * this call returns.
42 *
43 * @param element the value whose presence within me is to be ensured
44 * @return <code>true</code> iff I changed as a result of this call
45 *
46 * @throws UnsupportedOperationException when this operation is not
47 * supported
48 * @throws IllegalArgumentException may be thrown if some aspect of the
49 * specified element prevents it from being added to me
50 */
51 boolean add(byte element);
52
53 /**
54 * Inserts the specified element at the specified position
55 * (optional operation). Shifts the element currently
56 * at that position (if any) and any subsequent elements to the
57 * right, increasing their indices.
58 *
59 * @param index the index at which to insert the element
60 * @param element the value to insert
61 *
62 * @throws UnsupportedOperationException when this operation is not
63 * supported
64 * @throws IllegalArgumentException if some aspect of the specified element
65 * prevents it from being added to me
66 * @throws IndexOutOfBoundsException if the specified index is out of range
67 */
68 void add(int index, byte element);
69
70 /**
71 * Inserts all of the elements in the specified collection into me,
72 * at the specified position (optional operation). Shifts the
73 * element currently at that position (if any) and any subsequent
74 * elements to the right, increasing their indices. The new elements
75 * will appear in the order that they are returned by the given
76 * collection's {@link ByteCollection#iterator iterator}.
77 *
78 * @param index the index at which to insert the first element from
79 * the specified collection
80 * @param collection the {@link ByteCollection ByteCollection} of elements to add
81 * @return <code>true</code> iff I changed as a result of this call
82 *
83 * @throws UnsupportedOperationException when this operation is not
84 * supported
85 * @throws IndexOutOfBoundsException if the specified index is out of range
86 */
87 boolean addAll(int index, ByteCollection collection);
88
89 /**
90 * Returns <code>true</code> iff <i>that</i> is an <code>ByteList</code>
91 * that contains the same elements in the same order as me.
92 * In other words, returns <code>true</code> iff <i>that</i> is
93 * a <code>ByteList</code> that has the same {@link #size() size} as me,
94 * and for which the elements returned by its
95 * {@link ByteList#iterator iterator} are equal (<code>==</code>) to
96 * the corresponding elements within me.
97 * (This contract ensures that this method works properly across
98 * different implementations of the <code>ByteList</code> interface.)
99 *
100 * @param that the object to compare to me
101 * @return <code>true</code> iff <i>that</i> is an <code>ByteList</code>
102 * that contains the same elements in the same order as me
103 */
104 boolean equals(Object that);
105
106 /**
107 * Returns the value of the element at the specified position
108 * within me.
109 *
110 * @param index the index of the element to return
111 * @return the value of the element at the specified position
112 * @throws IndexOutOfBoundsException if the specified index is out of range
113 */
114 byte get(int index);
115
116 /**
117 * Returns my hash code.
118 * <p />
119 * The hash code of an <code>ByteList</code> is defined to be the
120 * result of the following calculation:
121 * <pre> int hash = 1;
122 * for(ByteIterator iter = iterator(); iter.hasNext(); ) {
123 * byte value = iter.next();
124 * hash = 31*hash + (int)(value ^ (value >>> 32));
125 * }</pre>
126 * <p />
127 * This contract ensures that this method is consistent with
128 * {@link #equals equals} and with the
129 * {@link java.util.List#hashCode hashCode}
130 * method of a {@link java.util.List List} of {@link Byte}s.
131 *
132 * @return my hash code
133 */
134 int hashCode();
135
136 /**
137 * Returns the index of the first occurrence
138 * of the specified element within me,
139 * or <code>-1</code> if I do not contain
140 * the element.
141 *
142 * @param element the element to search for
143 * @return the smallest index of an element matching the specified value,
144 * or <code>-1</code> if no such matching element can be found
145 */
146 int indexOf(byte element);
147
148 /**
149 * Returns an {@link ByteIterator iterator} over all my elements,
150 * in the appropriate sequence.
151 * @return an {@link ByteIterator iterator} over all my elements.
152 */
153 ByteIterator iterator();
154
155 /**
156 * Returns the index of the last occurrence
157 * of the specified element within me,
158 * or -1 if I do not contain the element.
159 *
160 * @param element the element to search for
161 * @return the largest index of an element matching the specified value,
162 * or <code>-1</code> if no such matching element can be found
163 */
164 int lastIndexOf(byte element);
165
166 /**
167 * Returns a
168 * {@link ByteListIterator bidirectional iterator}
169 * over all my elements, in the appropriate sequence.
170 */
171 ByteListIterator listIterator();
172
173 /**
174 * Returns a
175 * {@link ByteListIterator bidirectional iterator}
176 * over all my elements, in the appropriate sequence,
177 * starting at the specified position. The
178 * specified <i>index</i> indicates the first
179 * element that would be returned by an initial
180 * call to the
181 * {@link ByteListIterator#next next}
182 * method. An initial call to the
183 * {@link ByteListIterator#previous previous}
184 * method would return the element with the specified
185 * <i>index</i> minus one.
186 *
187 * @throws IndexOutOfBoundsException if the specified index is out of range
188 */
189 ByteListIterator listIterator(int index);
190
191 /**
192 * Removes the element at the specified position in
193 * (optional operation). Any subsequent elements
194 * are shifted to the left, subtracting one from their
195 * indices. Returns the element that was removed.
196 *
197 * @param index the index of the element to remove
198 * @return the value of the element that was removed
199 *
200 * @throws UnsupportedOperationException when this operation is not
201 * supported
202 * @throws IndexOutOfBoundsException if the specified index is out of range
203 */
204 byte removeElementAt(int index);
205
206 /**
207 * Replaces the element at the specified
208 * position in me with the specified element
209 * (optional operation).
210 *
211 * @param index the index of the element to change
212 * @param element the value to be stored at the specified position
213 * @return the value previously stored at the specified position
214 *
215 * @throws UnsupportedOperationException when this operation is not
216 * supported
217 * @throws IndexOutOfBoundsException if the specified index is out of range
218 */
219 byte set(int index, byte element);
220
221 /**
222 * Returns a view of the elements within me
223 * between the specified <i>fromIndex</i>, inclusive, and
224 * <i>toIndex</i>, exclusive. The returned <code>ByteList</code>
225 * is backed by me, so that any changes in
226 * the returned list are reflected in me, and vice-versa.
227 * The returned list supports all of the optional operations
228 * that I support.
229 * <p/>
230 * Note that when <code><i>fromIndex</i> == <i>toIndex</i></code>,
231 * the returned list is initially empty, and when
232 * <code><i>fromIndex</i> == 0 && <i>toIndex</i> == {@link #size() size()}</code>
233 * the returned list is my "improper" sublist, containing all my elements.
234 * <p/>
235 * The semantics of the returned list become undefined
236 * if I am structurally modified in any way other than
237 * via the returned list.
238 *
239 * @param fromIndex the smallest index (inclusive) in me that appears in
240 * the returned list
241 * @param toIndex the largest index (exclusive) in me that appears in the
242 * returned list
243 * @return a view of this list from <i>fromIndex</i> (inclusive) to
244 * <i>toIndex</i> (exclusive)
245 *
246 * @throws IndexOutOfBoundsException if either specified index is out of range
247 */
248 ByteList subList(int fromIndex, int toIndex);
249
250 }