001    /*
002     * Licensed to the Apache Software Foundation (ASF) under one or more
003     * contributor license agreements.  See the NOTICE file distributed with
004     * this work for additional information regarding copyright ownership.
005     * The ASF licenses this file to You under the Apache License, Version 2.0
006     * (the "License"); you may not use this file except in compliance with
007     * the License.  You may obtain a copy of the License at
008     *
009     *     http://www.apache.org/licenses/LICENSE-2.0
010     *
011     * Unless required by applicable law or agreed to in writing, software
012     * distributed under the License is distributed on an "AS IS" BASIS,
013     * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014     * See the License for the specific language governing permissions and
015     * limitations under the License.
016     */
017    package org.apache.commons.collections.primitives;
018    
019    /**
020     * A collection of <code>short</code> values.
021     *
022     * @see org.apache.commons.collections.primitives.adapters.ShortCollectionCollection
023     * @see org.apache.commons.collections.primitives.adapters.CollectionShortCollection
024     *
025     * @since Commons Primitives 1.0
026     * @version $Revision: 480460 $ $Date: 2006-11-29 09:14:21 +0100 (Wed, 29 Nov 2006) $
027     * 
028     * @author Rodney Waldhoff 
029     */
030    public interface ShortCollection {
031        /** 
032         * Ensures that I contain the specified element 
033         * (optional operation).  Returns <code>true</code>
034         * iff I changed as a result of this call.
035         * <p/>
036         * If a collection refuses to add the specified
037         * element for any reason other than that it already contains
038         * the element, it <i>must</i> throw an exception (rather than
039         * simply returning <tt>false</tt>).  This preserves the invariant
040         * that a collection always contains the specified element after 
041         * this call returns. 
042         * 
043         * @param element the value whose presence within me is to be ensured
044         * @return <code>true</code> iff I changed as a result of this call
045         * 
046         * @throws UnsupportedOperationException when this operation is not 
047         *         supported
048         * @throws IllegalArgumentException may be thrown if some aspect of the 
049         *         specified element prevents it from being added to me
050         */
051        boolean add(short element);
052    
053        /** 
054         * {@link #add Adds} all of the elements in the 
055         * specified collection to me (optional operation). 
056         * 
057         * @param c the collection of elements whose presence within me is to 
058         *        be ensured
059         * @return <code>true</code> iff I changed as a result of this call
060         * 
061         * @throws UnsupportedOperationException when this operation is not 
062         *         supported
063         * @throws IllegalArgumentException may be thrown if some aspect of some 
064         *         specified element prevents it from being added to me
065         */ 
066        boolean addAll(ShortCollection c);
067        
068        /** 
069         * Removes all my elements (optional operation). 
070         * I will be {@link #isEmpty empty} after this
071         * method successfully returns.
072         * 
073         * @throws UnsupportedOperationException when this operation is not 
074         *         supported
075         */
076        void clear();
077    
078        /** 
079         * Returns <code>true</code> iff I contain 
080         * the specified element. 
081         * 
082         * @param element the value whose presence within me is to be tested
083         * @return <code>true</code> iff I contain the specified element
084         */
085        boolean contains(short element);
086        
087        /** 
088         * Returns <code>true</code> iff I {@link #contains contain}
089         * all of the elements in the given collection.
090         * 
091         * @param c the collection of elements whose presence within me is to 
092         *        be tested
093         * @return <code>true</code> iff I contain the all the specified elements
094         */
095        boolean containsAll(ShortCollection c);
096        
097        /** 
098         * Returns <code>true</code> iff I contain no elements. 
099         * @return <code>true</code> iff I contain no elements. 
100         */
101        boolean isEmpty();
102        
103        /** 
104         * Returns an {@link ShortIterator iterator} over all my elements.
105         * This base interface places no constraints on the order 
106         * in which the elements are returned by the returned iterator.
107         * @return an {@link ShortIterator iterator} over all my elements.
108         */
109        ShortIterator iterator();
110        
111        /** 
112         * Removes all of my elements that are contained in the 
113         * specified collection (optional operation). 
114         * The behavior of this method is unspecified if 
115         * the given collection is modified while this method
116         * is executing.  Note that this includes the case
117         * in which the given collection is this collection, 
118         * and it is not empty.
119         * 
120         * @param c the collection of elements to remove
121         * @return <code>true</code> iff I contained the at least one of the
122         *         specified elements, in other words, returns <code>true</code>
123         *         iff I changed as a result of this call
124         * 
125         * @throws UnsupportedOperationException when this operation is not 
126         *         supported
127         */
128        boolean removeAll(ShortCollection c);
129         
130        /** 
131         * Removes a single occurrence of the specified element 
132         * (optional operation). 
133         * 
134         * @param element the element to remove, if present
135         * @return <code>true</code> iff I contained the specified element, 
136         *         in other words, iff I changed as a result of this call
137         * 
138         * @throws UnsupportedOperationException when this operation is not 
139         *         supported
140         */
141        boolean removeElement(short element);
142        
143        /** 
144         * Removes all of my elements that are <i>not</i> contained in the 
145         * specified collection (optional operation). 
146         * (In other words, retains <i>only</i> my elements that are 
147         * contained in the specified collection.)
148         * The behavior of this method is unspecified if 
149         * the given collection is modified while this method
150         * is executing.
151         * 
152         * @param c the collection of elements to retain
153         * @return <code>true</code> iff I changed as a result 
154         *         of this call
155         * 
156         * @throws UnsupportedOperationException when this operation is not 
157         *         supported
158         */
159        boolean retainAll(ShortCollection c);
160        
161        /** 
162         * Returns the number of elements I contain. 
163         * @return the number of elements I contain
164         */
165        int size();
166        
167        /** 
168         * Returns an array containing all of my elements.
169         * The length of the returned array will be equal
170         * to my {@link #size size}.
171         * <p/>
172         * The returned array will be independent of me, 
173         * so that callers may modify that 
174         * returned array without modifying this collection.
175         * <p/>
176         * When I guarantee the order in which 
177         * elements are returned by an {@link #iterator iterator},
178         * the returned array will contain elements in the
179         * same order.
180         * 
181         * @return an array containing all my elements
182         */
183        short[] toArray();
184        
185        /** 
186         * Returns an array containing all of my elements, 
187         * using the given array if it is large 
188         * enough.  When the length of the given array is 
189         * larger than the number of elements I contain, 
190         * values outside of my range will be unchanged.
191         * <p/>
192         * The returned array will be independent of me, 
193         * so that callers may modify that 
194         * returned array without modifying this collection.
195         * <p/>
196         * When I guarantee the order in which 
197         * elements are returned by an {@link #iterator iterator},
198         * the returned array will contain elements in the
199         * same order.
200         * 
201         * @param a an array that may be used to contain the elements
202         * @return an array containing all my elements
203         */
204        short[] toArray(short[] a);
205    }