1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16 package net.sf.collections15;
17
18 import java.util.Collection;
19 import java.util.Iterator;
20 import java.util.Set;
21
22 /***
23 * Defines a collection that counts the number of times an object appears in the
24 * collection.
25 * <p/>
26 * Suppose you have a Bag that contains <code>{a, a, b, c}</code>. Calling
27 * {@link #getCount(Object)} on <code>a</code> would return 2, while calling
28 * {@link #uniqueSet()} would return <code>{a, b, c}</code>.
29 *
30 * @author Chuck Burdick
31 * @author Stephen Colebourne
32 * @version $Revision: 1.2 $ $Date: 2004/10/17 01:02:42 $
33 * @since Commons Collections15 1.0
34 */
35 public interface Bag <E> extends Collection<E>
36 {
37
38 /***
39 * Returns the number of occurrences (cardinality) of the given object
40 * currently in the bag. If the object does not exist in the bag, return 0.
41 *
42 * @param object the object to search for
43 *
44 * @return the number of occurrences of the object, zero if not found
45 */
46 int getCount(Object object);
47
48 /***
49 * Adds one copy the specified object to the Bag.
50 * <p/>
51 * If the object is already in the {@link #uniqueSet()} then increment its
52 * count as reported by {@link #getCount(Object)}. Otherwise add it to the
53 * {@link #uniqueSet()} and report its count as 1.
54 * <p/>
55 * Since this method always increases the size of the bag, it always returns
56 * <code>true</code>, in accordance with the {@link java.util.Collection#add(Object)}
57 * contract.
58 *
59 * @param object the object to add
60 *
61 * @return <code>true</code>, to indicate that the collection changed as a
62 * result of this call.
63 */
64 boolean add(E object);
65
66 /***
67 * Adds <code>nCopies</code> copies of the specified object to the Bag.
68 * <p/>
69 * If the object is already in the {@link #uniqueSet()} then increment its
70 * count as reported by {@link #getCount(Object)}. Otherwise add it to the
71 * {@link #uniqueSet()} and report its count as <code>nCopies</code>.
72 *
73 * @param object the object to add
74 * @param nCopies the number of copies to add. Cannot be negative.
75 *
76 * @return <code>true</code>, if the collection changed as a result of this
77 * call (which can only occur if <code>nCopies</code> > 0).
78 *
79 * @throws IllegalArgumentException if <code>nCopies</code> is negative.
80 */
81 boolean add(E object, int nCopies);
82
83 /***
84 * Removes a single occurrence of the given object from the bag.
85 * <p/>
86 * If there was only one copy of the object in the set, this will also
87 * remove the object from the {@link #uniqueSet()}.
88 *
89 * @return <code>true</code> if this call changed the collection.
90 */
91 boolean remove(Object object);
92
93 /***
94 * Removes all occurrences of the given object from the bag.
95 * <p/>
96 * This will also remove the object from the {@link #uniqueSet()}.
97 *
98 * @param object the object to remove
99 *
100 * @return <code>true</code> if this call changed the collection.
101 */
102 boolean removeAllCopies(Object object);
103
104 /***
105 * Removes <code>nCopies</code> copies of the specified object from the
106 * Bag.
107 * <p/>
108 * If the number of copies to remove is greater than the actual number of
109 * copies in the Bag, no error is thrown.
110 *
111 * @param object the object to remove
112 * @param nCopies the number of copies to remove. Cannot be negative.
113 *
114 * @return <code>true</code> if this call changed the collection
115 *
116 * @throws IllegalArgumentException if <code>nCopies</code> is negative.
117 */
118 boolean remove(Object object, int nCopies);
119
120 /***
121 * Returns a {@link java.util.Set} of unique elements in the Bag.
122 * <p/>
123 * Uniqueness constraints are the same as those in {@link java.util.Set}.
124 *
125 * @return the Set of unique Bag elements
126 */
127 Set<E> uniqueSet();
128
129 /***
130 * Returns the total number of items in the bag across all types.
131 *
132 * @return the total size of the Bag
133 */
134 int size();
135
136 /***
137 * Returns <code>true</code> if the bag contains all elements in the given
138 * collection. More specifically, this method returns <code>true</code> only
139 * if <code>contains(e)</code> returns <code>true</code> for each element,
140 * <code>e</code>, in the specified collection, <code>coll</code>.
141 *
142 * @param coll the collection to check against
143 *
144 * @return <code>true</code> if the Bag contains all elements in the
145 * collection
146 */
147 boolean containsAll(Collection<?> coll);
148
149 /***
150 * Returns <code>true</code> if the bag contains all elements in the given
151 * collection, respecting cardinality. More specifically, this method
152 * returns <code>true</code> only if the following is true. <ul> <li>For the
153 * element, <code>e</code>, of which there are <code>n</code> copies in
154 * collection <code>coll</code>, the value returned by calling
155 * <code>getCount(e)</code> must be <code>>= n</code>.</li> <li>The above
156 * must hold true for all elements, <code>e</code>, in
157 * <code>coll</code>.</li> </ul>
158 *
159 * @param coll the collection to check against
160 *
161 * @return <code>true</code> if the contents of the collection is a subset
162 * of the contents of this bag.
163 */
164 boolean containsAllCardinally(Collection<?> coll);
165
166 /***
167 * Remove all occurrences of every element in the given collection.
168 *
169 * @param coll the elements to remove
170 *
171 * @return <code>true</code> if this call changed this collection.
172 */
173 boolean removeAll(Collection<?> coll);
174
175 /***
176 * Remove all elements represented in the given collection, respecting
177 * cardinality. That is, if the given collection <code>coll</code> contains
178 * <code>n</code> copies of a given object, the bag will have <code>n</code>
179 * fewer copies (or no copies, if the bag had fewer than <code>n</code>
180 * copies to begin with).
181 *
182 * @param coll the collection to remove
183 *
184 * @return <code>true</code> if this call changed this collection
185 */
186 boolean removeAllCardinally(Collection<?> coll);
187
188 /***
189 * Remove all elements of the bag that are not in the given collection.
190 *
191 * @param coll the collection to retain
192 *
193 * @return <code>true</code> if this call changed the collection
194 */
195 boolean retainAll(Collection<?> coll);
196
197 /***
198 * Remove any members of the bag that are not in the given collection,
199 * respecting cardinality. That is, if the given collection
200 * <code>coll</code> contains <code>n</code> copies of a given object and
201 * the bag has <code>m > n</code> copies, then delete <code>m - n</code>
202 * copies from the bag. In addition, if <code>e</code> is an object in the
203 * bag but <code>!coll.contains(e)</code>, then remove <code>e</code> and
204 * any of its copies.
205 *
206 * @param coll the collection to retain
207 *
208 * @return <code>true</code> if this call changed this collection
209 */
210 boolean retainAllCardinally(Collection<?> coll);
211
212 /***
213 * Returns an {@link Iterator} over the entire set of members, including
214 * copies due to cardinality. This iterator is fail-fast and will not
215 * tolerate concurrent modifications.
216 *
217 * @return iterator over all elements in the Bag
218 */
219 Iterator<E> iterator();
220
221
222
223 /***
224 // * Compares this Bag to another.
225 // * This Bag equals another Bag if it contains the same number of occurrences of
226 // * the same elements.
227 // * This equals definition is compatible with the Set interface.
228 // *
229 // * @param obj the Bag to compare to
230 // * @return true if equal
231 // */
232
233
234 /***
235 // * Gets a hash code for the Bag compatible with the definition of equals.
236 // * The hash code is defined as the sum total of a hash code for each element.
237 // * The per element hash code is defined as
238 // * <code>(e==null ? 0 : e.hashCode()) ^ noOccurances)</code>.
239 // * This hash code definition is compatible with the Set interface.
240 // *
241 // * @return the hash code of the Bag
242 // */
243
244
245 }