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 */
016package org.joda.primitives.collection;
017
018import org.joda.primitives.iterable.ByteIterable;
019import org.joda.primitives.iterator.ByteIterator;
020
021/**
022 * Defines a collection of primitive <code>byte</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 Byte}.
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 */
034public interface ByteCollection extends PrimitiveCollection<Byte>, ByteIterable {
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    ByteIterator iterator();
045    // This method is specified here, despite being in {@code ByteIterable},
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(byte 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(byte[] 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(ByteCollection 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(byte startInclusive, byte 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(byte[] 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(ByteCollection 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(byte startInclusive, byte 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    byte[] toByteArray();
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    byte[] toByteArray(byte[] 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(byte 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(byte[] 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(ByteCollection 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(byte startInclusive, byte 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(byte 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(byte 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(byte[] 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(ByteCollection 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(byte startInclusive, byte 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(byte[] 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(ByteCollection 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(byte startInclusive, byte endInclusive);
312
313}