388 lines
15 KiB
TeX
388 lines
15 KiB
TeX
\documentclass[11pt]{kasper}
|
|
%
|
|
% If you do not have 'kasper.cls', see
|
|
% http://www.damtp.cam.ac.uk/user/kp229/texstuff .
|
|
|
|
\usepackage{makeidx}
|
|
\usepackage{verbatim}
|
|
\usepackage{relsize}
|
|
\makeindex
|
|
%\newcommand{\toindex}[1]{#1\index{#1}}
|
|
|
|
\newcommand{\member}[1]{{\tt #1}\index{#1}}
|
|
%\newcommand{\member}[1]{{\tt #1}}
|
|
|
|
\def\mystrut{\vbox to 8.5pt{}\vtop to 3.5pt{}}
|
|
\def\V{\hskip10pt\vrule\hskip10pt}
|
|
\def\T{\hskip10pt\vrule\vrule height2.5pt depth -2.1pt width 10pt}
|
|
\def\L{\hskip10pt\vrule height 8.5pt depth -2.1pt
|
|
\vrule height2.5pt depth -2.1pt width 10pt}
|
|
\def\N{\hskip10pt\phantom{\vrule}\hskip10pt}
|
|
\def\hw{\hskip-1000pt plus 1fil}
|
|
|
|
% to test: insert before end of subtree
|
|
|
|
\begin{document}
|
|
\title{{\tt tree.hh} documentation}
|
|
\author{Kasper Peeters}
|
|
\email{kasper.peeters@gmail.com}
|
|
\maketitle
|
|
\begin{abstract}
|
|
The {\tt tree.hh} library for C++ provides an STL-like container class
|
|
for n-ary trees, templated over the data stored at the nodes. Various
|
|
types of iterators are provided (post-order, pre-order, and
|
|
others). Where possible the access methods are compatible with the STL
|
|
or alternative algorithms are available. The library is available
|
|
under the terms of the GNU General Public License.\\[3ex]
|
|
Code and examples available at: {\tt http://tree.phi-sci.com/}\\[3ex]
|
|
{\bf This documentation is not yet entirely complete. Refer to the {\tt
|
|
tree.hh} header file for a full list of member functions.}
|
|
\end{abstract}
|
|
\vfill
|
|
\maketoc
|
|
\eject
|
|
|
|
\begin{sectionunit}
|
|
\title{Overview}
|
|
\maketitle
|
|
\begin{sectionunit}
|
|
\title{The container class}
|
|
\maketitle
|
|
The tree class of {\tt tree.hh} is a templated container class in the
|
|
spirit of the STL. It organises data in the form of a so-called n-ary
|
|
tree. This is a tree in which every node is connected to an arbitrary
|
|
number of child nodes. Nodes at the same level of the tree are called
|
|
``siblings'', while nodes that are below a given node are called its
|
|
``children''. At the top of the tree, there is a set of nodes which
|
|
are characterised by the fact that they do not have any parents. The
|
|
collection of these nodes is called the ``head'' of the tree. See
|
|
figure~\ref{f:overview} for a pictorial illustration of this
|
|
structure (90 degrees rotated for convenience).
|
|
\begin{figure}[th]
|
|
\begin{center}
|
|
\includegraphics[width=.5\textwidth]{treefig}
|
|
\caption{Overview of the tree structure. The elements at the top of
|
|
the tree (here displayed at the left for convenience) are in the
|
|
``head'' (there can be more than one such element). Every node is
|
|
linked to its children using the ``first child'' and ``last child''
|
|
links. In addition, all nodes on a given level are doubly-linked using
|
|
the ``previous sibling'' and ``next sibling'' links. The ``depth'' of
|
|
a given node refers to the horizontal distance from the head nodes.}
|
|
\label{f:overview}
|
|
\end{center}
|
|
\end{figure}
|
|
|
|
The tree class is templated over the data objects stored at the nodes;
|
|
just like you can have a {\tt vector<string>} you can now have a
|
|
{\tt tree<string>}. Many STL algorithms work on this data structure,
|
|
and where necessary alternatives have been provided.
|
|
\medskip
|
|
|
|
\end{sectionunit}
|
|
\begin{sectionunit}
|
|
\title{Iterators}
|
|
\maketitle
|
|
|
|
The essential difference between a container with the structure of a
|
|
tree and the STL containers is that the latter are ``linear''. While
|
|
the STL containers thus only have essentially one way in which one can
|
|
iterate over their elements, this is not true for trees. The {\tt
|
|
tree.hh} library provides (at present) four different iteration
|
|
schemes. To describe them, consider the following tree:
|
|
\begin{equation*}
|
|
\vcenter{\offinterlineskip
|
|
\halign{&#\mystrut\hfil\cr
|
|
root \hw\cr
|
|
\T A \cr
|
|
\V \T B \cr
|
|
\V \L C \cr
|
|
\L D \cr
|
|
\N \T E \cr
|
|
\N \L F \cr}}
|
|
\end{equation*}
|
|
The three iteration types and the resulting order in which nodes are
|
|
visited are tabulated below:
|
|
\begin{center}
|
|
\begin{tabular}{llll}
|
|
pre-order (default) & ``element before children'' &
|
|
\member{pre\_order\_iterator} & root A B C D E F \\
|
|
post-order & ``element after children'' &
|
|
\member{post\_order\_iterator} & B C A E F D root \\
|
|
breadth-first & &
|
|
\member{breadth\_first\_iterator} & root A D B C E F \\
|
|
sibling & ``only siblings'' &
|
|
\member{sibling\_iterator} & (for ex.) A D \\
|
|
fixed-depth & &
|
|
\member{fixed\_depth\_iterator} & (for ex.) A D \\
|
|
leaf & &
|
|
\member{leaf\_iterator} & B C E F
|
|
\end{tabular}
|
|
\end{center}
|
|
The pre-order ones are the default iterators, and therefore also known
|
|
under the name of {\tt iterator}. Sibling iterators and fixed-depth
|
|
iterators iterate only over the nodes at a given depth of the
|
|
tree. The former restrict themselves to the child nodes of one given
|
|
node, while the latter iterates over all child nodes at the given
|
|
depth. Finally, leaf iterators iterate over all leafs (bottom-most)
|
|
nodes of the tree.
|
|
|
|
There are copy constructors that will convert iterators of the
|
|
various types into each other. The post- and pre-order iterators are
|
|
both also known as ``depth-first'', in contrast to the
|
|
``breadth-first'' iterator.
|
|
|
|
The begin and end iterators of a tree can be obtained using
|
|
\member{begin()} and \member{end()} (for pre-order iterators) or
|
|
alternatively \member{begin\_post()} and \member{end\_post()} (for
|
|
post-order iterators) and \member{begin\_leaf()} and
|
|
\member{end\_leaf()} (for leaf iterators). Similarly, the begin and
|
|
end sibling iterators can be obtained by calling
|
|
\member{begin(iterator)} and \member{end(iterator)}. The range of
|
|
children of a given node can also be obtained directly from an
|
|
iterator, by using the {\tt iterator::begin()} and {\tt
|
|
iterator::end()} member functions.
|
|
|
|
If you want to (temporarily) make an iterator not go into the child
|
|
subtree, call the member function \member{skip\_children}. This will only
|
|
keep effect for a single increment or decrement of the
|
|
iterator. Finally, whether or not an iterator is actually pointing at
|
|
a node (i.e.~is not an ``end'' iterator) can be tested using the
|
|
\member{is\_valid(iterator)} member of the tree class.
|
|
|
|
\end{sectionunit}
|
|
\end{sectionunit}
|
|
|
|
\begin{sectionunit}
|
|
\title{Basic operations}
|
|
\maketitle
|
|
\begin{description}
|
|
\item[Initialising] There are two nontrivial constructors. One which takes
|
|
a single node element as argument. It constructs a tree with this node
|
|
begin the sole node in the head (in other words, it is a combination
|
|
of a trivial constructor together with a \member{set\_head} call).
|
|
The other non-trivial constructor takes an iterator, and copies the
|
|
subtree starting at that node into the newly created tree (useful for
|
|
constructing new tree objects given by subtrees of existing trees).
|
|
|
|
\item[Tree traversal] Besides the \member{operator++} and
|
|
\member{operator--} members for step-wise traversal through the tree,
|
|
it is also possible to use the \member{operator+=} and \member{operator-=}
|
|
member functions to make more than one step at the same time (though
|
|
these are linear time, not amortized constant). The result of stepping
|
|
beyond the end of the tree or stepping beyond the end of a sibling
|
|
range (for sibling iterators) is undefined.
|
|
|
|
The parent of a given node can be reached by calling the \member{parent}
|
|
member of the tree object, giving it an iterator pointing to the node.
|
|
|
|
If you know the number of children of a given node, you can get direct
|
|
access to the $n$th child by using the \member{child} member
|
|
function. Note that the value of the index is not checked and should
|
|
therefore always be valid.
|
|
|
|
\item[Appending child nodes] Nodes can be added as children of a given
|
|
node using the \member{append\_child} member function.
|
|
|
|
\item[Inserting nodes] Nodes can be inserted at the same depth as a
|
|
given other node using the \member{insert} and \member{insert\_after}
|
|
members functions. This is also how you insert the first node into a
|
|
tree.
|
|
\end{description}
|
|
\end{sectionunit}
|
|
|
|
\begin{sectionunit}
|
|
\title{Other algorithms}
|
|
\maketitle
|
|
\begin{sectionunit}
|
|
\title{Non-mutating algorithms}
|
|
\maketitle
|
|
\begin{description}
|
|
\item[Counting nodes] The total number of nodes of a tree can be
|
|
obtained using the \member{size} member function, while the number of
|
|
children of a given node can be obtained with a call to
|
|
\member{number\_of\_children(iterator)}. Similarly, the number of
|
|
nodes at a given depth (the number of siblings of a given node) can be
|
|
obtained using the \member{number\_of\_siblings} member function.
|
|
\item[Determining depth] The \member{depth()} member function returns the
|
|
distance of a node to the root.
|
|
\item[Accessing siblings by their index] See the next item.
|
|
\item[Determining index in a sibling range] In order to determine the
|
|
index of a node in the range of siblings to which it belongs, use the
|
|
\member{index(sibling\_iterator)} member function. The first sibling node
|
|
has index 0. The reverse of this function (obtaining a sibling node
|
|
given its index in the range of siblings) is called
|
|
\member{child(const iterator\_base\&, unsigned int)}.
|
|
\item[Comparing trees] While the STL \member{equal} algorithm can be used
|
|
to compare the values of the nodes in two different trees, it does not
|
|
know about the structure of the tree. If you want the comparison to
|
|
take this into account, use the \member{equal(iterator, iterator,
|
|
iterator, BinaryPredicate)} call of the tree class. As an addition to
|
|
the STL algorithm, the length of the first range does not have to be
|
|
equal to the length of the range pointed to by the second iterator.
|
|
|
|
There is also an \member{equal\_subtree} algorithm which takes only
|
|
two iterators, pointing to the (single-node) heads of two
|
|
subtrees.
|
|
\end{description}
|
|
\end{sectionunit}
|
|
|
|
\begin{sectionunit}
|
|
\title{Mutating algorithms}
|
|
\maketitle
|
|
\begin{description}
|
|
\item[Erasing nodes and subtrees] In order to remove a node including
|
|
its children from the tree, use the \member{erase(iterator)} call. If you
|
|
just want to erase the children, but not the node itself, use the
|
|
\member{erase\_children(iterator)} call.
|
|
|
|
\item[Replacing individual nodes or subtrees]
|
|
|
|
\item[Flattening subtrees] The procedure of moving all children of a
|
|
given node to be siblings of that node is called ``flattening''; it
|
|
acts as
|
|
\begin{equation*}
|
|
\vcenter{\offinterlineskip
|
|
\halign{&#\mystrut\hfil\cr
|
|
apple \hw\cr
|
|
\T banana\cr
|
|
\V \T pear \cr
|
|
\V \T strawberry \cr
|
|
\V \L cherry \cr
|
|
\L grape\cr}}\quad\rightarrow\quad
|
|
\vcenter{\offinterlineskip
|
|
\halign{&#\mystrut\hfil\cr
|
|
apple \hw\cr
|
|
\T banana\cr
|
|
\T pear \cr
|
|
\T strawberry \cr
|
|
\T cherry \cr
|
|
\L grape\cr}}
|
|
\end{equation*}
|
|
% \begin{screen}
|
|
% apple apple
|
|
% banana banana
|
|
% pear -> pear
|
|
% strawberry strawberry
|
|
% cherry cherry
|
|
% grape grape
|
|
% \end{screen}
|
|
when the tree is flattened at the ``banana'' node.
|
|
|
|
\item[Moving or exchanging subtrees] Simple exchange of one sibling node with the
|
|
next one is done through the member function \member{swap(sibling\_iterator)}. The
|
|
iterator remains valid and remains pointing to the moved subtree.
|
|
|
|
More complicated move operations are the \member{move\_ontop},
|
|
\member{move\_before} and \member{move\_after} ones. These all take
|
|
two iterators, a source and a target. The member
|
|
\member{move\_ontop(target, source)} removes the `target' node and
|
|
all its children, and replaces it with the `source' node and its
|
|
children. The `source' subtree is removed from its original location.
|
|
The other two move members do a similar thing, differing only in the
|
|
node which is to be replaced.
|
|
|
|
\item[Extracting subtrees] You can create a new tree object
|
|
filled with the data of a subtree of the original tree. This is
|
|
analogous to the extraction of a substring of a string. The relevant
|
|
member function is \member{subtree(sibling\_iterator,
|
|
sibling\_iterator)} which takes a range of siblings as argument.
|
|
There is also a slight variation of this member, which does not return
|
|
a tree object but instead populates one that is passed as an argument
|
|
(useful if you want to call this on a tree object subclassed from
|
|
{\tt tree<T>}.
|
|
|
|
\item[Sorting] The standard STL sort algorithm is not very useful for
|
|
trees, because it only exchanges values, not nodes. Applying it to a
|
|
tree would mean that the structure of the tree remains unmodified,
|
|
only node values get moved around (not their subtrees).
|
|
|
|
Therefore, the {\tt tree} class has its own sort member. It comes in
|
|
two forms, just like the STL sort, namely
|
|
\begin{screen}
|
|
void sort(sibling_iterator from, sibling_iterator to, bool deep=false);
|
|
|
|
template<class StrictWeakOrdering>
|
|
void sort(sibling_iterator from, sibling_iterator to,
|
|
StrictWeakOrdering comp, bool deep=false);
|
|
\end{screen}
|
|
The result of a call to either of these is that the nodes in the range
|
|
described by the two iterators get sorted. If the boolean {\tt deep}
|
|
is true, the subtrees of all these nodes will get sorted as well (and
|
|
so one can sort the entire tree in one call). As in the STL, you can
|
|
use the second form of this function to pass your own comparison
|
|
class.
|
|
|
|
If the nodes to which the two iterators point are not in the same
|
|
sibling range (i.e.~not at the same depth in the tree), the result is undefined.
|
|
|
|
\item[Merging] One way in which one might think of indicating the
|
|
position where new nodes are to be inserted, is to give the path that
|
|
leads to the insertion point. For instance, given the tree
|
|
\begin{equation*}
|
|
\vcenter{\offinterlineskip
|
|
\halign{&#\mystrut\hfil\cr
|
|
apple \hw\cr
|
|
\T banana\cr
|
|
\V \T pear \cr
|
|
\V \T strawberry \cr
|
|
\V \L cherry \cr
|
|
\L grape\cr}}
|
|
\end{equation*}
|
|
one could imagine using the sub-tree
|
|
\begin{equation*}
|
|
\vcenter{\offinterlineskip
|
|
\halign{&#\mystrut\hfil\cr
|
|
apple \hw\cr
|
|
\L banana\cr
|
|
\N \T coconut \cr
|
|
\N \L raspberry \cr}}
|
|
\end{equation*}
|
|
to indicate that the nodes ``coconut'' and ``raspberry'' are to be
|
|
inserted as new children of the ``banana'' node. In {\tt tree.hh} this
|
|
process is called \emph{tree merging}. It can do the simple addition
|
|
of children as above, but actually handles the generic case too: as
|
|
an example consider the merge
|
|
\begin{equation*}
|
|
\text{\tt merge}\left[
|
|
\vcenter{\offinterlineskip
|
|
\halign{&#\mystrut\hfil\cr
|
|
apple \hw\cr
|
|
\T banana\cr
|
|
\V \T pear \cr
|
|
\V \T strawberry \cr
|
|
\V \L cherry \cr
|
|
\T grape\cr
|
|
blueberry \cr}}\quad, \quad
|
|
\vcenter{\offinterlineskip
|
|
\halign{&#\mystrut\hfil\cr
|
|
apple \hw\cr
|
|
\T banana\cr
|
|
\V \T coconut \cr
|
|
\V \L raspberry \cr
|
|
\T tangerine \cr
|
|
\V \L plum\cr
|
|
blueberry \cr
|
|
\N \L orange \cr}}\right]\quad\rightarrow\quad
|
|
\vcenter{\offinterlineskip
|
|
\halign{&#\mystrut\hfil\cr
|
|
apple \hw\cr
|
|
\T banana\cr
|
|
\V \T pear\cr
|
|
\V \T strawberry\cr
|
|
\V \T cherry\cr
|
|
\V \T coconut \cr
|
|
\V \L raspberry \cr
|
|
\T grape\cr
|
|
\T tangerine \cr
|
|
\V \L plum\cr
|
|
blueberry \cr
|
|
\N \L orange \cr}}
|
|
\end{equation*}
|
|
As is clear from the above, the arguments to \member{merge} are two
|
|
sibling ranges.
|
|
\end{description}
|
|
\end{sectionunit}
|
|
\end{sectionunit}
|
|
|
|
\printindex
|
|
\end{document}
|