org.apache.commons.collections
Interface Bag
- Collection
- SortedBag
- DefaultMapBag, HashBag, TreeBag
public interface Bag
extends Collection
A
Collection
that counts the number of times an object appears in
the collection. Suppose you have a Bag that contains
{a, a, b,
c}
. Calling
getCount(Object)
on
a
would return
2, while calling
uniqueSet()
would return
{a, b, c}
.
Note that this interface violates the Collection
contract.
The behavior specified in many of these methods is
not the same
as the behavior specified by
Collection
. The noncompliant methods
are clearly marked with "(Violation)" in their summary line. A future
version of this class will specify the same behavior as
Collection
,
which unfortunately will break backwards compatibility with this version.
boolean | add(Object o) - (Violation)
Add the given object to the bag and keep a count.
|
boolean | add(Object o, int i) - Add
i copies of the given object to the bag and
keep a count.
|
boolean | containsAll(Collection c) - (Violation)
Returns
true if the bag contains all elements in
the given collection, respecting cardinality.
|
int | getCount(Object o) - Return the number of occurrences (cardinality) of the given
object currently in the bag.
|
Iterator | iterator() - Returns an
Iterator over the entire set of members,
including copies due to cardinality.
|
boolean | remove(Object o) - (Violation)
Remove all occurrences of the given object from the bag, and do
not represent the object in the
uniqueSet() .
|
boolean | remove(Object o, int i) - Remove the given number of occurrences from the bag.
|
boolean | removeAll(Collection c) - (Violation)
Remove all elements represented in the given collection,
respecting cardinality.
|
boolean | retainAll(Collection c) - (Violation)
Remove any members of the bag that are not in the given
collection, respecting cardinality.
|
int | size() - Returns the total number of items in the bag across all types.
|
Set | uniqueSet() - The
Set of unique members that represent all members in
the bag.
|
add
public boolean add(Object o)
(Violation)
Add the given object to the bag and keep a count. If the object
is already in the
uniqueSet()
then increment its count as
reported by
getCount(Object)
. Otherwise add it to the
uniqueSet()
and report its count as 1.
Since this method always increases the size of the bag,
according to the
Collection.add(Object)
contract, it
should always return
true
. Since it sometimes returns
false
, this method violates the contract. A future
version of this method will comply by always returning
true
.
true
if the object was not already in the
uniqueSet
add
public boolean add(Object o,
int i)
Add i
copies of the given object to the bag and
keep a count.
true
if the object was not already in the
uniqueSet
containsAll
public boolean containsAll(Collection c)
(Violation)
Returns
true
if the bag contains all elements in
the given collection, respecting cardinality. That is, if the
given collection
C
contains
n
copies
of a given object, calling
getCount(Object)
on that object must
be
>= n
for all
n
in
C
.
The
Collection.containsAll(Collection)
method specifies
that cardinality should
not be respected; this method should
return true if the bag contains at least one of every object contained
in the given collection. A future version of this method will comply
with that contract.
getCount
public int getCount(Object o)
Return the number of occurrences (cardinality) of the given
object currently in the bag. If the object does not exist in the
bag, return 0.
iterator
public Iterator iterator()
Returns an Iterator
over the entire set of members,
including copies due to cardinality. This iterator is fail-fast
and will not tolerate concurrent modifications.
remove
public boolean remove(Object o)
(Violation)
Remove all occurrences of the given object from the bag, and do
not represent the object in the
uniqueSet()
.
According to the
Collection.remove(Object)
method,
this method should only remove the
first occurrence of the
given object, not
all occurrences. A future version of this
method will comply with the contract by only removing one occurrence
of the given object.
true
if this call changed the collection
remove
public boolean remove(Object o,
int i)
Remove the given number of occurrences from the bag. If the bag
contains
i
occurrences or less, the item will be
removed from the
uniqueSet()
.
true
if this call changed the collection
removeAll
public boolean removeAll(Collection c)
(Violation)
Remove all elements represented in the given collection,
respecting cardinality. That is, if the given collection
C
contains
n
copies of a given object,
the bag will have
n
fewer copies, assuming the bag
had at least
n
copies to begin with.
The
Collection.removeAll(Collection)
method specifies
that cardinality should
not be respected; this method should
remove
all occurrences of every object contained in the
given collection. A future version of this method will comply
with that contract.
true
if this call changed the collection
retainAll
public boolean retainAll(Collection c)
(Violation)
Remove any members of the bag that are not in the given
collection, respecting cardinality. That is, if the given
collection
C
contains
n
copies of a
given object and the bag has
m > n
copies, then
delete
m - n
copies from the bag. In addition, if
e
is an object in the bag but
!C.contains(e)
, then remove
e
and any
of its copies.
The
Collection.retainAll(Collection)
method specifies
that cardinality should
not be respected; this method should
keep
all occurrences of every object contained in the
given collection. A future version of this method will comply
with that contract.
true
if this call changed the collection
size
public int size()
Returns the total number of items in the bag across all types.
uniqueSet
public Set uniqueSet()
The Set
of unique members that represent all members in
the bag. Uniqueness constraints are the same as those in Set
.
Copyright © 2001-2004 Apache Software Foundation. Documenation generated ${TODAY}.