001/*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements.  See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License.  You may obtain a copy of the License at
008 *
009 *     http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017package org.apache.commons.collections.primitives;
018
019/**
020 * An ordered collection of <code>byte</code> values.
021 *
022 * @see org.apache.commons.collections.primitives.adapters.BooleanListList
023 * @see org.apache.commons.collections.primitives.adapters.BooleanByteList
024 *
025 * @since Commons Primitives 1.1
026 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
027 */
028public interface BooleanList extends BooleanCollection {
029    /** 
030     * Appends the specified element to the end of me (optional operation).
031     * Returns <code>true</code> iff I changed as a result of this call.
032     * <p/>
033     * If a collection refuses to add the specified element for any reason
034     * other than that it already contains the element, it <i>must</i>
035     * throw an exception (rather than simply returning <tt>false</tt>).
036     * This preserves the invariant that a collection always contains the
037     * specified element after this call returns.
038     * 
039     * @param element the value whose presence within me is to be ensured
040     * @return <code>true</code> iff I changed as a result of this call
041     * 
042     * @throws UnsupportedOperationException when this operation is not 
043     *         supported
044     * @throws IllegalArgumentException may be thrown if some aspect of the 
045     *         specified element prevents it from being added to me
046     */
047    boolean add(boolean element);
048       
049    /** 
050     * Inserts the specified element at the specified position (optional
051     * operation). Shifts the element currently at that position (if any)
052     * and any subsequent elements to the right, increasing their indices.
053     * 
054     * @param index the index at which to insert the element
055     * @param element the value to insert
056     * 
057     * @throws UnsupportedOperationException when this operation is not 
058     *         supported
059     * @throws IllegalArgumentException if some aspect of the specified element 
060     *         prevents it from being added to me
061     * @throws IndexOutOfBoundsException if the specified index is out of range
062     */
063    void add(int index, boolean element);
064          
065    /** 
066     * Inserts all of the elements in the specified collection into me,
067     * at the specified position (optional operation).  Shifts the 
068     * element currently at that position (if any) and any subsequent 
069     * elements to the right, increasing their indices.  The new elements 
070     * will appear in the order that they are returned by the given 
071     * collection's {@link BooleanCollection#iterator iterator}.
072     * 
073     * @param index the index at which to insert the first element from 
074     *        the specified collection
075     * @param collection the {@link BooleanCollection ByteCollection} of
076     *        elements to add
077     * @return <code>true</code> iff I changed as a result of this call
078     * 
079     * @throws UnsupportedOperationException when this operation is not 
080     *         supported
081     * @throws IndexOutOfBoundsException if the specified index is out of range
082     */
083    boolean addAll(int index, BooleanCollection collection);
084    
085    /**
086     * Returns <code>true</code> iff <i>that</i> is an <code>BooleanList</code>
087     * that contains the same elements in the same order as me.
088     * In other words, returns <code>true</code> iff <i>that</i> is
089     * a <code>BooleanList</code> that has the same {@link #size() size} as me,
090     * and for which the elements returned by its 
091     * {@link BooleanList#iterator iterator} are equal (<code>==</code>) to
092     * the corresponding elements within me.
093     * (This contract ensures that this method works properly across 
094     * different implementations of the <code>BooleanList</code> interface.)
095     * 
096     * @param that the object to compare to me
097     * @return <code>true</code> iff <i>that</i> is an <code>BooleanList</code>
098     *         that contains the same elements in the same order as me
099     */
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}