\chapter{Binary trees}
\label{chap-binary-trees}

\section{Classes}

\Defclass {node}

This class is the base class for all node types in binary trees.

\Defclass {simple-node}

This class is a subclass of the class \texttt{node}.  It does not add
any slots, and is only meant for client code to be able to distinguish
between a node with a parent and a node without one.

\Defclass {node-with-parent}

This class is a subclass of the class \texttt{node}.  It adds a slot
for storing a reference to the parent node in a binary tree.

\section{Basic operations}

\Defgeneric {left} {node}

Given a node, return the left child of that node.  The value returned
by this function may be either an instance of (a subclass of) the
class \texttt{node} or \texttt{nil} if the left child of \textit{node}
is the empty tree.

\Defgeneric {(setf left)} {new-left node}

Given a tree \texttt{new-left} and a node \texttt{node}, set the left
child of \texttt{node} to \texttt{new-left}.  The argument
\texttt{new-left} can be either a node or \texttt{nil}.

An \texttt{:after} method is provided with both parameters specialized
to\\ \texttt{node-with-parent}.  This method calls \texttt{(setf
  parent)} with \texttt{node} and \texttt{new-left} as arguments.

\Defgeneric {right} {node}

Given a node, return the right child of that node.  The value returned
by this function may be either an instance of (a subclass of) the
class \texttt{node} or \texttt{nil} if the right child of
\textit{node} is the empty tree.

\Defgeneric {(setf right)} {new-right node}

Given a tree \texttt{new-right} and a node \texttt{node}, set the
right child of \texttt{node} to \texttt{new-right}.  The argument
\texttt{new-right} can be either a node or \texttt{nil}.

An \texttt{:after} method is provided with both parameters specialized
to\\ \texttt{node-with-parent}.  This method calls \texttt{(setf
  parent)} with \texttt{node} and \texttt{new-right} as arguments.

\Defgeneric {parent} {node}

Given a node, return the parent of that node.  If \texttt{node} is not
an instance of (a subclass of) \texttt{node-with-parent}, then an
error is signaled.  Otherwise, the value returned by this function may
be either an instance of (a subclass of) the class
\texttt{node-with-parent}, or \texttt{nil} indicating that
\texttt{node} is the root of a tree.

\Defgeneric {(setf parent)} {new-parent node}

Given a tree \texttt{new-parent} and a node \texttt{node}, set the
parent of \texttt{node} to \texttt{new-parent}.  If \texttt{node} is
not an instance of (a subclass of) \texttt{node-with-parent}, then an
error is signaled.  The argument \texttt{new-parent} can be either an
instance of (a subclass of) \texttt{node-with-parent}, or \texttt{nil}
indicating that \texttt{node} is the root of a tree.

\section{Traversal}

\sysname{} contains two generic functions for traversing binary trees,
both with the same signature and the same result.

\Defgeneric {recursive-traversal} {tree pre in post}

\Defgeneric {iterative-traversal} {tree pre in post}

Both these functions implement a depth-first left-to-right traversal
of \texttt{tree}, which may be an instance of (a subclass of)
\texttt{node}, or \texttt{nil}.

Each of the parameters \texttt{pre}, \texttt{in}, and \texttt{post},
is a designator of a function of one argument, a node.  Each function
is called with the root $N$ (a node) of some subtree $T$.  The
function \texttt{pre} is called when $T$ is about to be visited.  The
function \texttt{in} is called after the \emph{left subtree} of $T$
has already been visited.  The function \texttt{post} is called after
the \emph{right subtree} of $T$ has already been visited.

The two functions differ in how the traversal is accomplished.

The function \texttt{recursive-traversal} uses \emph{recursion} for
the traversal.  This technique is very fast, but the disadvantage is
that is requires stack space proportional to the depth of the tree.
If the tree is large and skinny, the available stack space will very
likely be exhausted in most \commonlisp{} implementations.

The function \texttt{iterative-traversal} uses \emph{iteration} for
the traversal.  When the tree consists of instance of (subclasses of)
\texttt{node-with-parent}, the \texttt{parent} slot is used to back up
after a subtree has been completely traversed.  Therefore only a
small, constant amount of additional space is required.  When the tree
consists of instance of (subclasses of) \texttt{simple-node}, this
function allocates a \emph{list} to hold parent nodes in progress of
being traversed.  For that reason, this function uses additional space
proportional to the depth of the tree.

\section{Rotation}
\label{sec-rotation}

