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