\subsubsection{\Collections}
\label{sec:collection}
In order to support a rich variety of graphs and to ensure that these
can interact smoothly with each other and with algorithms written later on,
we decided to implement a hierarchy of \Collection\ objects that is 
more involved than those of other C++ libraries.  This fundamental decision
has had the desired effect of allowing great flexibility in the definition
and manipulation of graphs, but also the undesired effect of introducing an
uncomfortable level of complexity due to its combination of 
templating and inheritance.  In other words, to the user and library 
programmer, the system is flexible, whereas system designers
and library extenders must use tools to handle the instantiation of
so many templated classes.
Note that the hierarchy, shown in Figure~\ref{fig:coll-hier}, 
is not very large from the point of view of an object-oriented 
designer.  Nevertheless, it generates enough complexity to require
an automated template instantiation procedure, which, since it
is not available in most C++ compilers, had to be designed along with
the system.

\begin{figure}
\centerline{\psfig{height=3in,width=4in,figure=figures/collection_hier.ps}}
%\centerline{\includegraphics*[height=3in,width=4in]{figures/collection_hier.ps}}
\caption{The \Collection\ Hierarchy}
\label{fig:coll-hier}
\end{figure}
Objects of classes in the \Collection\ hierarchy can be thought of as
``shells'' surrounding a storage medium from the \Container\ class 
hierarchy.  These shells filter the messages sent to the underlying
\Container\ instance, thus providing a small, clean interface to the
\Container\ hierarchy.  Set primitive operations are defined for any
two objects of the \Collection\ hierarchy. 

\subsubsubsection{Organization}
Class \Collection\ itself is an abstract base class, meaning that there
are no true ``\Collection'' objects.  However, pointers and references to
sets and sequences of the \Collection\ hierarchy have access to a 
consistent interface, consisting of a set of member function prototypes
and a set of comparison operations.  The term ``\Collection\ objects''
is used to refer to instances of classes in the hierarchy.
The elements stored in collection objects are considered to come
from a totally ordered universe.  In order to compile an instantiation
of a  collection object with a new element type $A$, the following 
operations must be defined: 
\begin{itemize}
\item \verb+A::int operator==(const A&) const;+
\item \verb+A::int operator<(const A&) const;+
\item \verb+friend ostream& operator<<(ostream&, const A&);+
\end{itemize}
The  collection objects available to the programmer are listed below
and defined completely in the subsections to follow.  A {\em multiset}
(or {\em bag}) is a group of elements in which multiple occurrences of
a given element are allowed.
\begin{itemize}
\item \verb+MSetBase<Item, Impl> +:  multiset (the implementation
			can be chosen from among the \Containers).
\item \verb+SetBase<Item, Impl> +:  set (the implementation
			can be chosen from among the \Containers).
\item \verb+SequenceBase<Item, Impl> +:  sequence (the implementation
			can be chosen from among the \Containers).
\item \verb+MSet<Item>+: multiset which uses a default implementation 
\item \verb+Set<Item>+: set which uses a default implementation
\item \verb+Sequence<Item>+: sequence which uses a default implementation
\end{itemize}
The comparison methods of set objects (\MSetBase,\ \MSet,\ \SetBase,\
\Set) work under the 
assumption that the elements are stored in lexicographic order.
Therefore, in order for these operations to work correctly, the
underlying \Container\ implementation must store the elements in
sorted order, or at least be capable of iterating through the 
elements in sorted order.  With this restriction in mind, it is 
possible to introduce new \Container\ objects into LINK and use
them as \Collection\ implementations.

\subsubsubsection{Reference Counting}
Aside from implementing the core set and sequence operations, the 
\Collection\ hierarchy offers the programmer a major advantage
when compared to the \Container\ hierarchy. 
\begin{quote}	
	The copying of \Collections\ is implemented {\em efficiently} 
	if possible, i.e., if the source object is a descendent of
	the destination object, using
	a reference counting scheme.  This is of great importance when
	dealing with frequently passed groups of objects such as the 
	neighbors of a vertex.  In contrast, the initialization 
	of one \Container\ 
	with another is always accomplished by iteration through all of the 
	elements.
\end{quote}
All class derivation in the \Collection\ hierarchy is public.  In general,
if a child class is derived publically from a parent class, it is 
convenient to say that a child class instance {\em is a} parent class
instance.  For example, a set {\em is a} multiset in which no insertion 
of duplicate elements can occur.~\footnote{This relationship itself was
a fundamental design decision.  Clearly, we could say that a multiset
{\em is a} set augmented with frequency counts for its elements.  We
judged that the flexibility associated with 
storing multiple element occurrences explicitly outweighed the
improved efficiency in element counting and searching inherent in the
alternative organization.}
This inheritance determines whether or not a given 
copy operation will involve an increment in 
reference count or the iteration through all of the elements.  
For example, consider the code fragment in Figure~\ref{fig:MSet8}.
\begin{figure}[tbp]
\input{ProgMSet8.tex}
\caption{Interaction of \Collection\ objects and reference counting}
\label{fig:MSet8}
\end{figure}
The objects defined in this example are all \Collections, so they may
interact with one another.  Note that since the function
{\em f} takes a \Collection\ reference as an argument, any object of
this hierarchy may be passed as an actual parameter. 
However, some operations
will be more efficient than others.   For example, the return 
from the function call  
on line 22 involves only a reference count rather than a copy of 
return value.  That on line 23, however, does involve a copy of 
the return value since the class of the receiving variable is not an
ancestor of the return value's class.  Can the reader tell whether
or not the operation on line 9 involves a copy?~\footnote{It does.
\MSet\ is not an ancestor of \Collection.}  When the object \verb+m2+
is destructed upon function return, the reference count is decremented.
Whenever a reference count reaches zero, the elements of the collection
are deleted.

Still referring to Figure~\ref{fig:MSet8}, 
the reference counting mechanism is certainly used for the 
assignment on line 24 (why?),
meaning that afterwards, the objects \verb+result+ and \verb+result2+ both
refer to a single collection of objects.  The modification to 
\verb+result2+ on line 25, however, forces a new copy of the elements
to be made for consistency.  What about the assignment on line 21?
A review of Figure~\ref{fig:coll-hier} will indicate whether or not
reference counting is employed.  The flexibility of the \Collection\
hierarchy combined with the efficiency of reference counting makes
these classes a strong foundation upon which to build graphs. 

\subsubsubsection{Set Primitive Operations}
The three set primitive operations (union, intersection, and difference)
are binary operations which take arbitrary \Collection\ objects as
arguments, treat them as multisets, and return the result as a multiset.
\begin{figure}[tbp]
\input{ProgMSet6.tex}
\caption{Set Primitives with Set and Sequence Operands }
\label{fig:MSet6}
\end{figure}
\clearpage
The example in 
Figure~\ref{fig:MSet6} shows the
treatment of sequences as sets during these operations.  Note that
the type of the object receiving the return value of each operation 
determines whether the result is a set or a multiset.


\subsubsubsection{Combinatorial Operations}
Extension classes of the \Collection\ hierarchy offer functionality including
the manipulation of power sets, combinations, cartesian products, 
and permutations.   These operations in turn support graph complementation
and product, examining permutations of vertices, etc. 

