1 /*
2 * Copyright 2001-2010 Stephen Colebourne
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 * http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16 package org.joda.primitives.collection;
17
18 import org.joda.primitives.iterable.BooleanIterable;
19 import org.joda.primitives.iterator.BooleanIterator;
20
21 /**
22 * Defines a collection of primitive <code>boolean</code> values.
23 * <p>
24 * This interface extends {@link java.util.Collection Collection} allowing
25 * seamless integration with other APIs.
26 * All Collection methods can be used, using the primitive wrapper class {@link Boolean}.
27 * However, it will be <em>much</em> more efficient to use the methods defined here.
28 *
29 * @author Stephen Colebourne
30 * @author Jason Tiscione
31 * @version CODE GENERATED
32 * @since 1.0
33 */
34 public interface BooleanCollection extends PrimitiveCollection<Boolean>, BooleanIterable {
35 // This file is CODE GENERATED. Do not change manually.
36
37 // Mandatory operations
38 //-----------------------------------------------------------------------
39 /**
40 * Gets an iterator over this collection capable of accessing the primitive values.
41 *
42 * @return an iterator over this collection, not null
43 */
44 BooleanIterator iterator();
45 // This method is specified here, despite being in {@code BooleanIterable},
46 // due to compiler bug 6487370.
47
48 /**
49 * Checks whether this collection contains a specified primitive value.
50 *
51 * @param value the value to search for
52 * @return <code>true</code> if the value is found
53 */
54 boolean contains(boolean value);
55
56 /**
57 * Checks if this collection contains all of the values in the specified array.
58 * If the specified array is empty, <code>true</code> is returned.
59 *
60 * @param values the values to search for, null treated as empty array
61 * @return <code>true</code> if all of the values are found
62 */
63 boolean containsAll(boolean[] values);
64
65 /**
66 * Checks if this collection contains all of the values in the specified collection.
67 * If the specified collection is empty, <code>true</code> is returned.
68 *
69 * @param values the values to search for, null treated as empty collection
70 * @return <code>true</code> if all of the values are found
71 */
72 boolean containsAll(BooleanCollection values);
73
74 /**
75 * Checks if this collection contains any of the values in the specified array.
76 * If the specified array is empty, <code>false</code> is returned.
77 *
78 * @param values the values to search for, null treated as empty array
79 * @return <code>true</code> if at least one of the values is found
80 */
81 boolean containsAny(boolean[] values);
82
83 /**
84 * Checks if this collection contains any of the values in the specified collection.
85 * If the specified collection is empty, <code>false</code> is returned.
86 *
87 * @param coll the values to search for, null treated as empty collection
88 * @return <code>true</code> if at least one of the values is found
89 */
90 boolean containsAny(BooleanCollection coll);
91
92 /**
93 * Gets the elements of this collection as an array.
94 *
95 * @return a new array containing a copy of the elements of this collection
96 */
97 boolean[] toBooleanArray();
98
99 /**
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 }