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>char</code> values.
21 *
22 * @see org.apache.commons.collections.primitives.adapters.CharCollectionCollection
23 * @see org.apache.commons.collections.primitives.adapters.CollectionCharCollection
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 CharCollection {
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(char 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(CharCollection 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(char 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(CharCollection 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 CharIterator 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 CharIterator iterator} over all my elements.
108 */
109 CharIterator 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(CharCollection 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(char 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(CharCollection 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 char[] 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 char[] toArray(char[] a);
205 }