View Javadoc

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.ByteIterable;
19  import org.joda.primitives.iterator.ByteIterator;
20  
21  /**
22   * Defines a collection of primitive <code>byte</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 Byte}.
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 ByteCollection extends PrimitiveCollection<Byte>, ByteIterable {
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      ByteIterator iterator();
45      // This method is specified here, despite being in {@code ByteIterable},
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(byte 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(byte[] 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(ByteCollection 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(byte startInclusive, byte 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(byte[] 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(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 }