BooleanCollection


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>boolean</code> values.
21   *
22   * @see org.apache.commons.collections.primitives.adapters.BooleanCollectionCollection
23   * @see org.apache.commons.collections.primitives.adapters.CollectionBooleanCollection
24   *
25   * @since Commons Primitives 1.1
26   * @version $Revision: 480460 $ $Date: 2006-11-29 00:14:21 -0800 (Wed, 29 Nov 2006) $
27   */
28  public interface BooleanCollection
29  {
30      /** 
31       * Ensures that I contain the specified element (optional operation).
32       * Returns <code>true</code> iff I changed as a result of this call.
33       * <p/>
34       * If a collection refuses to add the specified element for any reason
35       * other than that it already contains the element, it <i>must</i>
36       * throw an exception (rather than simply returning <tt>false</tt>).
37       * This preserves the invariant that a collection always contains the
38       * specified element after this call returns.
39       * 
40       * @param element the value whose presence within me is to be ensured
41       * @return <code>true</code> iff I changed as a result of this call
42       * 
43       * @throws UnsupportedOperationException when this operation is not 
44       *         supported
45       * @throws IllegalArgumentException may be thrown if some aspect of the 
46       *         specified element prevents it from being added to me
47       */
48      boolean add(boolean element);
49  
50      /** 
51       * {@link #add Adds} all of the elements in the specified collection to
52       * me (optional operation).
53       * 
54       * @param c the collection of elements whose presence within me is to 
55       *        be ensured
56       * @return <code>true</code> iff I changed as a result of this call
57       * 
58       * @throws UnsupportedOperationException when this operation is not 
59       *         supported
60       * @throws IllegalArgumentException may be thrown if some aspect of some 
61       *         specified element prevents it from being added to me
62       */ 
63      boolean addAll(BooleanCollection c);
64      
65      /** 
66       * Removes all my elements (optional operation). I will be
67       * {@link #isEmpty empty} after this method successfully returns.
68       * 
69       * @throws UnsupportedOperationException when this operation is not 
70       *         supported
71       */
72      void clear();
73  
74      /** 
75       * Returns <code>true</code> iff I contain 
76       * the specified element. 
77       * 
78       * @param element the value whose presence within me is to be tested
79       * @return <code>true</code> iff I contain the specified element
80       */
81      boolean contains(boolean element);
82      
83      /** 
84       * Returns <code>true</code> iff I {@link #contains contain}
85       * all of the elements in the given collection.
86       * 
87       * @param c the collection of elements whose presence within me is to 
88       *        be tested
89       * @return <code>true</code> iff I contain the all the specified elements
90       */
91      boolean containsAll(BooleanCollection c);
92      
93      /** 
94       * Returns <code>true</code> iff I contain no elements. 
95       * @return <code>true</code> iff I contain no elements. 
96       */
97      boolean isEmpty();
98      
99      /** 
100      * Returns an {@link BooleanIterator iterator} over all my elements.
101      * This base interface places no constraints on the order in which the
102      * elements are returned by the returned iterator.
103      * @return an {@link BooleanIterator iterator} over all my elements.
104      */
105     BooleanIterator iterator();
106     
107     /** 
108      * Removes all of my elements that are contained in the specified
109      * collection (optional operation). The behavior of this method is
110      * unspecified if the given collection is modified while this method
111      * is executing.  Note that this includes the case in which the given
112      * collection is this collection, and it is not empty.
113      * 
114      * @param c the collection of elements to remove
115      * @return <code>true</code> iff I contained the at least one of the
116      *         specified elements, in other words, returns <code>true</code>
117      *         iff I changed as a result of this call
118      * 
119      * @throws UnsupportedOperationException when this operation is not 
120      *         supported
121      */
122     boolean removeAll(BooleanCollection c);
123      
124     /** 
125      * Removes a single occurrence of the specified element (optional
126      * operation).
127      * 
128      * @param element the element to remove, if present
129      * @return <code>true</code> iff I contained the specified element, 
130      *         in other words, iff I changed as a result of this call
131      * 
132      * @throws UnsupportedOperationException when this operation is not 
133      *         supported
134      */
135     boolean removeElement(boolean element);
136     
137     /** 
138      * Removes all of my elements that are <i>not</i> contained in the 
139      * specified collection (optional operation).  (In other words,
140      * retains <i>only</i> my elements that are contained in the specified
141      * collection.)  The behavior of this method is unspecified if the given
142      * collection is modified while this method is executing.
143      * 
144      * @param c the collection of elements to retain
145      * @return <code>true</code> iff I changed as a result of this call
146      * 
147      * @throws UnsupportedOperationException when this operation is not 
148      *         supported
149      */
150     boolean retainAll(BooleanCollection c);
151     
152     /** 
153      * Returns the number of elements I contain. 
154      * @return the number of elements I contain
155      */
156     int size();
157     
158     /** 
159      * Returns an array containing all of my elements.  The length of the
160      * returned array will be equal to my {@link #size size}.
161      * <p/>
162      * The returned array will be independent of me, so that callers may
163      * modify that returned array without modifying this collection.
164      * <p/>
165      * When I guarantee the order in which elements are returned by an
166      * {@link #iterator iterator}, the returned array will contain elements
167      * in the same order.
168      * 
169      * @return an array containing all my elements
170      */
171     boolean[] toArray();
172     
173     /** 
174      * Returns an array containing all of my elements, using the given array
175      * if it is large enough.  When the length of the given array is larger
176      * than the number of elements I contain, values outside of my range will
177      * be unchanged.
178      * <p/>
179      * The returned array will be independent of me, so that callers may modify
180      * that returned array without modifying this collection.
181      * <p/>
182      * When I guarantee the order in which elements are returned by an {@link
183      * #iterator iterator}, the returned array will contain elements in the
184      * same order.
185      * 
186      * @param a an array that may be used to contain the elements
187      * @return an array containing all my elements
188      */
189     boolean[] toArray(boolean[] a);
190 }
191
A to Z: JavaDoc & Examples Daily Java News & Articles Open Source Projects Open Source Codes Free Computer Books Remove Frame
Popular Tags