Go to the previous, next section.
#include <nihcl/Collection.h>
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()
)
remove()
)
addContentsTo()
)
includes()
)
isEmpty()
)
size()
)
capacity()
)
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 const unsigned DEFAULT_CAPACITY
DEFAULT_CAPACITY
is currently set to 16.
static const unsigned EXPANSION_INCREMENT
OrderedCltn
, expand thmeselves by a fixed amount.
EXPANSION_INCREMENT
defines this amount. It is currently set to 32.
static const unsigned EXPANSION_FACTOR
Set
,
Bag
, and
Dictionary
, expand themselves by a fixed multiple.
EXPANSION_FACTOR
defines this factor. It is currently set to 2.
virtual Object* add(Object&
ob) = 0
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)
Collection
and returns a reference to
cltn.
virtual Collection& addContentsTo(Collection&
cltn) const
Collection
to
cltn
and returns a reference to
cltn.
virtual Object* remove(const Object&
ob) = 0
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
Collection
.
virtual const Collection& removeCltn(const Collection&
cltn)
Collection
.
virtual unsigned hash() const = 0
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
Collection
.
virtual int compare(const Object&
cltn) const = 0
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
YES
when the
Collection
and the argument
Collection
cltn
have the same list of
Object
pointers.
virtual bool includes(const Object&
ob) const
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
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
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()
.
virtual void deepenShallowCopy()
Collection::deepenShallowCopy()
is a no-op.
virtual Object*& at(int
i) = 0
virtual const Object *const& at(int
i) const = 0
Collection
.
virtual unsigned capacity() const = 0
virtual unsigned size() const = 0
Collection
.
ArrayOb asArrayOb() const
Bag asBag() const
Heap asHeap() const
OrderedCltn asOrderedCltn() const
Set asSet() const
SortedCltn asSortedCltn() const
Collection
.
virtual void dumpOn(ostream&
strm
=cerr) const
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
printOn(strm)
to each object in this
Collection
. Prints a newline to
strm
between calls to
printOn()
.
virtual void doFinish(Iterator&
pos) const
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
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
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; }
virtual ~Collection()
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.
virtual void _reader(OIOifd&
fd)
virtual void _reader(OIOin&
strm)
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
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
.
Go to the previous, next section.