Rotation is a fundamental operation on nodes of a binary tree.  It is
used in a variety of special cases of binary trees, in particular in
\emph{AVL trees} \cite{Adelson-Velskii_Landis_1962}, \emph{red-black
  trees} \cite{Guibas:1978:DFB:1382432.1382565}, and \emph{splay
  trees} \cite{Sleator:1985:SBS:3828.3835}.

Rotation is important because, although it changes the structure of
the tree, it \emph{preserves the in-order depth-first traversal}.
Since this order is what defines the contents of the tree when it is
used either as a \emph{dictionary} or to represent a \emph{sequence},
rotation can be applied without changing the meaning of what it
contains.

Rotation is illustrated in \refFig{fig-rotation}.

\begin{figure}
\begin{center}
\inputfig{fig-rotation.pdf_t}
\end{center}
\caption{\label{fig-rotation}
Rotation.}
\end{figure}

Two symmetrical operations are provided, namely \emph{left rotation}
and \emph{right rotation}.  In \refFig{fig-rotation}, a left rotation
transforms the tree in the right-hand side of the figure to the tree
in the left-hand side of the figure.  Conversely, a right rotation
transforms the tree in the left-hand side of the figure to the tree
in the right-hand side of the figure.

\section{Splaying}
\label{sec-splaying}

Splaying is fundamental operation of \emph{splay trees}
\cite{Sleator:1985:SBS:3828.3835}.  It is defined in terms of
rotations \seesec{sec-rotation}.

The splay operation can be applied to any \emph{node} in the tree.
When the splay operation terminates, the node to which the splay
operation was applied will be at the root of the tree.  The node is
migrated to the root through a sequence of well-defined \emph{splay
  steps}.  Each splay step consists of one or two rotations.  Which
rotations to apply depends on the constellations between the node to
be splayed, its parent, and its grandparent.

There are three fundamentally different types of splay-step
operations, traditionally called \emph{zig}, \emph{zig-zig}, and
\emph{zig-zag}, respectively.  Furthermore, each type of operation has
two constellations that are mirror images of each other, for a total
of six types of splay steps.

\refFig{fig-splay-zig-1} illustrates the first case of a \emph{zig}
splay-step operation.  The node to be splayed is labeled \textsf{a}.

\begin{figure}
\begin{center}
\inputfig{fig-splay-zig-1.pdf_t}
\end{center}
\caption{\label{fig-splay-zig-1}
Splaying with a zig step, case 1.}
\end{figure}

As \refFig{fig-splay-zig-1} shows, this splay-step operation applies
when the parent of the node to be splayed (labeled \textsf{b} in
\refFig{fig-splay-zig-1}) is the root of the entire tree, and the node
to be splayed is the \emph{left} child of its parent.  For this
constellation, the splay step for the node labeled \textsf{a} is the
same as a \emph{right rotation} of the node labeled \textsf{b}.

The splay step of the constellation in \refFig{fig-splay-zig-1} is
handled by the generic function
\texttt{splay-step-with-right-parent-and-grandparent}, specifically by
the method specialized to a grandparent of class \texttt{null}.

\refFig{fig-splay-zig-2} illustrates the second case of a \emph{zig}
splay-step operation.  Again, the node to be splayed is labeled
\textsf{a}.

\begin{figure}
\begin{center}
\inputfig{fig-splay-zig-2.pdf_t}
\end{center}
\caption{\label{fig-splay-zig-2}
Splaying with a zig step, case 2.}
\end{figure}

As \refFig{fig-splay-zig-2} shows, this splay-step operation applies
when the parent of the node to be splayed (labeled \textsf{b} in
\refFig{fig-splay-zig-2}) is the root of the entire tree, and the node
to be splayed is the \emph{right} child of its parent.  For this
constellation, the splay step for the node labeled \textsf{a} is the
same as a \emph{left rotation} of the node labeled \textsf{b}.

The splay step of the constellation in \refFig{fig-splay-zig-2} is
handled by the generic function
\texttt{splay-step-with-left-parent-and-grandparent}, specifically by
the method specialized to a grandparent of class \texttt{null}.

\refFig{fig-splay-zig-zig-1} illustrates the first case of a
\emph{zig-zig} splay-step operation.  Again, the node to be splayed is
labeled \textsf{a}.

\begin{figure}
\begin{center}
\inputfig{fig-splay-zig-zig-1.pdf_t}
\end{center}
\caption{\label{fig-splay-zig-zig-1}
Splaying with a zig-zig step, case 1.}
\end{figure}

