Coverage Report

Coverage Report - org.apache.commons.collections.primitives.LongCollection

Classes in this File

 /*
  * Licensed to the Apache Software Foundation (ASF) under one or more
  * contributor license agreements.  See the NOTICE file distributed with
  * this work for additional information regarding copyright ownership.
  * The ASF licenses this file to You under the Apache License, Version 2.0
  * (the "License"); you may not use this file except in compliance with
  * the License.  You may obtain a copy of the License at
  *
  *     http://www.apache.org/licenses/LICENSE-2.0
  *
  * Unless required by applicable law or agreed to in writing, software
  * distributed under the License is distributed on an "AS IS" BASIS,
  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
 package org.apache.commons.collections.primitives;
 
 /**
  * A collection of <code>long</code> values.
  *
  * @see org.apache.commons.collections.primitives.adapters.LongCollectionCollection
  * @see org.apache.commons.collections.primitives.adapters.CollectionLongCollection
  *
  * @since Commons Primitives 1.0
  * @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
  * 
  * @author Rodney Waldhoff 
  */
 public interface LongCollection {
     /** 
      * Ensures that I contain the specified element 
      * (optional operation).  Returns <code>true</code>
      * iff I changed as a result of this call.
      * <p/>
      * If a collection refuses to add the specified
      * element for any reason other than that it already contains
      * the element, it <i>must</i> throw an exception (rather than
      * simply returning <tt>false</tt>).  This preserves the invariant
      * that a collection always contains the specified element after 
      * this call returns. 
      * 
      * @param element the value whose presence within me is to be ensured
      * @return <code>true</code> iff I changed as a result of this call
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      * @throws IllegalArgumentException may be thrown if some aspect of the 
      *         specified element prevents it from being added to me
      */
     boolean add(long element);
 
     /** 
      * {@link #add Adds} all of the elements in the 
      * specified collection to me (optional operation). 
      * 
      * @param c the collection of elements whose presence within me is to 
      *        be ensured
      * @return <code>true</code> iff I changed as a result of this call
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      * @throws IllegalArgumentException may be thrown if some aspect of some 
      *         specified element prevents it from being added to me
      */ 
     boolean addAll(LongCollection c);
     
     /** 
      * Removes all my elements (optional operation). 
      * I will be {@link #isEmpty empty} after this
      * method successfully returns.
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      */
     void clear();
 
     /** 
      * Returns <code>true</code> iff I contain 
      * the specified element. 
      * 
      * @param element the value whose presence within me is to be tested
      * @return <code>true</code> iff I contain the specified element
      */
     boolean contains(long element);
     
     /** 
      * Returns <code>true</code> iff I {@link #contains contain}
      * all of the elements in the given collection.
      * 
      * @param c the collection of elements whose presence within me is to 
      *        be tested
      * @return <code>true</code> iff I contain the all the specified elements
      */
     boolean containsAll(LongCollection c);
     
     /** 
      * Returns <code>true</code> iff I contain no elements. 
      * @return <code>true</code> iff I contain no elements. 
      */
     boolean isEmpty();
     
     /** 
      * Returns an {@link LongIterator iterator} over all my elements.
      * This base interface places no constraints on the order 
      * in which the elements are returned by the returned iterator.
      * @return an {@link LongIterator iterator} over all my elements.
      */
     LongIterator iterator();
     
     /** 
      * Removes all of my elements that are contained in the 
      * specified collection (optional operation). 
      * The behavior of this method is unspecified if 
      * the given collection is modified while this method
      * is executing.  Note that this includes the case
      * in which the given collection is this collection, 
      * and it is not empty.
      * 
      * @param c the collection of elements to remove
      * @return <code>true</code> iff I contained the at least one of the
      *         specified elements, in other words, returns <code>true</code>
      *         iff I changed as a result of this call
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      */
     boolean removeAll(LongCollection c);
      
     /** 
      * Removes a single occurrence of the specified element 
      * (optional operation). 
      * 
      * @param element the element to remove, if present
      * @return <code>true</code> iff I contained the specified element, 
      *         in other words, iff I changed as a result of this call
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      */
     boolean removeElement(long element);
     
     /** 
      * Removes all of my elements that are <i>not</i> contained in the 
      * specified collection (optional operation). 
      * (In other words, retains <i>only</i> my elements that are 
      * contained in the specified collection.)
      * The behavior of this method is unspecified if 
      * the given collection is modified while this method
      * is executing.
      * 
      * @param c the collection of elements to retain
      * @return <code>true</code> iff I changed as a result 
      *         of this call
      * 
      * @throws UnsupportedOperationException when this operation is not 
      *         supported
      */
     boolean retainAll(LongCollection c);
     
     /** 
      * Returns the number of elements I contain. 
      * @return the number of elements I contain
      */
     int size();
     
     /** 
      * Returns an array containing all of my elements.
      * The length of the returned array will be equal
      * to my {@link #size size}.
      * <p/>
      * The returned array will be independent of me, 
      * so that callers may modify that 
      * returned array without modifying this collection.
      * <p/>
      * When I guarantee the order in which 
      * elements are returned by an {@link #iterator iterator},
      * the returned array will contain elements in the
      * same order.
      * 
      * @return an array containing all my elements
      */
     long[] toArray();
     
     /** 
      * Returns an array containing all of my elements, 
      * using the given array if it is large 
      * enough.  When the length of the given array is 
      * larger than the number of elements I contain, 
      * values outside of my range will be unchanged.
      * <p/>
      * The returned array will be independent of me, 
      * so that callers may modify that 
      * returned array without modifying this collection.
      * <p/>
      * When I guarantee the order in which 
      * elements are returned by an {@link #iterator iterator},
      * the returned array will contain elements in the
      * same order.
      * 
      * @param a an array that may be used to contain the elements
      * @return an array containing all my elements
      */
     long[] toArray(long[] a);
 }

