A bag is an unordered collection of zero or more elements with no key. Multiple elements are supported. A request to add an element that already exists is not ignored.
An example of using a bag is a program for entering observations on species of plants and animals found in a river. Each time you spot a plant or animal in the river, you enter the name of the species into the collection. If you spot a species twice during an observation period, the species is added twice, because a bag supports multiple elements. You can locate the name of a species that you have observed, and you can determine the number of observations of that species, but you cannot sort the collection by species, because a bag is an unordered collection. If you want to sort the elements of a bag, use a sorted bag instead.
The following rule applies for duplicates: If bag P contains the element X m times and bag Q contains the element X n times, then the union of P and Q contains the element X m+n times, the intersection of P and Q contains the element X MIN(m,n) times, and the difference of P and Q contains the element X m-n times if m is > n, and zero times if m is <= n.
You can construct and destruct objects of this class.
![]() |
public:
~IABag()
Removes all elements from the collection. Destructors are called for all elements contained in the collection and for elements that have been constructed in advance.
Side Effects
All cursors of the collection become undefined.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
IABag(INotifier&)
Use this constructor to create a collection with support for notification.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
protected:
IABag(IABag < Element > const&)
Constructs a collection.
The collection is unbounded and is initially empty.
Exception
IOutOfMemory
Note:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
protected:
IABag()
The default constructor.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
Use these members to execute miscellaneous operations.
![]() |
public:
virtual void addDifference( IABag < Element > const&, IABag < Element > const& )
Creates the difference between the two given collections, and adds this difference to the collection. The contents of the added elements, not the pointers to those elements, are copied.
For a definition of the difference between two collections, see IABag::differenceWith.
Preconditions
Because the elements are added one by one, the following preconditions are tested for each individual addition.
Side Effects
If any elements were added, all cursors of this collection become undefined.
Exceptions
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual void addIntersection( IABag < Element > const&, IABag < Element > const& )
Creates the intersection of the two given collections, and adds this intersection to the collection. The contents of the added elements, not the pointers to those elements, are copied.
For a definition of the intersection of two collections, see IABag::intersectionWith.
Preconditions
Because the elements are added one by one, the following preconditions are tested for each individual addition.
Side Effects
If any elements were added, all cursors of this collection become undefined.
Exceptions
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual void addUnion( IABag < Element > const&, IABag < Element > const& )
Creates the union of the two given collections, and adds this union to the collection. The contents of the added elements, not the pointers to those elements, are copied.
For a definition of the union of two collections, see IABag::unionWith.
Preconditions
Because the elements are added one by one, the following preconditions are tested for each individual addition.
Side Effects
If any elements were added, all cursors of this collection become undefined.
Exceptions
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual void differenceWith(IABag < Element > const&)
Makes the collection the difference between the collection and the given collection. The difference of A and B (A minus B) is the set of elements that are contained in A but not in B.
The following rule applies for bags with duplicate elements: If bag P contains the element X m times and bag Q contains the element X n times, the difference of P and Q contains the element X m-n times if m > n, and zero times if m<=n.
Side Effects
If any elements were removed, all cursors of this collection become undefined.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual void intersectionWith(IABag < Element > const&)
Makes the collection the intersection of the collection and the given collection. The intersection of A and B is the set of elements that is contained in both A and B.
The following rule applies for bags with duplicate elements: If bag P contains the element X m times and bag Q contains the element X n times, the intersection of P and Q contains the element X MIN(m,n): times.
Side Effects
If any elements were removed, all cursors of this collection become undefined.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
INumber numberOfDifferentElements() const
Returns the number of different elements in the collection.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool operator !=(IABag < Element > const&) const
Returns true if the given collection is not equal to the collection. For a definition of equality for collections, see IABag::operator ==.
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool operator ==(IABag < Element > const&) const
Returns true if the given collection is equal to the collection. Two collections are equal if the number of elements in each collection is the same, and if the condition for the collection is described in the following list:
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
bool setToNextDifferentElement(ICursor&) const
Sets the cursor to the next element in the collection in iteration order with a key different from the key of the element pointed to by the given cursor. If no such element exists, the given cursor is no longer valid.
Preconditions
The cursor must belong to the collection and must point to an element of the collection.
Return Value
Returns true if a subsequent element was found whose key is different from the current key.
Exception
ICursorInvalidException
Windows | OS/2 | AIX |
Yes | Yes | Yes |
![]() |
public:
virtual void unionWith(IABag < Element > const&)
Makes the collection the union of the collection and the given collection. The union of A and B is the set of elements that are members of A or B or both.
The following rule applies for bags with duplicate elements: If bag P contains the element X m times and bag Q contains the element X n times, the union of P and Q contains the element X m+n times.
Preconditions
Because the elements from the given collection are added to the collection one by one, the following preconditions are tested for each individual add operation :
Side Effects
If any elements were added to the collection, all cursors of this collection become undefined.
Exceptions
Windows | OS/2 | AIX |
Yes | Yes | Yes |
virtual ~IACollection()
virtual bool add(Element const&)
virtual bool add(Element const&, ICursor&)
virtual void addAllFrom(IACollection < Element > const&)
void adoptStreamer(IACollectionStreamer*)
bool allElementsDo( bool ( * applicatorFunction ) ( Element&, void * ) , void* additionalArgument = 0 )
bool allElementsDo(IApplicator < Element >&)
bool allElementsDo( bool ( * applicatorFunction ) ( Element const&, void * ) , void* additionalArgument = 0 ) const
bool allElementsDo(IConstantApplicator < Element >&) const
Element const& any() const
Element const& anyElement() const
virtual void copy(IACollection < Element > const&)
INotifier& disableNotification()
Element const& elementAt(ICursor const&) const
Element& elementAt(ICursor const&)
INotifier& enableNotification(bool = true)
IACollection(INotifier&)
bool isBounded() const
bool isConsistent() const
bool isEmpty() const
bool isEnabledForNotification() const
bool isFull() const
INumber maxNumberOfElements() const
virtual ICursor* newCursor() const
ICursor* newMngCursor() const
INotifier const& notifier() const
INotifier& notifier()
INotifier& notifyObservers(INotificationEvent const&)
INumber numberOfElements() const
virtual void operator <<=(IDataStream&)
virtual void operator >>=(IDataStream&)
operator INotifier &() const
virtual INumber removeAll( bool ( * predicateFunction ) ( Element const&, void * ) , void* additionalArgument = 0 )
virtual INumber removeAll()
virtual void removeAt(ICursor&)
virtual void replaceAt(ICursor const&, Element const&)
bool setToFirst(ICursor&) const
bool setToNext(ICursor&) const
~IAEqualityCollection()
bool contains(Element const&) const
bool containsAllFrom(IACollection < Element > const&) const
IAEqualityCollection(INotifier&)
bool locate(Element const&, ICursor&) const
bool locateNext(Element const&, ICursor&) const
virtual bool locateOrAdd(Element const&)
virtual bool locateOrAdd(Element const&, ICursor&)
INumber numberOfOccurrences(Element const&) const
virtual bool remove(Element const&)
virtual INumber removeAllOccurrences(Element const&)
IACollection(IACollection < Element > const&)
IACollection()
static Implementation& ImplOf( IACollection < Element > const& )
IAEqualityCollection()
IAEqualityCollection( IAEqualityCollection < Element > const& )