1 /*
2 * $Header: /home/cvs/jakarta-commons/primitives/src/java/org/apache/commons/collections/primitives/ShortCollection.java,v 1.3 2003/10/16 20:49:36 scolebourne Exp $
3 * ====================================================================
4 * The Apache Software License, Version 1.1
5 *
6 * Copyright (c) 2002-2003 The Apache Software Foundation. All rights
7 * reserved.
8 *
9 * Redistribution and use in source and binary forms, with or without
10 * modification, are permitted provided that the following conditions
11 * are met:
12 *
13 * 1. Redistributions of source code must retain the above copyright
14 * notice, this list of conditions and the following disclaimer.
15 *
16 * 2. Redistributions in binary form must reproduce the above copyright
17 * notice, this list of conditions and the following disclaimer in
18 * the documentation and/or other materials provided with the
19 * distribution.
20 *
21 * 3. The end-user documentation included with the redistribution, if
22 * any, must include the following acknowledgement:
23 * "This product includes software developed by the
24 * Apache Software Foundation (http://www.apache.org/)."
25 * Alternately, this acknowledgement may appear in the software itself,
26 * if and wherever such third-party acknowledgements normally appear.
27 *
28 * 4. The names "The Jakarta Project", "Commons", and "Apache Software
29 * Foundation" must not be used to endorse or promote products derived
30 * from this software without prior written permission. For written
31 * permission, please contact apache@apache.org.
32 *
33 * 5. Products derived from this software may not be called "Apache"
34 * nor may "Apache" appear in their names without prior written
35 * permission of the Apache Software Foundation.
36 *
37 * THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
38 * WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES
39 * OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
40 * DISCLAIMED. IN NO EVENT SHALL THE APACHE SOFTWARE FOUNDATION OR
41 * ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
42 * SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
43 * LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
44 * USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
45 * ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
46 * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
47 * OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
48 * SUCH DAMAGE.
49 * ====================================================================
50 *
51 * This software consists of voluntary contributions made by many
52 * individuals on behalf of the Apache Software Foundation. For more
53 * information on the Apache Software Foundation, please see
54 * <http://www.apache.org/>.
55 *
56 */
57
58 package org.apache.commons.collections.primitives;
59
60 /**
61 * A collection of <code>short</code> values.
62 *
63 * @see org.apache.commons.collections.primitives.adapters.ShortCollectionCollection
64 * @see org.apache.commons.collections.primitives.adapters.CollectionShortCollection
65 *
66 * @since Commons Primitives 1.0
67 * @version $Revision: 1.3 $ $Date: 2003/10/16 20:49:36 $
68 *
69 * @author Rodney Waldhoff
70 */
71 public interface ShortCollection {
72 /**
73 * Ensures that I contain the specified element
74 * (optional operation). Returns <code>true</code>
75 * iff I changed as a result of this call.
76 * <p/>
77 * If a collection refuses to add the specified
78 * element for any reason other than that it already contains
79 * the element, it <i>must</i> throw an exception (rather than
80 * simply returning <tt>false</tt>). This preserves the invariant
81 * that a collection always contains the specified element after
82 * this call returns.
83 *
84 * @param element the value whose presence within me is to be ensured
85 * @return <code>true</code> iff I changed as a result of this call
86 *
87 * @throws UnsupportedOperationException when this operation is not
88 * supported
89 * @throws IllegalArgumentException may be thrown if some aspect of the
90 * specified element prevents it from being added to me
91 */
92 boolean add(short element);
93
94 /**
95 * {@link #add Adds} all of the elements in the
96 * specified collection to me (optional operation).
97 *
98 * @param c the collection of elements whose presence within me is to
99 * be ensured
100 * @return <code>true</code> iff I changed as a result of this call
101 *
102 * @throws UnsupportedOperationException when this operation is not
103 * supported
104 * @throws IllegalArgumentException may be thrown if some aspect of some
105 * specified element prevents it from being added to me
106 */
107 boolean addAll(ShortCollection c);
108
109 /**
110 * Removes all my elements (optional operation).
111 * I will be {@link #isEmpty empty} after this
112 * method successfully returns.
113 *
114 * @throws UnsupportedOperationException when this operation is not
115 * supported
116 */
117 void clear();
118
119 /**
120 * Returns <code>true</code> iff I contain
121 * the specified element.
122 *
123 * @param element the value whose presence within me is to be tested
124 * @return <code>true</code> iff I contain the specified element
125 */
126 boolean contains(short element);
127
128 /**
129 * Returns <code>true</code> iff I {@link #contains contain}
130 * all of the elements in the given collection.
131 *
132 * @param c the collection of elements whose presence within me is to
133 * be tested
134 * @return <code>true</code> iff I contain the all the specified elements
135 */
136 boolean containsAll(ShortCollection c);
137
138 /**
139 * Returns <code>true</code> iff I contain no elements.
140 * @return <code>true</code> iff I contain no elements.
141 */
142 boolean isEmpty();
143
144 /**
145 * Returns an {@link ShortIterator iterator} over all my elements.
146 * This base interface places no constraints on the order
147 * in which the elements are returned by the returned iterator.
148 * @return an {@link ShortIterator iterator} over all my elements.
149 */
150 ShortIterator iterator();
151
152 /**
153 * Removes all of my elements that are contained in the
154 * specified collection (optional operation).
155 * The behavior of this method is unspecified if
156 * the given collection is modified while this method
157 * is executing. Note that this includes the case
158 * in which the given collection is this collection,
159 * and it is not empty.
160 *
161 * @param c the collection of elements to remove
162 * @return <code>true</code> iff I contained the at least one of the
163 * specified elements, in other words, returns <code>true</code>
164 * iff I changed as a result of this call
165 *
166 * @throws UnsupportedOperationException when this operation is not
167 * supported
168 */
169 boolean removeAll(ShortCollection c);
170
171 /**
172 * Removes a single occurrence of the specified element
173 * (optional operation).
174 *
175 * @param element the element to remove, if present
176 * @return <code>true</code> iff I contained the specified element,
177 * in other words, iff I changed as a result of this call
178 *
179 * @throws UnsupportedOperationException when this operation is not
180 * supported
181 */
182 boolean removeElement(short element);
183
184 /**
185 * Removes all of my elements that are <i>not</i> contained in the
186 * specified collection (optional operation).
187 * (In other words, retains <i>only</i> my elements that are
188 * contained in the specified collection.)
189 * The behavior of this method is unspecified if
190 * the given collection is modified while this method
191 * is executing.
192 *
193 * @param c the collection of elements to retain
194 * @return <code>true</code> iff I changed as a result
195 * of this call
196 *
197 * @throws UnsupportedOperationException when this operation is not
198 * supported
199 */
200 boolean retainAll(ShortCollection c);
201
202 /**
203 * Returns the number of elements I contain.
204 * @return the number of elements I contain
205 */
206 int size();
207
208 /**
209 * Returns an array containing all of my elements.
210 * The length of the returned array will be equal
211 * to my {@link #size size}.
212 * <p/>
213 * The returned array will be independent of me,
214 * so that callers may modify that
215 * returned array without modifying this collection.
216 * <p/>
217 * When I guarantee the order in which
218 * elements are returned by an {@link #iterator iterator},
219 * the returned array will contain elements in the
220 * same order.
221 *
222 * @return an array containing all my elements
223 */
224 short[] toArray();
225
226 /**
227 * Returns an array containing all of my elements,
228 * using the given array if it is large
229 * enough. When the length of the given array is
230 * larger than the number of elements I contain,
231 * values outside of my range will be unchanged.
232 * <p/>
233 * The returned array will be independent of me,
234 * so that callers may modify that
235 * returned array without modifying this collection.
236 * <p/>
237 * When I guarantee the order in which
238 * elements are returned by an {@link #iterator iterator},
239 * the returned array will contain elements in the
240 * same order.
241 *
242 * @param a an array that may be used to contain the elements
243 * @return an array containing all my elements
244 */
245 short[] toArray(short[] a);
246 }
Save This Page