1		/*
2		* Licensed to the Apache Software Foundation (ASF) under one or more
3		* contributor license agreements. See the NOTICE file distributed with
4		* this work for additional information regarding copyright ownership.
5		* The ASF licenses this file to You under the Apache License, Version 2.0
6		* (the "License"); you may not use this file except in compliance with
7		* the License. You may obtain a copy of the License at
8		*
9		* http://www.apache.org/licenses/LICENSE-2.0
10		*
11		* Unless required by applicable law or agreed to in writing, software
12		* distributed under the License is distributed on an "AS IS" BASIS,
13		* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
14		* See the License for the specific language governing permissions and
15		* limitations under the License.
16		*/
17		package org.apache.commons.collections.primitives;
18
19		/**
20		* A collection of <code>long</code> values.
21		*
22		* @see org.apache.commons.collections.primitives.adapters.LongCollectionCollection
23		* @see org.apache.commons.collections.primitives.adapters.CollectionLongCollection
24		*
25		* @since Commons Primitives 1.0
26		* @version $Revision: 480460 $ $Date: 2006-11-29 03:14:21 -0500 (Wed, 29 Nov 2006) $
27		*
28		* @author Rodney Waldhoff
29		*/
30		public interface LongCollection {
31		/**
32		* Ensures that I contain the specified element
33		* (optional operation). Returns <code>true</code>
34		* iff I changed as a result of this call.
35		* <p/>
36		* If a collection refuses to add the specified
37		* element for any reason other than that it already contains
38		* the element, it <i>must</i> throw an exception (rather than
39		* simply returning <tt>false</tt>). This preserves the invariant
40		* that a collection always contains the specified element after
41		* this call returns.
42		*
43		* @param element the value whose presence within me is to be ensured
44		* @return <code>true</code> iff I changed as a result of this call
45		*
46		* @throws UnsupportedOperationException when this operation is not
47		* supported
48		* @throws IllegalArgumentException may be thrown if some aspect of the
49		* specified element prevents it from being added to me
50		*/
51		boolean add(long element);
52
53		/**
54		* {@link #add Adds} all of the elements in the
55		* specified collection to me (optional operation).
56		*
57		* @param c the collection of elements whose presence within me is to
58		* be ensured
59		* @return <code>true</code> iff I changed as a result of this call
60		*
61		* @throws UnsupportedOperationException when this operation is not
62		* supported
63		* @throws IllegalArgumentException may be thrown if some aspect of some
64		* specified element prevents it from being added to me
65		*/
66		boolean addAll(LongCollection c);
67
68		/**
69		* Removes all my elements (optional operation).
70		* I will be {@link #isEmpty empty} after this
71		* method successfully returns.
72		*
73		* @throws UnsupportedOperationException when this operation is not
74		* supported
75		*/
76		void clear();
77
78		/**
79		* Returns <code>true</code> iff I contain
80		* the specified element.
81		*
82		* @param element the value whose presence within me is to be tested
83		* @return <code>true</code> iff I contain the specified element
84		*/
85		boolean contains(long element);
86
87		/**
88		* Returns <code>true</code> iff I {@link #contains contain}
89		* all of the elements in the given collection.
90		*
91		* @param c the collection of elements whose presence within me is to
92		* be tested
93		* @return <code>true</code> iff I contain the all the specified elements
94		*/
95		boolean containsAll(LongCollection c);
96
97		/**
98		* Returns <code>true</code> iff I contain no elements.
99		* @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		}