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>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 09:14:21 +0100 (Wed, 29 Nov 2006) $
027 *
028 * @author Rodney Waldhoff
029 */
030 public 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 }