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.IntIterable;
019 import org.joda.primitives.iterator.IntIterator;
020
021 /**
022 * Defines a collection of primitive <code>int</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 Integer}.
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 IntCollection extends PrimitiveCollection<Integer>, IntIterable {
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 IntIterator iterator();
045 // This method is specified here, despite being in {@code IntIterable},
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(int 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(int[] 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(IntCollection values);
073
074 /**
075 * Checks if this collection contain all the values in the specified range.
076 * <p>
077 * The range is defined to be inclusive of the start and end.
078 * If the start is greater than the end then the result is <code>true</code>
079 * as the range is equivalent to an empty collection.
080 *
081 * @param startInclusive the inclusive range start value
082 * @param endInclusive the inclusive range end value
083 * @return <code>true</code> if the collection contains the entire range
084 */
085 boolean containsAll(int startInclusive, int endInclusive);
086
087 /**
088 * Checks if this collection contains any of the values in the specified array.
089 * If the specified array is empty, <code>false</code> is returned.
090 *
091 * @param values the values to search for, null treated as empty array
092 * @return <code>true</code> if at least one of the values is found
093 */
094 boolean containsAny(int[] values);
095
096 /**
097 * Checks if this collection contains any of the values in the specified collection.
098 * If the specified collection is empty, <code>false</code> is returned.
099 *
100 * @param coll the values to search for, null treated as empty collection
101 * @return <code>true</code> if at least one of the values is found
102 */
103 boolean containsAny(IntCollection coll);
104
105 /**
106 * Checks if this collection contain any of the values in the specified range.
107 * <p>
108 * The range is defined to be inclusive of the start and end.
109 * If the start is greater than the end then the result is <code>false</code>
110 * as the range is equivalent to an empty collection.
111 *
112 * @param startInclusive the inclusive range start value
113 * @param endInclusive the inclusive range end value
114 * @return <code>true</code> if the collection contains at least one of the range
115 */
116 boolean containsAny(int startInclusive, int endInclusive);
117
118 /**
119 * Gets the elements of this collection as an array.
120 *
121 * @return a new array containing a copy of the elements of this collection
122 */
123 int[] toIntArray();
124
125 /**
126 * Copies the elements of this collection into an array at a specified position.
127 * Previous values in the array are overwritten.
128 * <p>
129 * If the array specified is null a new array is created.
130 * If the array specified is large enough, it will be modified.
131 * If the array is not large enough, a new array will be created containing the
132 * values from the specified array before the startIndex plus those from this collection.
133 *
134 * @param array the array to add the elements to, null creates new array
135 * @param startIndex the position in the array to start setting elements
136 * @return the array with the populated collection, not null
137 * @throws IndexOutOfBoundsException if the index is negative
138 */
139 int[] toIntArray(int[] array, int startIndex);
140
141 // Optional operations
142 //-----------------------------------------------------------------------
143 /**
144 * Adds a primitive value 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 value the value to add to this collection
150 * @return <code>true</code> if this collection was modified by this method call
151 * @throws IllegalArgumentException if value is rejected by this collection
152 * @throws UnsupportedOperationException if not supported by this collection
153 */
154 boolean add(int value);
155
156 /**
157 * Adds an array of primitive values to this collection (optional operation).
158 * <p>
159 * This method is optional, throwing an UnsupportedOperationException if the
160 * collection cannot be added to.
161 *
162 * @param values the values to add to this collection, null treated as empty array
163 * @return <code>true</code> if this collection was modified by this method call
164 * @throws IllegalArgumentException if a value is rejected by this collection
165 * @throws UnsupportedOperationException if not supported by this collection
166 */
167 boolean addAll(int[] values);
168
169 /**
170 * Adds a collection of primitive values to this collection (optional operation).
171 * <p>
172 * This method is optional, throwing an UnsupportedOperationException if the
173 * collection cannot be added to.
174 *
175 * @param values the values to add to this collection, null treated as empty collection
176 * @return <code>true</code> if this collection was modified by this method call
177 * @throws IllegalArgumentException if a value is rejected by this collection
178 * @throws UnsupportedOperationException if not supported by this collection
179 */
180 boolean addAll(IntCollection values);
181
182 /**
183 * Adds a range of primitive values to this collection (optional operation).
184 * <p>
185 * The range is defined to be inclusive of the start and end.
186 * If the start is greater than the end then the range is equivalent to an empty collection.
187 * <p>
188 * This method is optional, throwing an UnsupportedOperationException if the
189 * collection cannot be added to.
190 *
191 * @param startInclusive the inclusive range start value
192 * @param endInclusive the inclusive range end value
193 * @return <code>true</code> if this collection was modified by this method call
194 * @throws IllegalArgumentException if a value is rejected by this set
195 * @throws UnsupportedOperationException if not supported by this set
196 */
197 boolean addAll(int startInclusive, int endInclusive);
198
199 /**
200 * Removes the first occurrence of the specified primitive value from this collection
201 * (optional operation).
202 * <p>
203 * This method is optional, throwing an UnsupportedOperationException if the
204 * collection cannot be removed from.
205 *
206 * @param value the value to remove
207 * @return <code>true</code> if this collection was modified by this method call
208 * @throws UnsupportedOperationException if not supported by this collection
209 */
210 boolean removeFirst(int value);
211
212 /**
213 * Removes all occurrences of the specified primitive value from this collection
214 * (optional operation).
215 * <p>
216 * This method is optional, throwing an UnsupportedOperationException if the
217 * collection cannot be removed from.
218 *
219 * @param value the value to remove
220 * @return <code>true</code> if this collection was modified by this method call
221 * @throws UnsupportedOperationException if not supported by this collection
222 */
223 boolean removeAll(int value);
224
225 /**
226 * Removes all occurrences from this collection of each primitive in the specified array
227 * (optional operation).
228 * <p>
229 * This method is optional, throwing an UnsupportedOperationException if the
230 * collection cannot be removed from.
231 *
232 * @param values the values to remove from this collection, null treated as empty array
233 * @return <code>true</code> if this collection was modified by this method call
234 * @throws UnsupportedOperationException if not supported by this collection
235 */
236 boolean removeAll(int[] values);
237
238 /**
239 * Removes all occurrences from this collection of each primitive in the specified collection
240 * (optional operation).
241 * <p>
242 * This method is optional, throwing an UnsupportedOperationException if the
243 * collection cannot be removed from.
244 *
245 * @param values the values to remove from this collection, null treated as empty collection
246 * @return <code>true</code> if this collection was modified by this method call
247 * @throws UnsupportedOperationException if not supported by this collection
248 */
249 boolean removeAll(IntCollection values);
250
251 /**
252 * Removes all occurrences of a range of primitive values from this collection
253 * (optional operation).
254 * <p>
255 * The range is defined to be inclusive of the start and end.
256 * The elements removed are greater than or equal to the start and
257 * less than or equal to the end.
258 * Thus if the start is greater than the end then no elements are removed.
259 * <p>
260 * This method is optional, throwing an UnsupportedOperationException if the
261 * set cannot be changed.
262 *
263 * @param startInclusive the inclusive range start value
264 * @param endInclusive the inclusive range end value
265 * @return <code>true</code> if this collection was modified by this method call
266 * @throws UnsupportedOperationException if not supported by this collection
267 */
268 boolean removeAll(int startInclusive, int endInclusive);
269
270 /**
271 * Retains each element of this collection that is present in the specified array
272 * removing all other values (optional operation).
273 * <p>
274 * This method is optional, throwing an UnsupportedOperationException if the
275 * collection cannot be removed from.
276 *
277 * @param values the values to retain in this collection, null treated as empty array
278 * @return <code>true</code> if this collection was modified by this method call
279 * @throws UnsupportedOperationException if not supported by this collection
280 */
281 boolean retainAll(int[] values);
282
283 /**
284 * Retains each element of this collection that is present in the specified collection
285 * removing all other values (optional operation).
286 * <p>
287 * This method is optional, throwing an UnsupportedOperationException if the
288 * collection cannot be removed from.
289 *
290 * @param values the values to retain in this collection, null treated as empty collection
291 * @return <code>true</code> if this collection was modified by this method call
292 * @throws UnsupportedOperationException if not supported by this collection
293 */
294 boolean retainAll(IntCollection values);
295
296 /**
297 * Retains all occurrences of a range of primitive values within this collection
298 * removing all values outside the range (optional operation).
299 * <p>
300 * The range is defined to be inclusive of the start and end.
301 * If the start is greater than the end then the range is equivalent to an empty collection.
302 * <p>
303 * This method is optional, throwing an UnsupportedOperationException if the
304 * set cannot be changed.
305 *
306 * @param startInclusive the inclusive range start value
307 * @param endInclusive the inclusive range end value
308 * @return <code>true</code> if this collection was modified by this method call
309 * @throws UnsupportedOperationException if not supported by this collection
310 */
311 boolean retainAll(int startInclusive, int endInclusive);
312
313 }