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 }