001 /*
002 * Copyright 2001-2010 Stephen Colebourne
003 *
004 * Licensed under the Apache License, Version 2.0 (the "License");
005 * you may not use this file except in compliance with the License.
006 * You may obtain a copy of the License at
007 *
008 * http://www.apache.org/licenses/LICENSE-2.0
009 *
010 * Unless required by applicable law or agreed to in writing, software
011 * distributed under the License is distributed on an "AS IS" BASIS,
012 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
013 * See the License for the specific language governing permissions and
014 * limitations under the License.
015 */
016 package org.joda.primitives.collection;
017
018 import org.joda.primitives.iterable.BooleanIterable;
019 import org.joda.primitives.iterator.BooleanIterator;
020
021 /**
022 * Defines a collection of primitive <code>boolean</code> values.
023 * <p>
024 * This interface extends {@link java.util.Collection Collection} allowing
025 * seamless integration with other APIs.
026 * All Collection methods can be used, using the primitive wrapper class {@link Boolean}.
027 * However, it will be <em>much</em> more efficient to use the methods defined here.
028 *
029 * @author Stephen Colebourne
030 * @author Jason Tiscione
031 * @version CODE GENERATED
032 * @since 1.0
033 */
034 public interface BooleanCollection extends PrimitiveCollection<Boolean>, BooleanIterable {
035 // This file is CODE GENERATED. Do not change manually.
036
037 // Mandatory operations
038 //-----------------------------------------------------------------------
039 /**
040 * Gets an iterator over this collection capable of accessing the primitive values.
041 *
042 * @return an iterator over this collection, not null
043 */
044 BooleanIterator iterator();
045 // This method is specified here, despite being in {@code BooleanIterable},
046 // due to compiler bug 6487370.
047
048 /**
049 * Checks whether this collection contains a specified primitive value.
050 *
051 * @param value the value to search for
052 * @return <code>true</code> if the value is found
053 */
054 boolean contains(boolean value);
055
056 /**
057 * Checks if this collection contains all of the values in the specified array.
058 * If the specified array is empty, <code>true</code> is returned.
059 *
060 * @param values the values to search for, null treated as empty array
061 * @return <code>true</code> if all of the values are found
062 */
063 boolean containsAll(boolean[] values);
064
065 /**
066 * Checks if this collection contains all of the values in the specified collection.
067 * If the specified collection is empty, <code>true</code> is returned.
068 *
069 * @param values the values to search for, null treated as empty collection
070 * @return <code>true</code> if all of the values are found
071 */
072 boolean containsAll(BooleanCollection values);
073
074 /**
075 * Checks if this collection contains any of the values in the specified array.
076 * If the specified array is empty, <code>false</code> is returned.
077 *
078 * @param values the values to search for, null treated as empty array
079 * @return <code>true</code> if at least one of the values is found
080 */
081 boolean containsAny(boolean[] values);
082
083 /**
084 * Checks if this collection contains any of the values in the specified collection.
085 * If the specified collection is empty, <code>false</code> is returned.
086 *
087 * @param coll the values to search for, null treated as empty collection
088 * @return <code>true</code> if at least one of the values is found
089 */
090 boolean containsAny(BooleanCollection coll);
091
092 /**
093 * Gets the elements of this collection as an array.
094 *
095 * @return a new array containing a copy of the elements of this collection
096 */
097 boolean[] toBooleanArray();
098
099 /**
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 }