As \refFig{fig-splay-zig-zig-1} shows, this splay-step operation
applies when the node to be splayed is the \emph{left} child of its
parent (labeled \textsf{b} in \refFig{fig-splay-zig-zig-1}) and the
parent is also the \emph{left} child of its parent.  For this
constellation, the splay step for the node labeled \textsf{a} consists
of two right rotations.  The first rotation applies to the grandparent
(labeled \textsf{c} in \refFig{fig-splay-zig-zig-1}) of the node to be
splayed, and the second rotation applies to the parent of the node to
be splayed.

The splay step of the constellation in \refFig{fig-splay-zig-zig-1} is
handled by the generic function
\texttt{splay-step-with-right-parent-and-right-grandparent}.

\refFig{fig-splay-zig-zig-2} illustrates the second case of a
\emph{zig-zig} splay-step operation.  Again, the node to be splayed is
labeled \textsf{a}.

\begin{figure}
\begin{center}
\inputfig{fig-splay-zig-zig-2.pdf_t}
\end{center}
\caption{\label{fig-splay-zig-zig-2}
Splaying with a zig-zig step, case 2.}
\end{figure}

As \refFig{fig-splay-zig-zig-2} shows, this splay-step operation
applies when the node to be splayed is the \emph{right} child of its
parent (labeled \textsf{b} in \refFig{fig-splay-zig-zig-2}) and the
parent is also the \emph{right} child of its parent.  For this
constellation, the splay step for the node labeled \textsf{a} consists
of two left rotations.  The first rotation applies to the grandparent
(labeled \textsf{c} in \refFig{fig-splay-zig-zig-2}) of the node to be
splayed, and the second rotation applies to the parent of the node to
be splayed.

The splay step of the constellation in \refFig{fig-splay-zig-zig-2} is
handled by the generic function
\texttt{splay-step-with-left-parent-and-left-grandparent}.

\refFig{fig-splay-zig-zag-1} illustrates the first case of a
\emph{zig-zag} splay-step operation.  Again, the node to be splayed is
labeled \textsf{a}.

\begin{figure}
\begin{center}
\inputfig{fig-splay-zig-zag-1.pdf_t}
\end{center}
\caption{\label{fig-splay-zig-zag-1}
Splaying with a zig-zag step, case 1.}
\end{figure}

As \refFig{fig-splay-zig-zag-1} shows, this splay-step operation
applies when the node to be splayed is the \emph{right} child of its
parent (labeled \textsf{b} in \refFig{fig-splay-zig-zag-1}) and the
parent is the \emph{left} child of its parent.  For this
constellation, the splay step for the node labeled \textsf{a} consists
of one left rotation followed by one right rotation.  The first
rotation applies to the parent of the node to be splayed, and the
second rotation applies to the grandparent (labeled \textsf{c} in
\refFig{fig-splay-zig-zag-1}) of the node to be splayed.

The splay step of the constellation in \refFig{fig-splay-zig-zag-1} is
handled by the generic function
\texttt{splay-step-with-left-parent-and-right-grandparent}.

\refFig{fig-splay-zig-zag-2} illustrates the second case of a
\emph{zig-zag} splay-step operation.  Again, the node to be splayed is
labeled \textsf{a}.

\begin{figure}
\begin{center}
\inputfig{fig-splay-zig-zag-2.pdf_t}
\end{center}
\caption{\label{fig-splay-zig-zag-2}
Splaying with a zig-zag step, case 2.}
\end{figure}

As \refFig{fig-splay-zig-zag-2} shows, this splay-step operation
applies when the node to be splayed is the \emph{left} child of its
parent (labeled \textsf{b} in \refFig{fig-splay-zig-zag-2}) and the
parent is the \emph{right} child of its parent.  For this
constellation, the splay step for the node labeled \textsf{a} consists
of one right rotation followed by one left rotation.  The first
rotation applies to the parent of the node to be splayed, and the
second rotation applies to the grandparent (labeled \textsf{c} in
\refFig{fig-splay-zig-zag-2}) of the node to be splayed.

The splay step of the constellation in \refFig{fig-splay-zig-zag-2} is
handled by the generic function
\texttt{splay-step-with-right-parent-and-left-grandparent}.

\Defgeneric {splay} {node}

This function takes an instance of (a subclass of)
\texttt{node-with-parent} and splays it so that it becomes the root of
the entire tree.  The function \texttt{splay} returns its argument
\texttt{node}.

\Defmethod {splay} {(node \texttt{node-with-parent})}

This method repeatedly invokes the generic function
\texttt{splay-step} passing \texttt{node} as an argument until
\texttt{node} is the root of the entire tree, which is determined by
the fact that its parent is \texttt{nil}.

Client code may define methods on \texttt{splay}, specialized to
strict subclasses of \texttt{node-with-parents}.

\Defgeneric {splay-step} {node}

\Defmethod {splay-step} {(node \texttt{node-with-parent})}

