001/*
002 *  Copyright 2001-2010 Stephen Colebourne
003 *
004 *  Licensed under the Apache License, Version 2.0 (the "License");
005 *  you may not use this file except in compliance with the License.
006 *  You may obtain a copy of the License at
007 *
008 *      http://www.apache.org/licenses/LICENSE-2.0
009 *
010 *  Unless required by applicable law or agreed to in writing, software
011 *  distributed under the License is distributed on an "AS IS" BASIS,
012 *  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 *  See the License for the specific language governing permissions and
014 *  limitations under the License.
015 */
016package org.joda.primitives.collection;
017
018import org.joda.primitives.iterable.BooleanIterable;
019import org.joda.primitives.iterator.BooleanIterator;
020
021/**
022 * Defines a collection of primitive <code>boolean</code> values.
023 * <p>
024 * This interface extends {@link java.util.Collection Collection} allowing
025 * seamless integration with other APIs.
026 * All Collection methods can be used, using the primitive wrapper class {@link Boolean}.
027 * However, it will be <em>much</em> more efficient to use the methods defined here.
028 * 
029 * @author Stephen Colebourne
030 * @author Jason Tiscione
031 * @version CODE GENERATED
032 * @since 1.0
033 */
034public interface BooleanCollection extends PrimitiveCollection<Boolean>, BooleanIterable {
035    // This file is CODE GENERATED. Do not change manually.
036
037    // Mandatory operations
038    //-----------------------------------------------------------------------
039    /**
040     * Gets an iterator over this collection capable of accessing the primitive values.
041     *
042     * @return an iterator over this collection, not null
043     */
044    BooleanIterator iterator();
045    // This method is specified here, despite being in {@code BooleanIterable},
046    // due to compiler bug 6487370.
047
048    /**
049     * Checks whether this collection contains a specified primitive value.
050     *
051     * @param value  the value to search for
052     * @return <code>true</code> if the value is found
053     */
054    boolean contains(boolean value);
055
056    /**
057     * Checks if this collection contains all of the values in the specified array.
058     * If the specified array is empty, <code>true</code> is returned.
059     *
060     * @param values  the values to search for, null treated as empty array
061     * @return <code>true</code> if all of the values are found
062     */
063    boolean containsAll(boolean[] values);
064
065    /**
066     * Checks if this collection contains all of the values in the specified collection.
067     * If the specified collection is empty, <code>true</code> is returned.
068     *
069     * @param values  the values to search for, null treated as empty collection
070     * @return <code>true</code> if all of the values are found
071     */
072    boolean containsAll(BooleanCollection values);
073
074    /**
075     * Checks if this collection contains any of the values in the specified array.
076     * If the specified array is empty, <code>false</code> is returned.
077     *
078     * @param values  the values to search for, null treated as empty array
079     * @return <code>true</code> if at least one of the values is found
080     */
081    boolean containsAny(boolean[] values);
082
083    /**
084     * Checks if this collection contains any of the values in the specified collection.
085     * If the specified collection is empty, <code>false</code> is returned.
086     *
087     * @param coll  the values to search for, null treated as empty collection
088     * @return <code>true</code> if at least one of the values is found
089     */
090    boolean containsAny(BooleanCollection coll);
091
092    /**
093     * Gets the elements of this collection as an array.
094     *
095     * @return a new array containing a copy of the elements of this collection
096     */
097    boolean[] toBooleanArray();
098
099    /**
100     * Copies the elements of this collection into an array at a specified position.
101     * Previous values in the array are overwritten.
102     * <p>
103     * If the array specified is null a new array is created.
104     * If the array specified is large enough, it will be modified.
105     * If the array is not large enough, a new array will be created containing the
106     * values from the specified array before the startIndex plus those from this collection.
107     *
108     * @param array  the array to add the elements to, null creates new array
109     * @param startIndex  the position in the array to start setting elements
110     * @return the array with the populated collection, not null
111     * @throws IndexOutOfBoundsException if the index is negative
112     */
113    boolean[] toBooleanArray(boolean[] array, int startIndex);
114
115    // Optional operations
116    //-----------------------------------------------------------------------
117    /**
118     * Adds a primitive value to this collection (optional operation).
119     * <p>
120     * This method is optional, throwing an UnsupportedOperationException if the
121     * collection cannot be added to.
122     *
123     * @param value  the value to add to this collection
124     * @return <code>true</code> if this collection was modified by this method call
125     * @throws IllegalArgumentException if value is rejected by this collection
126     * @throws UnsupportedOperationException if not supported by this collection
127     */
128    boolean add(boolean value);
129
130    /**
131     * Adds an array of primitive values to this collection (optional operation).
132     * <p>
133     * This method is optional, throwing an UnsupportedOperationException if the
134     * collection cannot be added to.
135     *
136     * @param values  the values to add to this collection, null treated as empty array
137     * @return <code>true</code> if this collection was modified by this method call
138     * @throws IllegalArgumentException if a value is rejected by this collection
139     * @throws UnsupportedOperationException if not supported by this collection
140     */
141    boolean addAll(boolean[] values);
142
143    /**
144     * Adds a collection of primitive values to this collection (optional operation).
145     * <p>
146     * This method is optional, throwing an UnsupportedOperationException if the
147     * collection cannot be added to.
148     *
149     * @param values  the values to add to this collection, null treated as empty collection
150     * @return <code>true</code> if this collection was modified by this method call
151     * @throws IllegalArgumentException if a value is rejected by this collection
152     * @throws UnsupportedOperationException if not supported by this collection
153     */
154    boolean addAll(BooleanCollection values);
155
156    /**
157     * Removes the first occurrence of the specified primitive value from this collection
158     * (optional operation).
159     * <p>
160     * This method is optional, throwing an UnsupportedOperationException if the
161     * collection cannot be removed from.
162     *
163     * @param value  the value to remove
164     * @return <code>true</code> if this collection was modified by this method call
165     * @throws UnsupportedOperationException if not supported by this collection
166     */
167    boolean removeFirst(boolean value);
168
169    /**
170     * Removes all occurrences of the specified primitive value from this collection
171     * (optional operation).
172     * <p>
173     * This method is optional, throwing an UnsupportedOperationException if the
174     * collection cannot be removed from.
175     *
176     * @param value  the value to remove
177     * @return <code>true</code> if this collection was modified by this method call
178     * @throws UnsupportedOperationException if not supported by this collection
179     */
180    boolean removeAll(boolean value);
181
182    /**
183     * Removes all occurrences from this collection of each primitive in the specified array
184     * (optional operation).
185     * <p>
186     * This method is optional, throwing an UnsupportedOperationException if the
187     * collection cannot be removed from.
188     *
189     * @param values  the values to remove from this collection, null treated as empty array
190     * @return <code>true</code> if this collection was modified by this method call
191     * @throws UnsupportedOperationException if not supported by this collection
192     */
193    boolean removeAll(boolean[] values);
194
195    /**
196     * Removes all occurrences from this collection of each primitive in the specified collection
197     * (optional operation).
198     * <p>
199     * This method is optional, throwing an UnsupportedOperationException if the
200     * collection cannot be removed from.
201     *
202     * @param values  the values to remove from this collection, null treated as empty collection
203     * @return <code>true</code> if this collection was modified by this method call
204     * @throws UnsupportedOperationException if not supported by this collection
205     */
206    boolean removeAll(BooleanCollection values);
207
208    /**
209     * Retains each element of this collection that is present in the specified array
210     * removing all other values (optional operation).
211     * <p>
212     * This method is optional, throwing an UnsupportedOperationException if the
213     * collection cannot be removed from.
214     *
215     * @param values  the values to retain in this collection, null treated as empty array
216     * @return <code>true</code> if this collection was modified by this method call
217     * @throws UnsupportedOperationException if not supported by this collection
218     */
219    boolean retainAll(boolean[] values);
220
221    /**
222     * Retains each element of this collection that is present in the specified collection
223     * removing all other values (optional operation).
224     * <p>
225     * This method is optional, throwing an UnsupportedOperationException if the
226     * collection cannot be removed from.
227     *
228     * @param values  the values to retain in this collection, null treated as empty collection
229     * @return <code>true</code> if this collection was modified by this method call
230     * @throws UnsupportedOperationException if not supported by this collection
231     */
232    boolean retainAll(BooleanCollection values);
233
234}