KezvhLib/lib/org.apache.commons.collections/apidocs/org/apache/commons/collections/Bag.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd">
   2 <!--NewPage-->
   3 <HTML>
   4 <HEAD>
   5 <!-- Generated by javadoc (build 1.5.0_07) on Fri Apr 11 15:39:16 BST 2008 -->
   6 <META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   7 <TITLE>
   8 Bag (Commons Collections 3.2.1 API)
   9 </TITLE>
  10
  11 <META NAME="keywords" CONTENT="org.apache.commons.collections.Bag interface">
  12
  13 <LINK REL ="stylesheet" TYPE="text/css" HREF="../../../../stylesheet.css" TITLE="Style">
  14
  15 <SCRIPT type="text/javascript">
  16 function windowTitle()
  17 {
  18     parent.document.title="Bag (Commons Collections 3.2.1 API)";
  19 }
  20 </SCRIPT>
  21 <NOSCRIPT>
  22 </NOSCRIPT>
  23
  24 </HEAD>
  25
  26 <BODY BGCOLOR="white" onload="windowTitle();">
  27
  28
  29 <!-- ========= START OF TOP NAVBAR ======= -->
  30 <A NAME="navbar_top"><!-- --></A>
  31 <A HREF="#skip-navbar_top" title="Skip navigation links"></A>
  32 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
  33 <TR>
  34 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
  35 <A NAME="navbar_top_firstrow"><!-- --></A>
  36 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
  37   <TR ALIGN="center" VALIGN="top">
  38   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
  39   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
  40   <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
  41   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="class-use/Bag.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
  42   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
  43   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
  44   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
  45   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
  46   </TR>
  47 </TABLE>
  48 </TD>
  49 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
  50 </EM>
  51 </TD>
  52 </TR>
  53
  54 <TR>
  55 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  56 &nbsp;<A HREF="../../../../org/apache/commons/collections/ArrayStack.html" title="class in org.apache.commons.collections"><B>PREV CLASS</B></A>&nbsp;
  57 &nbsp;<A HREF="../../../../org/apache/commons/collections/BagUtils.html" title="class in org.apache.commons.collections"><B>NEXT CLASS</B></A></FONT></TD>
  58 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
  59   <A HREF="../../../../index.html?org/apache/commons/collections/Bag.html" target="_top"><B>FRAMES</B></A>  &nbsp;
  60 &nbsp;<A HREF="Bag.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
  61 &nbsp;<SCRIPT type="text/javascript">
  62   <!--
  63   if(window==top) {
  64     document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
  65   }
  66   //-->
  67 </SCRIPT>
  68 <NOSCRIPT>
  69   <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
  70 </NOSCRIPT>
  71
  72
  73 </FONT></TD>
  74 </TR>
  75 <TR>
  76 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  77   SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
  78 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
  79 DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
  80 </TR>
  81 </TABLE>
  82 <A NAME="skip-navbar_top"></A>
  83 <!-- ========= END OF TOP NAVBAR ========= -->
  84
  85 <HR>
  86 <!-- ======== START OF CLASS DATA ======== -->
  87 <H2>
  88 <FONT SIZE="-1">
  89 org.apache.commons.collections</FONT>
  90 <BR>
  91 Interface Bag</H2>
  92 <DL>
  93 <DT><B>All Superinterfaces:</B> <DD>java.util.Collection, java.lang.Iterable</DD>
  94 </DL>
  95 <DL>
  96 <DT><B>All Known Subinterfaces:</B> <DD><A HREF="../../../../org/apache/commons/collections/SortedBag.html" title="interface in org.apache.commons.collections">SortedBag</A></DD>
  97 </DL>
  98 <DL>
  99 <DT><B>All Known Implementing Classes:</B> <DD><A HREF="../../../../org/apache/commons/collections/bag/AbstractBagDecorator.html" title="class in org.apache.commons.collections.bag">AbstractBagDecorator</A>, <A HREF="../../../../org/apache/commons/collections/bag/AbstractMapBag.html" title="class in org.apache.commons.collections.bag">AbstractMapBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/AbstractSortedBagDecorator.html" title="class in org.apache.commons.collections.bag">AbstractSortedBagDecorator</A>, <A HREF="../../../../org/apache/commons/collections/DefaultMapBag.html" title="class in org.apache.commons.collections">DefaultMapBag</A>, <A HREF="../../../../org/apache/commons/collections/HashBag.html" title="class in org.apache.commons.collections">HashBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/HashBag.html" title="class in org.apache.commons.collections.bag">HashBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/PredicatedBag.html" title="class in org.apache.commons.collections.bag">PredicatedBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/PredicatedSortedBag.html" title="class in org.apache.commons.collections.bag">PredicatedSortedBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/SynchronizedBag.html" title="class in org.apache.commons.collections.bag">SynchronizedBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/SynchronizedSortedBag.html" title="class in org.apache.commons.collections.bag">SynchronizedSortedBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/TransformedBag.html" title="class in org.apache.commons.collections.bag">TransformedBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/TransformedSortedBag.html" title="class in org.apache.commons.collections.bag">TransformedSortedBag</A>, <A HREF="../../../../org/apache/commons/collections/TreeBag.html" title="class in org.apache.commons.collections">TreeBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/TreeBag.html" title="class in org.apache.commons.collections.bag">TreeBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/UnmodifiableBag.html" title="class in org.apache.commons.collections.bag">UnmodifiableBag</A>, <A HREF="../../../../org/apache/commons/collections/bag/UnmodifiableSortedBag.html" title="class in org.apache.commons.collections.bag">UnmodifiableSortedBag</A></DD>
 100 </DL>
 101 <HR>
 102 <DL>
 103 <DT><PRE>public interface <B>Bag</B><DT>extends java.util.Collection</DL>
 104 </PRE>
 105
 106 <P>
 107 Defines a collection that counts the number of times an object appears in
 108  the collection.
 109  <p>
 110  Suppose you have a Bag that contains <code>{a, a, b, c}</code>.
 111  Calling <A HREF="../../../../org/apache/commons/collections/Bag.html#getCount(java.lang.Object)"><CODE>getCount(Object)</CODE></A> on <code>a</code> would return 2, while
 112  calling <A HREF="../../../../org/apache/commons/collections/Bag.html#uniqueSet()"><CODE>uniqueSet()</CODE></A> would return <code>{a, b, c}</code>.
 113  <p>
 114  <i>NOTE: This interface violates the <CODE>Collection</CODE> contract.</i>
 115  The behavior specified in many of these methods is <i>not</i> the same
 116  as the behavior specified by <code>Collection</code>.
 117  The noncompliant methods are clearly marked with "(Violation)".
 118  Exercise caution when using a bag as a <code>Collection</code>.
 119  <p>
 120  This violation resulted from the original specification of this interface.
 121  In an ideal world, the interface would be changed to fix the problems, however
 122  it has been decided to maintain backwards compatibility instead.
 123 <P>
 124
 125 <P>
 126 <DL>
 127 <DT><B>Since:</B></DT>
 128   <DD>Commons Collections 2.0</DD>
 129 <DT><B>Version:</B></DT>
 130   <DD>$Revision: 646777 $ $Date: 2008-04-10 13:33:15 +0100 (Thu, 10 Apr 2008) $</DD>
 131 <DT><B>Author:</B></DT>
 132   <DD>Chuck Burdick, Stephen Colebourne</DD>
 133 </DL>
 134 <HR>
 135
 136 <P>
 137
 138 <!-- ========== METHOD SUMMARY =========== -->
 139
 140 <A NAME="method_summary"><!-- --></A>
 141 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
 142 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 143 <TH ALIGN="left" COLSPAN="2"><FONT SIZE="+2">
 144 <B>Method Summary</B></FONT></TH>
 145 </TR>
 146 <TR BGCOLOR="white" CLASS="TableRowColor">
 147 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 148 <CODE>&nbsp;boolean</CODE></FONT></TD>
 149 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#add(java.lang.Object)">add</A></B>(java.lang.Object&nbsp;object)</CODE>
 150
 151 <BR>
 152 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i>(Violation)</i>
 153  Adds one copy the specified object to the Bag.</TD>
 154 </TR>
 155 <TR BGCOLOR="white" CLASS="TableRowColor">
 156 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 157 <CODE>&nbsp;boolean</CODE></FONT></TD>
 158 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#add(java.lang.Object, int)">add</A></B>(java.lang.Object&nbsp;object,
 159     int&nbsp;nCopies)</CODE>
 160
 161 <BR>
 162 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Adds <code>nCopies</code> copies of the specified object to the Bag.</TD>
 163 </TR>
 164 <TR BGCOLOR="white" CLASS="TableRowColor">
 165 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 166 <CODE>&nbsp;boolean</CODE></FONT></TD>
 167 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#containsAll(java.util.Collection)">containsAll</A></B>(java.util.Collection&nbsp;coll)</CODE>
 168
 169 <BR>
 170 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i>(Violation)</i>
 171  Returns <code>true</code> if the bag contains all elements in
 172  the given collection, respecting cardinality.</TD>
 173 </TR>
 174 <TR BGCOLOR="white" CLASS="TableRowColor">
 175 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 176 <CODE>&nbsp;int</CODE></FONT></TD>
 177 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#getCount(java.lang.Object)">getCount</A></B>(java.lang.Object&nbsp;object)</CODE>
 178
 179 <BR>
 180 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Returns the number of occurrences (cardinality) of the given
 181  object currently in the bag.</TD>
 182 </TR>
 183 <TR BGCOLOR="white" CLASS="TableRowColor">
 184 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 185 <CODE>&nbsp;java.util.Iterator</CODE></FONT></TD>
 186 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#iterator()">iterator</A></B>()</CODE>
 187
 188 <BR>
 189 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Returns an <CODE>Iterator</CODE> over the entire set of members,
 190  including copies due to cardinality.</TD>
 191 </TR>
 192 <TR BGCOLOR="white" CLASS="TableRowColor">
 193 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 194 <CODE>&nbsp;boolean</CODE></FONT></TD>
 195 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#remove(java.lang.Object)">remove</A></B>(java.lang.Object&nbsp;object)</CODE>
 196
 197 <BR>
 198 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i>(Violation)</i>
 199  Removes all occurrences of the given object from the bag.</TD>
 200 </TR>
 201 <TR BGCOLOR="white" CLASS="TableRowColor">
 202 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 203 <CODE>&nbsp;boolean</CODE></FONT></TD>
 204 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#remove(java.lang.Object, int)">remove</A></B>(java.lang.Object&nbsp;object,
 205        int&nbsp;nCopies)</CODE>
 206
 207 <BR>
 208 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Removes <code>nCopies</code> copies of the specified object from the Bag.</TD>
 209 </TR>
 210 <TR BGCOLOR="white" CLASS="TableRowColor">
 211 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 212 <CODE>&nbsp;boolean</CODE></FONT></TD>
 213 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#removeAll(java.util.Collection)">removeAll</A></B>(java.util.Collection&nbsp;coll)</CODE>
 214
 215 <BR>
 216 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i>(Violation)</i>
 217  Remove all elements represented in the given collection,
 218  respecting cardinality.</TD>
 219 </TR>
 220 <TR BGCOLOR="white" CLASS="TableRowColor">
 221 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 222 <CODE>&nbsp;boolean</CODE></FONT></TD>
 223 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#retainAll(java.util.Collection)">retainAll</A></B>(java.util.Collection&nbsp;coll)</CODE>
 224
 225 <BR>
 226 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;<i>(Violation)</i>
 227  Remove any members of the bag that are not in the given
 228  collection, respecting cardinality.</TD>
 229 </TR>
 230 <TR BGCOLOR="white" CLASS="TableRowColor">
 231 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 232 <CODE>&nbsp;int</CODE></FONT></TD>
 233 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#size()">size</A></B>()</CODE>
 234
 235 <BR>
 236 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Returns the total number of items in the bag across all types.</TD>
 237 </TR>
 238 <TR BGCOLOR="white" CLASS="TableRowColor">
 239 <TD ALIGN="right" VALIGN="top" WIDTH="1%"><FONT SIZE="-1">
 240 <CODE>&nbsp;java.util.Set</CODE></FONT></TD>
 241 <TD><CODE><B><A HREF="../../../../org/apache/commons/collections/Bag.html#uniqueSet()">uniqueSet</A></B>()</CODE>
 242
 243 <BR>
 244 &nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;&nbsp;Returns a <CODE>Set</CODE> of unique elements in the Bag.</TD>
 245 </TR>
 246 </TABLE>
 247 &nbsp;<A NAME="methods_inherited_from_class_java.util.Collection"><!-- --></A>
 248 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
 249 <TR BGCOLOR="#EEEEFF" CLASS="TableSubHeadingColor">
 250 <TH ALIGN="left"><B>Methods inherited from interface java.util.Collection</B></TH>
 251 </TR>
 252 <TR BGCOLOR="white" CLASS="TableRowColor">
 253 <TD><CODE>addAll, clear, contains, equals, hashCode, isEmpty, toArray, toArray</CODE></TD>
 254 </TR>
 255 </TABLE>
 256 &nbsp;
 257 <P>
 258
 259 <!-- ============ METHOD DETAIL ========== -->
 260
 261 <A NAME="method_detail"><!-- --></A>
 262 <TABLE BORDER="1" WIDTH="100%" CELLPADDING="3" CELLSPACING="0" SUMMARY="">
 263 <TR BGCOLOR="#CCCCFF" CLASS="TableHeadingColor">
 264 <TH ALIGN="left" COLSPAN="1"><FONT SIZE="+2">
 265 <B>Method Detail</B></FONT></TH>
 266 </TR>
 267 </TABLE>
 268
 269 <A NAME="getCount(java.lang.Object)"><!-- --></A><H3>
 270 getCount</H3>
 271 <PRE>
 272 int <B>getCount</B>(java.lang.Object&nbsp;object)</PRE>
 273 <DL>
 274 <DD>Returns the number of occurrences (cardinality) of the given
 275  object currently in the bag. If the object does not exist in the
 276  bag, return 0.
 277 <P>
 278 <DD><DL>
 279 </DL>
 280 </DD>
 281 <DD><DL>
 282 <DT><B>Parameters:</B><DD><CODE>object</CODE> - the object to search for
 283 <DT><B>Returns:</B><DD>the number of occurrences of the object, zero if not found</DL>
 284 </DD>
 285 </DL>
 286 <HR>
 287
 288 <A NAME="add(java.lang.Object)"><!-- --></A><H3>
 289 add</H3>
 290 <PRE>
 291 boolean <B>add</B>(java.lang.Object&nbsp;object)</PRE>
 292 <DL>
 293 <DD><i>(Violation)</i>
 294  Adds one copy the specified object to the Bag.
 295  <p>
 296  If the object is already in the <A HREF="../../../../org/apache/commons/collections/Bag.html#uniqueSet()"><CODE>uniqueSet()</CODE></A> then increment its
 297  count as reported by <A HREF="../../../../org/apache/commons/collections/Bag.html#getCount(java.lang.Object)"><CODE>getCount(Object)</CODE></A>. Otherwise add it to the
 298  <A HREF="../../../../org/apache/commons/collections/Bag.html#uniqueSet()"><CODE>uniqueSet()</CODE></A> and report its count as 1.
 299  <p>
 300  Since this method always increases the size of the bag,
 301  according to the <CODE>Collection.add(Object)</CODE> contract, it
 302  should always return <code>true</code>.  Since it sometimes returns
 303  <code>false</code>, this method violates the contract.
 304 <P>
 305 <DD><DL>
 306 <DT><B>Specified by:</B><DD><CODE>add</CODE> in interface <CODE>java.util.Collection</CODE></DL>
 307 </DD>
 308 <DD><DL>
 309 <DT><B>Parameters:</B><DD><CODE>object</CODE> - the object to add
 310 <DT><B>Returns:</B><DD><code>true</code> if the object was not already in the <code>uniqueSet</code></DL>
 311 </DD>
 312 </DL>
 313 <HR>
 314
 315 <A NAME="add(java.lang.Object, int)"><!-- --></A><H3>
 316 add</H3>
 317 <PRE>
 318 boolean <B>add</B>(java.lang.Object&nbsp;object,
 319             int&nbsp;nCopies)</PRE>
 320 <DL>
 321 <DD>Adds <code>nCopies</code> copies of the specified object to the Bag.
 322  <p>
 323  If the object is already in the <A HREF="../../../../org/apache/commons/collections/Bag.html#uniqueSet()"><CODE>uniqueSet()</CODE></A> then increment its
 324  count as reported by <A HREF="../../../../org/apache/commons/collections/Bag.html#getCount(java.lang.Object)"><CODE>getCount(Object)</CODE></A>. Otherwise add it to the
 325  <A HREF="../../../../org/apache/commons/collections/Bag.html#uniqueSet()"><CODE>uniqueSet()</CODE></A> and report its count as <code>nCopies</code>.
 326 <P>
 327 <DD><DL>
 328 </DL>
 329 </DD>
 330 <DD><DL>
 331 <DT><B>Parameters:</B><DD><CODE>object</CODE> - the object to add<DD><CODE>nCopies</CODE> - the number of copies to add
 332 <DT><B>Returns:</B><DD><code>true</code> if the object was not already in the <code>uniqueSet</code></DL>
 333 </DD>
 334 </DL>
 335 <HR>
 336
 337 <A NAME="remove(java.lang.Object)"><!-- --></A><H3>
 338 remove</H3>
 339 <PRE>
 340 boolean <B>remove</B>(java.lang.Object&nbsp;object)</PRE>
 341 <DL>
 342 <DD><i>(Violation)</i>
 343  Removes all occurrences of the given object from the bag.
 344  <p>
 345  This will also remove the object from the <A HREF="../../../../org/apache/commons/collections/Bag.html#uniqueSet()"><CODE>uniqueSet()</CODE></A>.
 346  <p>
 347  According to the <CODE>Collection.remove(Object)</CODE> method,
 348  this method should only remove the <i>first</i> occurrence of the
 349  given object, not <i>all</i> occurrences.
 350 <P>
 351 <DD><DL>
 352 <DT><B>Specified by:</B><DD><CODE>remove</CODE> in interface <CODE>java.util.Collection</CODE></DL>
 353 </DD>
 354 <DD><DL>
 355
 356 <DT><B>Returns:</B><DD><code>true</code> if this call changed the collection</DL>
 357 </DD>
 358 </DL>
 359 <HR>
 360
 361 <A NAME="remove(java.lang.Object, int)"><!-- --></A><H3>
 362 remove</H3>
 363 <PRE>
 364 boolean <B>remove</B>(java.lang.Object&nbsp;object,
 365                int&nbsp;nCopies)</PRE>
 366 <DL>
 367 <DD>Removes <code>nCopies</code> copies of the specified object from the Bag.
 368  <p>
 369  If the number of copies to remove is greater than the actual number of
 370  copies in the Bag, no error is thrown.
 371 <P>
 372 <DD><DL>
 373 </DL>
 374 </DD>
 375 <DD><DL>
 376 <DT><B>Parameters:</B><DD><CODE>object</CODE> - the object to remove<DD><CODE>nCopies</CODE> - the number of copies to remove
 377 <DT><B>Returns:</B><DD><code>true</code> if this call changed the collection</DL>
 378 </DD>
 379 </DL>
 380 <HR>
 381
 382 <A NAME="uniqueSet()"><!-- --></A><H3>
 383 uniqueSet</H3>
 384 <PRE>
 385 java.util.Set <B>uniqueSet</B>()</PRE>
 386 <DL>
 387 <DD>Returns a <CODE>Set</CODE> of unique elements in the Bag.
 388  <p>
 389  Uniqueness constraints are the same as those in <CODE>Set</CODE>.
 390 <P>
 391 <DD><DL>
 392 </DL>
 393 </DD>
 394 <DD><DL>
 395
 396 <DT><B>Returns:</B><DD>the Set of unique Bag elements</DL>
 397 </DD>
 398 </DL>
 399 <HR>
 400
 401 <A NAME="size()"><!-- --></A><H3>
 402 size</H3>
 403 <PRE>
 404 int <B>size</B>()</PRE>
 405 <DL>
 406 <DD>Returns the total number of items in the bag across all types.
 407 <P>
 408 <DD><DL>
 409 <DT><B>Specified by:</B><DD><CODE>size</CODE> in interface <CODE>java.util.Collection</CODE></DL>
 410 </DD>
 411 <DD><DL>
 412
 413 <DT><B>Returns:</B><DD>the total size of the Bag</DL>
 414 </DD>
 415 </DL>
 416 <HR>
 417
 418 <A NAME="containsAll(java.util.Collection)"><!-- --></A><H3>
 419 containsAll</H3>
 420 <PRE>
 421 boolean <B>containsAll</B>(java.util.Collection&nbsp;coll)</PRE>
 422 <DL>
 423 <DD><i>(Violation)</i>
 424  Returns <code>true</code> if the bag contains all elements in
 425  the given collection, respecting cardinality.  That is, if the
 426  given collection <code>coll</code> contains <code>n</code> copies
 427  of a given object, calling <A HREF="../../../../org/apache/commons/collections/Bag.html#getCount(java.lang.Object)"><CODE>getCount(Object)</CODE></A> on that object must
 428  be <code>&gt;= n</code> for all <code>n</code> in <code>coll</code>.
 429  <p>
 430  The <CODE>Collection.containsAll(Collection)</CODE> method specifies
 431  that cardinality should <i>not</i> be respected; this method should
 432  return true if the bag contains at least one of every object contained
 433  in the given collection.
 434 <P>
 435 <DD><DL>
 436 <DT><B>Specified by:</B><DD><CODE>containsAll</CODE> in interface <CODE>java.util.Collection</CODE></DL>
 437 </DD>
 438 <DD><DL>
 439 <DT><B>Parameters:</B><DD><CODE>coll</CODE> - the collection to check against
 440 <DT><B>Returns:</B><DD><code>true</code> if the Bag contains all the collection</DL>
 441 </DD>
 442 </DL>
 443 <HR>
 444
 445 <A NAME="removeAll(java.util.Collection)"><!-- --></A><H3>
 446 removeAll</H3>
 447 <PRE>
 448 boolean <B>removeAll</B>(java.util.Collection&nbsp;coll)</PRE>
 449 <DL>
 450 <DD><i>(Violation)</i>
 451  Remove all elements represented in the given collection,
 452  respecting cardinality.  That is, if the given collection
 453  <code>coll</code> contains <code>n</code> copies of a given object,
 454  the bag will have <code>n</code> fewer copies, assuming the bag
 455  had at least <code>n</code> copies to begin with.
 456
 457  <P>The <CODE>Collection.removeAll(Collection)</CODE> method specifies
 458  that cardinality should <i>not</i> be respected; this method should
 459  remove <i>all</i> occurrences of every object contained in the
 460  given collection.
 461 <P>
 462 <DD><DL>
 463 <DT><B>Specified by:</B><DD><CODE>removeAll</CODE> in interface <CODE>java.util.Collection</CODE></DL>
 464 </DD>
 465 <DD><DL>
 466 <DT><B>Parameters:</B><DD><CODE>coll</CODE> - the collection to remove
 467 <DT><B>Returns:</B><DD><code>true</code> if this call changed the collection</DL>
 468 </DD>
 469 </DL>
 470 <HR>
 471
 472 <A NAME="retainAll(java.util.Collection)"><!-- --></A><H3>
 473 retainAll</H3>
 474 <PRE>
 475 boolean <B>retainAll</B>(java.util.Collection&nbsp;coll)</PRE>
 476 <DL>
 477 <DD><i>(Violation)</i>
 478  Remove any members of the bag that are not in the given
 479  collection, respecting cardinality.  That is, if the given
 480  collection <code>coll</code> contains <code>n</code> copies of a
 481  given object and the bag has <code>m &gt; n</code> copies, then
 482  delete <code>m - n</code> copies from the bag.  In addition, if
 483  <code>e</code> is an object in the bag but
 484  <code>!coll.contains(e)</code>, then remove <code>e</code> and any
 485  of its copies.
 486
 487  <P>The <CODE>Collection.retainAll(Collection)</CODE> method specifies
 488  that cardinality should <i>not</i> be respected; this method should
 489  keep <i>all</i> occurrences of every object contained in the
 490  given collection.
 491 <P>
 492 <DD><DL>
 493 <DT><B>Specified by:</B><DD><CODE>retainAll</CODE> in interface <CODE>java.util.Collection</CODE></DL>
 494 </DD>
 495 <DD><DL>
 496 <DT><B>Parameters:</B><DD><CODE>coll</CODE> - the collection to retain
 497 <DT><B>Returns:</B><DD><code>true</code> if this call changed the collection</DL>
 498 </DD>
 499 </DL>
 500 <HR>
 501
 502 <A NAME="iterator()"><!-- --></A><H3>
 503 iterator</H3>
 504 <PRE>
 505 java.util.Iterator <B>iterator</B>()</PRE>
 506 <DL>
 507 <DD>Returns an <CODE>Iterator</CODE> over the entire set of members,
 508  including copies due to cardinality. This iterator is fail-fast
 509  and will not tolerate concurrent modifications.
 510 <P>
 511 <DD><DL>
 512 <DT><B>Specified by:</B><DD><CODE>iterator</CODE> in interface <CODE>java.util.Collection</CODE><DT><B>Specified by:</B><DD><CODE>iterator</CODE> in interface <CODE>java.lang.Iterable</CODE></DL>
 513 </DD>
 514 <DD><DL>
 515
 516 <DT><B>Returns:</B><DD>iterator over all elements in the Bag</DL>
 517 </DD>
 518 </DL>
 519 <!-- ========= END OF CLASS DATA ========= -->
 520 <HR>
 521
 522
 523 <!-- ======= START OF BOTTOM NAVBAR ====== -->
 524 <A NAME="navbar_bottom"><!-- --></A>
 525 <A HREF="#skip-navbar_bottom" title="Skip navigation links"></A>
 526 <TABLE BORDER="0" WIDTH="100%" CELLPADDING="1" CELLSPACING="0" SUMMARY="">
 527 <TR>
 528 <TD COLSPAN=2 BGCOLOR="#EEEEFF" CLASS="NavBarCell1">
 529 <A NAME="navbar_bottom_firstrow"><!-- --></A>
 530 <TABLE BORDER="0" CELLPADDING="0" CELLSPACING="3" SUMMARY="">
 531   <TR ALIGN="center" VALIGN="top">
 532   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../overview-summary.html"><FONT CLASS="NavBarFont1"><B>Overview</B></FONT></A>&nbsp;</TD>
 533   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-summary.html"><FONT CLASS="NavBarFont1"><B>Package</B></FONT></A>&nbsp;</TD>
 534   <TD BGCOLOR="#FFFFFF" CLASS="NavBarCell1Rev"> &nbsp;<FONT CLASS="NavBarFont1Rev"><B>Class</B></FONT>&nbsp;</TD>
 535   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="class-use/Bag.html"><FONT CLASS="NavBarFont1"><B>Use</B></FONT></A>&nbsp;</TD>
 536   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="package-tree.html"><FONT CLASS="NavBarFont1"><B>Tree</B></FONT></A>&nbsp;</TD>
 537   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../deprecated-list.html"><FONT CLASS="NavBarFont1"><B>Deprecated</B></FONT></A>&nbsp;</TD>
 538   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../index-all.html"><FONT CLASS="NavBarFont1"><B>Index</B></FONT></A>&nbsp;</TD>
 539   <TD BGCOLOR="#EEEEFF" CLASS="NavBarCell1">    <A HREF="../../../../help-doc.html"><FONT CLASS="NavBarFont1"><B>Help</B></FONT></A>&nbsp;</TD>
 540   </TR>
 541 </TABLE>
 542 </TD>
 543 <TD ALIGN="right" VALIGN="top" ROWSPAN=3><EM>
 544 </EM>
 545 </TD>
 546 </TR>
 547
 548 <TR>
 549 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 550 &nbsp;<A HREF="../../../../org/apache/commons/collections/ArrayStack.html" title="class in org.apache.commons.collections"><B>PREV CLASS</B></A>&nbsp;
 551 &nbsp;<A HREF="../../../../org/apache/commons/collections/BagUtils.html" title="class in org.apache.commons.collections"><B>NEXT CLASS</B></A></FONT></TD>
 552 <TD BGCOLOR="white" CLASS="NavBarCell2"><FONT SIZE="-2">
 553   <A HREF="../../../../index.html?org/apache/commons/collections/Bag.html" target="_top"><B>FRAMES</B></A>  &nbsp;
 554 &nbsp;<A HREF="Bag.html" target="_top"><B>NO FRAMES</B></A>  &nbsp;
 555 &nbsp;<SCRIPT type="text/javascript">
 556   <!--
 557   if(window==top) {
 558     document.writeln('<A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>');
 559   }
 560   //-->
 561 </SCRIPT>
 562 <NOSCRIPT>
 563   <A HREF="../../../../allclasses-noframe.html"><B>All Classes</B></A>
 564 </NOSCRIPT>
 565
 566
 567 </FONT></TD>
 568 </TR>
 569 <TR>
 570 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
 571   SUMMARY:&nbsp;NESTED&nbsp;|&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_summary">METHOD</A></FONT></TD>
 572 <TD VALIGN="top" CLASS="NavBarCell3"><FONT SIZE="-2">
 573 DETAIL:&nbsp;FIELD&nbsp;|&nbsp;CONSTR&nbsp;|&nbsp;<A HREF="#method_detail">METHOD</A></FONT></TD>
 574 </TR>
 575 </TABLE>
 576 <A NAME="skip-navbar_bottom"></A>
 577 <!-- ======== END OF BOTTOM NAVBAR ======= -->
 578
 579 <HR>
 580 Copyright © 2001-2008 <a href="http://www.apache.org/">The Apache Software Foundation</a>. All Rights Reserved.
 581 </BODY>
 582 </HTML>