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     */
017    package 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 09:14:21 +0100 (Wed, 29 Nov 2006) $
027     */
028    public 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    }