BooleanList


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 00:14:21 -0800 (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 }
235
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags