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