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 * A collection of <code>boolean</code> values.
21 *
22 * @see org.apache.commons.collections.primitives.adapters.BooleanCollectionCollection
23 * @see org.apache.commons.collections.primitives.adapters.CollectionBooleanCollection
24 *
25 * @since Commons Primitives 1.1
26 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
27 */
28 public interface BooleanCollection
29 {
30 /**
31 * Ensures that I contain the specified element (optional operation).
32 * Returns <code>true</code> iff I changed as a result of this call.
33 * <p/>
34 * If a collection refuses to add the specified element for any reason
35 * other than that it already contains the element, it <i>must</i>
36 * throw an exception (rather than simply returning <tt>false</tt>).
37 * This preserves the invariant that a collection always contains the
38 * specified element after this call returns.
39 *
40 * @param element the value whose presence within me is to be ensured
41 * @return <code>true</code> iff I changed as a result of this call
42 *
43 * @throws UnsupportedOperationException when this operation is not
44 * supported
45 * @throws IllegalArgumentException may be thrown if some aspect of the
46 * specified element prevents it from being added to me
47 */
48 boolean add(boolean element);
49
50 /**
51 * {@link #add Adds} all of the elements in the specified collection to
52 * me (optional operation).
53 *
54 * @param c the collection of elements whose presence within me is to
55 * be ensured
56 * @return <code>true</code> iff I changed as a result of this call
57 *
58 * @throws UnsupportedOperationException when this operation is not
59 * supported
60 * @throws IllegalArgumentException may be thrown if some aspect of some
61 * specified element prevents it from being added to me
62 */
63 boolean addAll(BooleanCollection c);
64
65 /**
66 * Removes all my elements (optional operation). I will be
67 * {@link #isEmpty empty} after this method successfully returns.
68 *
69 * @throws UnsupportedOperationException when this operation is not
70 * supported
71 */
72 void clear();
73
74 /**
75 * Returns <code>true</code> iff I contain
76 * the specified element.
77 *
78 * @param element the value whose presence within me is to be tested
79 * @return <code>true</code> iff I contain the specified element
80 */
81 boolean contains(boolean element);
82
83 /**
84 * Returns <code>true</code> iff I {@link #contains contain}
85 * all of the elements in the given collection.
86 *
87 * @param c the collection of elements whose presence within me is to
88 * be tested
89 * @return <code>true</code> iff I contain the all the specified elements
90 */
91 boolean containsAll(BooleanCollection c);
92
93 /**
94 * Returns <code>true</code> iff I contain no elements.
95 * @return <code>true</code> iff I contain no elements.
96 */
97 boolean isEmpty();
98
99 /**
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 }