This method calls \texttt{splay-step-with-parent}, passing it
\texttt{node} and the parent of \texttt{node} as arguments.

\Defgeneric {splay-step-with-parent} {node parent}

\Defmethod {splay-step-with-parent}
{(node \texttt{node-with-parent}) (parent \texttt{null})}

This method does nothing and returns \texttt{node}.

\Defmethod {splay-step-with-parent}\\
{(node \texttt{node-with-parent}) (parent \texttt{node-with-parent})}

This method checks whether \texttt{node} is the left or the right child
of \texttt{parent}.  If \texttt{node} is the left child of
\texttt{parent}, it calls \texttt{splay-step-with-right-parent},
passing it \texttt{node} and \texttt{parent} as arguments.  If
\texttt{node} is the right child of \texttt{parent}, it calls
\texttt{splay-step-with-left-parent}, passing it \texttt{node} and
\texttt{parent} as arguments.

\Defgeneric {splay-step-with-right-parent} {node parent}

\Defmethod {splay-step-with-right-parent}\\
{(node \texttt{node-with-parent}) (parent \texttt{node-with-parent})}

This method calls \texttt{splay-step-with-right-parent-and-grandparent},
passing it \texttt{node}, \texttt{parent} and the parent of
\texttt{parent} as arguments.

\Defgeneric {splay-step-with-left-parent} {node parent}

\Defmethod {splay-step-with-left-parent}\\
{(node \texttt{node-with-parent}) (parent \texttt{node-with-parent})}

This method calls \texttt{splay-step-with-left-parent-and-grandparent},
passing it \texttt{node}, \texttt{parent} and the parent of
\texttt{parent} as arguments.

\Defgeneric {splay-step-with-right-parent-and-grandparent}\\
{node parent grandparent}

This function handles splay steps where \texttt{node} is the left
child of \texttt{parent}, and \texttt{grandparent} is either a node or
\texttt{nil}.

\Defmethod {splay-step-with-right-parent-and-grandparent}\\
{(node \texttt{node-with-parent})\\
 (parent \texttt{node-with-parent})\\
 (grandparent \texttt{node-with-parent})}

This method calls
\texttt{splay-step-with-right-parent-and-right-grandparent} or
\texttt{splay-step-with-right-parent-and-left-grandparent} according
to whether \texttt{parent} is the left or the right child of
\texttt{grandparent}.

\Defmethod {splay-step-with-right-parent-and-grandparent}\\
{(node \texttt{node-with-parent})\\
 (parent \texttt{node-with-parent})\\
 (grandparent \texttt{null})}

This method handles a splay step when the constellation of the node is
the one illustrated by \refFig{fig-splay-zig-1}.

\Defgeneric {splay-step-with-left-parent-and-grandparent}\\
{node parent grandparent}

This function handles splay steps where \texttt{node} is the right
child of \texttt{parent}, and \texttt{grandparent} is either a node or
\texttt{nil}.

\Defmethod {splay-step-with-left-parent-and-grandparent}\\
{(node \texttt{node-with-parent})\\
 (parent \texttt{node-with-parent})\\
 (grandparent \texttt{node-with-parent})}

This method calls
\texttt{splay-step-with-left-parent-and-right-grandparent} or
\texttt{splay-step-with-left-parent-and-left-grandparent} according
to whether \texttt{parent} is the left or the right child of
\texttt{grandparent}.

\Defmethod {splay-step-with-left-parent-and-grandparent}\\
{(node \texttt{node-with-parent})\\
 (parent \texttt{node-with-parent})\\
 (grandparent \texttt{null})}

This method handles a splay step when the constellation of the node is
the one illustrated by \refFig{fig-splay-zig-2}.

\Defgeneric {splay-step-with-right-parent-and-right-grandparent}\\
{node parent grandparent}

This generic function handles a splay step when the constellation of
the node is the one illustrated by \refFig{fig-splay-zig-zig-1}.

\Defgeneric {splay-step-with-left-parent-and-left-grandparent}\\
{node parent grandparent}

This generic function handles a splay step when the constellation of
the node is the one illustrated by \refFig{fig-splay-zig-zig-2}.

\Defgeneric {splay-step-with-left-parent-and-right-grandparent}\\
{node parent grandparent}

This generic function handles a splay step when the constellation of
the node is the one illustrated by \refFig{fig-splay-zig-zag-1}.

\Defgeneric {splay-step-with-right-parent-and-left-grandparent}\\
{node parent grandparent}

This generic function handles a splay step when the constellation of
the node is the one illustrated by \refFig{fig-splay-zig-zag-2}.
