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 * A collection of <code>boolean</code> values.
021 *
022 * @see org.apache.commons.collections.primitives.adapters.BooleanCollectionCollection
023 * @see org.apache.commons.collections.primitives.adapters.CollectionBooleanCollection
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 BooleanCollection
029{
030    /** 
031     * Ensures that I contain the specified element (optional operation).
032     * Returns <code>true</code> iff I changed as a result of this call.
033     * <p/>
034     * If a collection refuses to add the specified element for any reason
035     * other than that it already contains the element, it <i>must</i>
036     * throw an exception (rather than simply returning <tt>false</tt>).
037     * This preserves the invariant that a collection always contains the
038     * specified element after this call returns.
039     * 
040     * @param element the value whose presence within me is to be ensured
041     * @return <code>true</code> iff I changed as a result of this call
042     * 
043     * @throws UnsupportedOperationException when this operation is not 
044     *         supported
045     * @throws IllegalArgumentException may be thrown if some aspect of the 
046     *         specified element prevents it from being added to me
047     */
048    boolean add(boolean element);
049
050    /** 
051     * {@link #add Adds} all of the elements in the specified collection to
052     * me (optional operation).
053     * 
054     * @param c the collection of elements whose presence within me is to 
055     *        be ensured
056     * @return <code>true</code> iff I changed as a result of this call
057     * 
058     * @throws UnsupportedOperationException when this operation is not 
059     *         supported
060     * @throws IllegalArgumentException may be thrown if some aspect of some 
061     *         specified element prevents it from being added to me
062     */ 
063    boolean addAll(BooleanCollection c);
064    
065    /** 
066     * Removes all my elements (optional operation). I will be
067     * {@link #isEmpty empty} after this method successfully returns.
068     * 
069     * @throws UnsupportedOperationException when this operation is not 
070     *         supported
071     */
072    void clear();
073
074    /** 
075     * Returns <code>true</code> iff I contain 
076     * the specified element. 
077     * 
078     * @param element the value whose presence within me is to be tested
079     * @return <code>true</code> iff I contain the specified element
080     */
081    boolean contains(boolean element);
082    
083    /** 
084     * Returns <code>true</code> iff I {@link #contains contain}
085     * all of the elements in the given collection.
086     * 
087     * @param c the collection of elements whose presence within me is to 
088     *        be tested
089     * @return <code>true</code> iff I contain the all the specified elements
090     */
091    boolean containsAll(BooleanCollection c);
092    
093    /** 
094     * Returns <code>true</code> iff I contain no elements. 
095     * @return <code>true</code> iff I contain no elements. 
096     */
097    boolean isEmpty();
098    
099    /** 
100     * Returns an {@link BooleanIterator iterator} over all my elements.
101     * This base interface places no constraints on the order in which the
102     * elements are returned by the returned iterator.
103     * @return an {@link BooleanIterator iterator} over all my elements.
104     */
105    BooleanIterator iterator();
106    
107    /** 
108     * Removes all of my elements that are contained in the specified
109     * collection (optional operation). The behavior of this method is
110     * unspecified if the given collection is modified while this method
111     * is executing.  Note that this includes the case in which the given
112     * collection is this collection, and it is not empty.
113     * 
114     * @param c the collection of elements to remove
115     * @return <code>true</code> iff I contained the at least one of the
116     *         specified elements, in other words, returns <code>true</code>
117     *         iff I changed as a result of this call
118     * 
119     * @throws UnsupportedOperationException when this operation is not 
120     *         supported
121     */
122    boolean removeAll(BooleanCollection c);
123     
124    /** 
125     * Removes a single occurrence of the specified element (optional
126     * operation).
127     * 
128     * @param element the element to remove, if present
129     * @return <code>true</code> iff I contained the specified element, 
130     *         in other words, iff I changed as a result of this call
131     * 
132     * @throws UnsupportedOperationException when this operation is not 
133     *         supported
134     */
135    boolean removeElement(boolean element);
136    
137    /** 
138     * Removes all of my elements that are <i>not</i> contained in the 
139     * specified collection (optional operation).  (In other words,
140     * retains <i>only</i> my elements that are contained in the specified
141     * collection.)  The behavior of this method is unspecified if the given
142     * collection is modified while this method is executing.
143     * 
144     * @param c the collection of elements to retain
145     * @return <code>true</code> iff I changed as a result of this call
146     * 
147     * @throws UnsupportedOperationException when this operation is not 
148     *         supported
149     */
150    boolean retainAll(BooleanCollection c);
151    
152    /** 
153     * Returns the number of elements I contain. 
154     * @return the number of elements I contain
155     */
156    int size();
157    
158    /** 
159     * Returns an array containing all of my elements.  The length of the
160     * returned array will be equal to my {@link #size size}.
161     * <p/>
162     * The returned array will be independent of me, so that callers may
163     * modify that returned array without modifying this collection.
164     * <p/>
165     * When I guarantee the order in which elements are returned by an
166     * {@link #iterator iterator}, the returned array will contain elements
167     * in the same order.
168     * 
169     * @return an array containing all my elements
170     */
171    boolean[] toArray();
172    
173    /** 
174     * Returns an array containing all of my elements, using the given array
175     * if it is large enough.  When the length of the given array is larger
176     * than the number of elements I contain, values outside of my range will
177     * be unchanged.
178     * <p/>
179     * The returned array will be independent of me, so that callers may modify
180     * that returned array without modifying this collection.
181     * <p/>
182     * When I guarantee the order in which elements are returned by an {@link
183     * #iterator iterator}, the returned array will contain elements in the
184     * same order.
185     * 
186     * @param a an array that may be used to contain the elements
187     * @return an array containing all my elements
188     */
189    boolean[] toArray(boolean[] a);
190}