WWC snapshot of http://www.alw.nih.gov/Docs/NIHCL/nihcl_9.html taken on Sat Jun 10 19:13:37 1995

Go to the previous, next section.

Collection--Abstract Base Class for Containers

Class Collection is the abstract base class for the NIH Class Library's container classes, so called because they hold, or contain, instances of NIH Library classes. Examples of container classes include implementations of classic data structures such as indexed arrays (class OrderedCltn), stacks (class Stack), singly-linked lists (class LinkedList), hash tables (class Set), and associative arrays (class Dictionary).

Class Collection declares those virtual member functions that apply to all container classes:

add an object to a container (add())
remove an object from a container (remove())
convert one type of container to another
copy objects from one container to another (addContentsTo())
test for the presence of an object in a container (includes())
test for an empty container (isEmpty())
report the number of objects in a container (size())
report the capacity of a container (capacity())
report the number of occurrences of a particular object in a container (occurrencesOf())

Thus, a client program can perform these operations on a container object without needing to know specifically what kind of container it is.

Classes derived from Collection are expected to provide the following member functions: add(), at(), capacity(), compare(), doNext(), hash(), isEqual(), occurrencesOf(), remove(), removeAll(), and size().

STATIC CONSTANTS

static const unsigned DEFAULT_CAPACITY: The default initial capacity of collections. For most container classes, this is not a hard limit--a container will usually expand itself to increase its capacity if necessary, although this may be a time-consuming operation. DEFAULT_CAPACITY is currently set to 16.
static const unsigned EXPANSION_INCREMENT: When an object is added to a container already at its capacity, some container classes, such as OrderedCltn, expand thmeselves by a fixed amount. EXPANSION_INCREMENT defines this amount. It is currently set to 32.
static const unsigned EXPANSION_FACTOR: When an object is added to a container already at its capacity, some container classes, such as Set, Bag, and Dictionary, expand themselves by a fixed multiple.
EXPANSION_FACTOR defines this factor. It is currently set to 2.

ADDING OBJECTS

virtual Object* add(Object& ob) = 0: Adds the object ob to this Collection and returns a pointer to the object actually in the Collection. The pointer returned may point to an object other than ob for container classes that reject the addition of duplicate objects, such as class Set and its derived classes. Note that a derived container class may supply its own definition of what it considers "duplicate" objects; for example, class Set applies isEqual(), while class IdentSet applies isSame().
virtual const Collection& addAll(const Collection& cltn): Adds all of the objects in cltn to this Collection and returns a reference to cltn.
virtual Collection& addContentsTo(Collection& cltn) const: Adds all of the objects in this Collection to cltn and returns a reference to cltn.

REMOVING OBJECTS

virtual Object* remove(const Object& ob) = 0: Removes the object ob from this Collection and returns a pointer to the object removed. The pointer returned may point to an object other than ob when a container uses a function other than isSame() to locate the object to be removed.
virtual void removeAll() = 0: Removes all objects from this Collection.
virtual const Collection& removeCltn(const Collection& cltn): Removes all of the objects in cltn from this Collection.

SEARCHING

virtual unsigned hash() const = 0: Returns a number that classes such as Set can use as a hash table probe. If two objects are equal; that is, if isEqual() returns YES for the objects, then the two objects must return the same value for hash().
virtual unsigned occurrencesOf(const Object& ob) const = 0: Returns the number of occurrences of ob in this Collection.

COMPARING CONTAINERS

virtual int compare(const Object& cltn) const = 0: Compares this Collection with the argument Collection cltn and returns a negative result if this Collection is less than cltn, zero if this Collection equals cltn, and a positive result if this Collection is greater than cltn.
virtual bool sameContentsAs(const Collection& cltn) const: Returns YES when the Collection and the argument Collection cltn have the same list of Object pointers.

TESTING CONTAINERS

virtual bool includes(const Object& ob) const

Returns YES if ob is contained in this Collection. Collection::includes() is implemented as:

bool Collection::includes(const Object& ob) const
{
    return occurrencesOf(ob) != 0;
}

virtual bool isEmpty() const

Returns YES if this Collection is empty. Collection::isEmpty() is implemented as:

bool Collection::isEmpty() const
{
    return size() == 0;
}

virtual bool isEqual(const Object& cltn) const = 0

Returns YES if this Collection and the argument cltn are comparable and they have equal values. Note that the functions isEqual() and hash() must be consistently defined; that is, if two objects are isEqual(), then they must return the same value for hash().

COPYING CONTAINERS

virtual void deepenShallowCopy(): Collection::deepenShallowCopy() is a no-op.

INDEXING CONTAINERS

virtual Object*& at(int i) = 0
virtual const Object *const& at(int i) const = 0: Returns a reference to the ith object in this Collection.

CONTAINER SIZE

virtual unsigned capacity() const = 0
virtual unsigned size() const = 0: Returns the number of objects in this Collection.

CONVERTING CONTAINERS

ArrayOb asArrayOb() const
Bag asBag() const
Heap asHeap() const
OrderedCltn asOrderedCltn() const
Set asSet() const
SortedCltn asSortedCltn() const: Returns a collection of the indicated type after adding to it all the objects in this Collection.

PRINTING CONTAINERS

virtual void dumpOn(ostream& strm =cerr) const: Prints the class name of this Collection, a left square bracket, applys dumpOn(strm) to each object in this Collection, then prints a right square bracket and a newline.
virtual void printOn(ostream& strm =cout) const: Applies printOn(strm) to each object in this Collection. Prints a newline to strm between calls to printOn().

SUPPORT FOR ITERATORS

virtual void doFinish(Iterator& pos) const

The destructor for class Iterator calls doFinish() to give a container an opportunity to deallocate any additional objects it may have created to maintain state during an iteration. Containers usually use the member variable pos .state to hold a pointer to such an object.

Collection::doFinish() is a no-op.

virtual Object* doNext(Iterator& pos) const = 0

Returns a pointer to the next object in this Collection, or 0 if no more objects remain. The Iterator argument pos maintains the state of the iteration for a container so that multiple iterations may be active concurrently for the same container.

virtual void doReset(Iterator& pos) const

The constructor for class Iterator and the member function Iterator::reset() call doReset() to reset the position of an iteration to the beginning of this Collection; that is, so that the next call to doNext() returns the first object in this Collection.

Collection::doReset() is implemented as:

void Collection::doReset(Iterator& pos) const
{
    pos.index = 0;
    pos.ptr = NULL;
    pos.num = 0;
}

DESTROYING CONTAINERS

virtual ~Collection(): The destructor for class Collection is implemented as a no-op, but since it is virtual, is forces the destructors for all derived container classes to be virtual also. A container can therefore be destroyed without knowing its specific class.

PROTECTED MEMBERS

Object I/O

virtual void _reader(OIOifd& fd)
virtual void _reader(OIOin& strm): Reads the representations of objects from fd or strm and calls add() to add them to this Collection. 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 add().
void _storer(OIOofd& strm) const
void _storer(OIOout& fd) const: The storer() functions of container classes usually use _storer() to write the objects they contain to the output stream strm or file descriptor fd. Collection::_storer() writes the capacity and size of this Collection, then applies storeOn() to each object in this Collection.

EXCEPTIONS RAISED

None