Bag--Unordered Collection of Objects

A Bag is a Set of AssocInt objects. Each AssocInt object associates an object in a Bag with a count of the number of occurrences of that object. Each time an equal object, as determined by applying isEqual(), is added to a Bag, the object's associated occurrence count is incremented. Thus, unlike a Set, a Bag may contain multiple occurrences of equal objects.

CONSTRUCTORS

Bag(unsigned capacity =DEFAULT_CAPACITY): Constructs an empty Bag that can hold up to capacity objects. An NIHCL_ALLOCSIZE error is raised if capacity is not greater than 0. If an attempt is made to add more than capacity objects to a Bag, reSize() is called to increase its capacity. Since this is an expensive operation, it is wise to supply a reasonable estimate for capacity.
Bag(const Bag& b): Constructs an instance of a Bag that is the same size as Bag b and initializes it to point to the same objects contained in b.

ADDING OBJECTS

virtual Object* add(Object& ob): Checks this Bag to see if it already contains an object that is equal to ob, as determined by applying isEqual(). If not, add() adds ob to this Bag with an occurrence count of 1 and returns a pointer to ob. If an object that is equal to ob is already in this Bag, add() increments the occurrence count for this object and returns a pointer to this object instead of a pointer to ob.
Object* addWithOccurrences(Object& ob, unsigned n): Similar to Bag::add(), except that ob's occurrence count is initialized to or increased by n instead of 1.

REMOVING OBJECTS

virtual Object* remove(const Object& ob): Finds the object equal to ob in this Bag, as determined by applying isEqual(). If no equal object is found, remove() raises an NIHCL_REMOVEERR; otherwise, remove() decrements this object's occurrence count. If the occurrence count is non-zero, remove() returns 0; when an object's occurrence count reaches zero, the object is removed from this Bag and remove() returns a pointer to it.
virtual void removeAll(): Removes all occurrences of all objects in this Bag.

SEARCHING

virtual unsigned hash() const: Returns a number that classes such as Set can use as a hash table probe. Class Bag implements hash() by exclusive ORing the results of applying hash() to all objects in a Bag.
virtual unsigned occurrencesOf(const Object& ob) const: Returns the occurrence count of the object in this Bag that is equal to ob, as determined by applying isEqual(). Returns 0 if no equal object is contained in this Bag.

RELATIONAL OPERATORS

bool operator==(const Bag&) const
bool operator!=(const Bag&) const: Returns YES if the right Bag operand is equal to (or not equal to) the left Bag operand. Two Bags a and b are equal if they contain the same number of objects and if, for each object in a, there is an isEqual() object in b with the same occurrence count.

TESTING BAGS

virtual bool isEqual(const Object& b) const: Returns YES if this Bag and the argument object are comparable and they have equal values. The argument object a is comparable if it returns the address of class Bag's class descriptor for its species(). Class Bag implements isEqual() by applying isEqual() to all objects in a Bag.

COPYING BAGS

void operator=(const Bag&): Replaces the left Bag operand with a copy of the right Bag operand. Only the pointers to the objects contained in the right operand are copied, not the objects they point to.
virtual void deepenShallowCopy(): Converts this shallow copy to a deep copy by applying deepCopy() to all the object pointers, replacing each pointer with a pointer to its copy.

INDEXING BAGS

virtual Object*& at(int i)
virtual const Object *const& at(int i) const: Returns a reference to the ith object pointer in the underlying Set object used by this Bag. This will be a pointer to either the nil object (if the ith hash table position is unoccupied), or a pointer to an AssocInt that associates an object in this Bag with its occurrence count. Because this function relies on the underlying implementation of class Bag as a Set of AssocInts, it is not recommended for general use.

BAG CAPACITY AND SIZE

virtual unsigned capacity() const: Returns the number of non-duplicate objects that this Bag can hold before it will need to be expanded.
virtual unsigned size() const: Returns the number of objects in this Bag. Since size() includes multiple occurrences of duplicate (i.e. isEqual()) objects, a Bag's size() may exceed its capacity().
virtual void reSize(unsigned newSize): Changes the capacity of this Bag to newSize. If newSize is less than or equal to capacity(), then the capacity is not changed.

PRINTING BAGS

virtual void dumpOn(ostream& strm =cerr) const: Prints the class name, a left square bracket, applies dumpOn() to all AssocInt objects in this Bag to print each object and its occurrence count, then prints a right square bracket and a newline.

SUPPORT FOR ITERATORS

virtual Object* doNext(Iterator& pos) const: Returns a pointer to the next object in this Bag, or 0 if no more objects remain. The Iterator argument pos maintains the current position in the Bag.

BAG SPECIES

virtual const Class* species() const: Returns a pointer to the class descriptor for class Bag.

PROTECTED MEMBERS

Object I/O

virtual void _reader(OIOifd& fd)
virtual void _reader(OIOin& strm): Reads the representations of objects from fd or strm along with their occurrence counts and calls addWithOccurrences() to add them to this Bag. Does nothing unless called from the readFrom() constructor of a most-derived class. This assures that _reader() calls the most-derived implementation of the virtual function addWithOccurrences().
virtual void storer(OIOofd& fd) const
virtual void storer(OIOout& strm) const: Apply storeOn() to each of the objects contained in this Bag to store them on fd or strm along with each object's occurrence count.

DISABLED MEMBER FUNCTIONS

virtual int compare(const Object&) const: This function is implemented as shouldNotImplement().

EXCEPTIONS RAISED

NIHCL_REMOVEERR

Go to the previous, next section.