
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


\spadtype{BinarySearchTree(R)} is the domain of binary trees with
\index{tree!binary search}
elements of type \spad{R}, ordered across the nodes of the tree.
\index{binary search tree}
A non-empty binary search tree has a value
of type \spad{R}, and \spadfun{right} and \spadfun{left}
binary search subtrees.
If a subtree is empty, it is displayed as a period (``.'').

\xtc{
Define a list of values to be placed across the tree.
The resulting tree has \spad{8} at the root;
all other elements are in the left subtree.
}{
\spadcommand{lv := [8,3,5,4,6,2,1,5,7]\bound{lv}}
}
\xtc{
A convenient way to create a binary search tree is to
apply the operation \spadfun{binarySearchTree} to a list of elements.
}{
\spadcommand{t := binarySearchTree lv\free{lv}\bound{t}}
}
\xtc{
Another approach is to first create an empty binary search tree of integers.
}{
\spadcommand{emptybst := empty()\$BSTREE(INT)\bound{e}}
}
\xtc{
Insert the value \spad{8}.
This establishes \spad{8} as the root of the binary search tree.
Values inserted later that are less than \spad{8} get stored in
the \spadfun{left} subtree, others in the \spadfun{right} subtree.
}{
\spadcommand{t1 := insert!(8,emptybst)\free{e}\bound{t1}}
}
\xtc{
Insert the value \spad{3}. This number becomes the root of the
\spadfun{left} subtree of \spad{t1}.
For optimal retrieval, it is thus important to insert the
middle elements first.
}{
\spadcommand{insert!(3,t1)\free{t1}}
}
\xtc{
We go back to the original tree \spad{t}.
The leaves of the binary search tree are those which have empty
\spadfun{left} and \spadfun{right} subtrees.
}{
\spadcommand{leaves t\free{t}}
}
\xtc{
The operation
\spadfun{split}\spad{(k,t)} returns a \spadgloss{record} containing
the two subtrees: one with all elements ``less'' than \spad{k},
another with elements ``greater'' than \spad{k}.
}{
\spadcommand{split(3,t)\free{t}}
}
\xtc{
Define \userfun{insertRoot} to insert new elements by
creating a new node.
}{
\spadcommand{insertRoot: (INT,BSTREE INT) -> BSTREE INT\bound{x}}
}
\xtc{
The new node puts the inserted value between its
``less'' tree and ``greater'' tree.
}{
\begin{spadsrc}[\bound{x1}\free{x}]
insertRoot(x, t) ==
    a := split(x, t)
    node(a.less, x, a.greater)
\end{spadsrc}
}
\xtc{
Function \userfun{buildFromRoot} builds
a binary search tree from a list of elements \spad{ls}
and the empty tree \spad{emptybst}.
}{
\spadcommand{buildFromRoot ls == reduce(insertRoot,ls,emptybst)\bound{x2}\free{x1 e}}
}
\xtc{
Apply this to the reverse of the list \spad{lv}.
}{
\spadcommand{rt := buildFromRoot reverse lv\bound{rt}\free{lv x2}}
}
\xtc{
Have \Language{} check that these are equal.
}{
\spadcommand{(t = rt)@Boolean\free{rt t}}
}
