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 */
017package org.apache.commons.collections.primitives;
018
019/**
020 * A collection of <code>long</code> values.
021 *
022 * @see org.apache.commons.collections.primitives.adapters.LongCollectionCollection
023 * @see org.apache.commons.collections.primitives.adapters.CollectionLongCollection
024 *
025 * @since Commons Primitives 1.0
026 * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
027 * 
028 * @author Rodney Waldhoff 
029 */
030public interface LongCollection {
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(long 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(LongCollection 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(long 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(LongCollection 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 LongIterator 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 LongIterator iterator} over all my elements.
108     */
109    LongIterator 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(LongCollection 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(long 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(LongCollection 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    long[] 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    long[] toArray(long[] a);
205}