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.LongIterable;
19 import org.joda.primitives.iterator.LongIterator;
20
21 /**
22 * Defines a collection of primitive <code>long</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 Long}.
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 LongCollection extends PrimitiveCollection<Long>, LongIterable {
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 LongIterator iterator();
45 // This method is specified here, despite being in {@code LongIterable},
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(long 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(long[] 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(LongCollection values);
73
74 /**
75 * Checks if this collection contain all the values in the specified range.
76 * <p>
77 * The range is defined to be inclusive of the start and end.
78 * If the start is greater than the end then the result is <code>true</code>
79 * as the range is equivalent to an empty collection.
80 *
81 * @param startInclusive the inclusive range start value
82 * @param endInclusive the inclusive range end value
83 * @return <code>true</code> if the collection contains the entire range
84 */
85 boolean containsAll(long startInclusive, long endInclusive);
86
87 /**
88 * Checks if this collection contains any of the values in the specified array.
89 * If the specified array is empty, <code>false</code> is returned.
90 *
91 * @param values the values to search for, null treated as empty array
92 * @return <code>true</code> if at least one of the values is found
93 */
94 boolean containsAny(long[] values);
95
96 /**
97 * Checks if this collection contains any of the values in the specified collection.
98 * If the specified collection is empty, <code>false</code> is returned.
99 *
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(LongCollection 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(long startInclusive, long 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 long[] toLongArray();
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 long[] toLongArray(long[] 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(long 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(long[] 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(LongCollection 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(long startInclusive, long 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(long 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(long 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(long[] 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(LongCollection 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(long startInclusive, long 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(long[] 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(LongCollection 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(long startInclusive, long endInclusive);
312
313 }