%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%  
%%  sort_vector.tex       LiDIA documentation
%%  
%%  This file contains the documentation of the vector classes
%%  
%%  Copyright   (c)   1995   by  LiDIA-Group
%%  
%%  Authors: Frank Lehmann, Markus Maurer
%%           Patrick Theobald, Stefan Neis
%%

\def\basev{\BF{base\_vector\TEMPL{T}} }
\def\sortv{\BF{sort\_vector\TEMPL{T}} }

\markright{\BF{sort\_vector}}
\begin{lidia_man}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NAME
\sortv \DOTFILL vectors with sort functions

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\ABSTRACT
Class \sortv contains \basev as a base class. It supports any member and friend
function of that class. Additionally it provides functions 
for sorting and searching, inserting and deleting. \BF{T} can be either a 
built-in type or a class.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\DESCRIPTION
A variable of type \sortv contains the same components as a variable of type
\basev. In addition there is a character \BF{sort\_dir} and a function pointer 
\BF{*el\_cmp}.

A vector of type \sortv can be sorted according to a certain sort direction. 
This class provides two standard directions \BF{SORT\_VECTOR\_UP} and 
\BF{SORT\_VECTOR\_DOWN} to sort the elements of a vector in ascending 
or descending order, respectively. Furthermore, specific compare functions 
may be used to define a relation of elements of type \BF{T}. These functions 
define a new sort relation for a vector.

Any compare function used must have a prototye like
\begin{center}
\TT{int cmp ( const T \& a , const T \& b ) }.
\end{center}
The data type for pointers to functions of that type will be called 
\BF{CMP\_FUNC} in the sequel. The return value of a comparison shall be as 
follows:
\begin{center}
\begin{tabular}{rl}
\MATH{ < 0 } & if \TT{(a,b)} is in correct order \\
\MATH{ = 0 } & if \TT{a, b}  are identified      \\
\MATH{ > 0 } & if \TT{(a,b)} is in inverted order
\end{tabular}
\end{center}

Any vector \MATH{v} of type \sortv contains a default sort direction 
according to which it will be sorted if the function \TT{v.sort()} is applied.
This default sort direction will be set to SORT\_VECTOR\_UP by any constructor in 
this class; i.e. vector \MATH{v} will be sorted in ascending order by default.
This default value may later be changed for a vector \MATH{v} by using the 
function \TT{v.set\_sort\_direction()}.

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\CONS
Each of the following constructors can get an additional parameter (FIXED or EXPAND) 
to indicate the mode of the \BF{sort\_vector}.

\fcode{ct}{\sortv}{}
{constructs a vector with capacity 0.}

\fcode{ct}{\sortv}{lidia\_size\_t c}
{constructs a vector with capacity \MATH{c} initialized with values generated 
by the default constructor for type \BF{T}.}

\fcode{ct}{\sortv}{lidia\_size\_t c\k lidia\_size\_t s}
{constructs a vector with capacity \MATH{c} and size \MATH{s} initialized with 
values generated by the default constructor for type \BF{T}.}

\fcode{ct}{\sortv}{const \sortv \& w}
{constructs a vector with capacity \MATH{w.size} initialized with the elements 
of \MATH{w}.}

\fcode{ct}{\sortv}{const T *a\k lidia\_size\_t l}
{constructs a vector with capacity \MATH{l} and size \MATH{l} initialized with 
the first \MATH{l} elements of the array \MATH{a}.}

\fcode{dt}{\SIM \sortv}{}{}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\STITLE{Sort\_direction}
\cfcode{char}{v.sort\_direction}{}
{returns the default sort direction of vector \MATH{v}. The return value 
will be one of the predefined constants SORT\_VECTOR\_UP, SORT\_VECTOR\_UP 
or SORT\_VECTOR\_CMP. The latter indicates that the sort direction of 
\MATH{v} has been set to a certain compare function.}

\cfcode{char}{v.get\_sort\_direction}{}
{returns the default sort direction of vector \MATH{v}. The return value 
will be one of the predefined constants SORT\_VECTOR\_UP, SORT\_VECTOR\_DOWN 
or SORT\_VECTOR\_CMP. The latter indicates that the sort direction of 
\MATH{v} has been set to a certain compare function.}

\fcode{void}{v.set\_sort\_direction}{char dir}
{sets the default sort--direction for \MATH{v} to \MATH{dir}. The value of 
\MATH{dir} may be either one of the two predefined constants SORT\_VECTOR\_UP or 
SORT\_VECTOR\_DOWN. If \MATH{dir} is invalid, the standard sort direction of 
\MATH{v} will be left unchanged and the \TT{lidia\_error\_handler} will be
invoked.}

\fcode{void}{v.set\_sort\_direction}{int (*cmp) (const T \& a, const T \& b)}
{sets the default sort direction for \MATH{v} in a way that function 
\TT{cmp()} will be used to compare the entries of \MATH{v}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\STITLE{Sort Functions}
Class \TT{\sortv} provides a sort function, which allows to sort a vector in 
various ways. There are three different prototypes for this sort routine that 
allow a variety of calls of the functions. Some of the parameters of function 
\TT{sort()} can obtain default values if they are not specified in a call.
These default values will be indicated by ''DEF''.

It is possible to restrict the sort routine to a part of a vector by 
explicitly passing on the starting and ending indices to this function. Whenever these 
values are invalid, the \TT{lidia\_error\_handler} will be invoked.

\fcode{void}{v.sort}{char sort\_dir = DEF\k int l = DEF\k int r = DEF}
{sorts the elements \MATH{v[l],\LDOTS,v[r]} according to the direction 
\MATH{v.sort\_dir}. Any other element in \MATH{v} will remain in its position. 
The value of \MATH{v.sort\_dir} has to be either one of the two constants 
SORT\_VECTOR\_UP or SORT\_VECTOR\_DOWN. If it differs from these values, 
the \TT{lidia\_error\_handler} will be invoked. If no values for \MATH{l} and 
\MATH{r} are given, the entire vector will be sorted. If \MATH{v.sort\_dir} is 
not specified either, the default sort direction for \MATH{v} will be 
used.}

\fcode{void}{v.sort}{CMP\_FUNC cmp\k int l = DEF\k int r = DEF}
{sorts the elements \MATH{v[l],...,v[r]} according to the compare function 
\TT{(*cmp)()}. Any other element in \MATH{v} will remain in its position. 
The function \TT{(*cmp)()} must be of correct type CMP\_FUNC. If no values for 
\MATH{l} and \MATH{r} are given, the entire vector will be sorted.}

\fcode{void}{v.sort}{int l\k int r}
{sorts the elements \MATH{v[l],\LDOTS,v[r]} according to the default 
sort direction of \MATH{v}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\STITLE{Search Functions}
As a second feature the class \sortv provides functions for linear and binary 
search in a vector.

\cfcode{bool}{v.linear\_search}{const T \&x\k int \&pos}
{searches \MATH{x} in vector \MATH{v}. If \MATH{x} can be found, this function 
will return \TRUE\ and \MATH{pos} will hold the index of its first occurence 
in \MATH{v}. Otherwise, the return value will be \FALSE.}

The function \TT{bin\_search()} searches for an element \MATH{x} in a vector using 
a binary search strategy. (Beware of the fact, that this routine can work 
successfully only if the elements of the vector are sorted in an appropriate 
way.) Its return value will be \TRUE\ if it succeeds, and \FALSE\ otherwise.
If \MATH{x} can be found in a vector, \MATH{pos} will hold the index of its 
\BF{first} occurence or else, \MATH{pos} will be the index, where \MATH{x} 
can be inserted according to the corresponding sort direction.

Some of the parameters of function \TT{bin\_search()} can obtain default 
values if they are not specified in a call. These default values will be 
indicated by ''DEF''.

It is possible to restrict the search to a part of a vector by explicitly 
passing on the starting and ending indices to this function. Whenever these values are 
invalid, the \TT{lidia\_error\_handler} will be invoked.

\cfcode{bool}{v.bin\_search}{const T \&x\k int \&pos\k char sort\_dir=DEF\k int l=DEF\k int r=DEF}
{searches for \MATH{x} among the elements \MATH{v[l],\LDOTS,v[r]} using 
the sort direction \MATH{v.sort\_dir}. Its value must be either of the two 
constants SORT\_VECTOR\_UP or SORT\_VECTOR\_DOWN. If \MATH{v.sort\_dir} 
differs from these values, the \TT{lidia\_error\_handler} will be invoked.
If no values for \MATH{l} and \MATH{r} are given, the search will be carried 
out on the entire vector. If \MATH{v.sort\_dir} is not specified either, the 
default sort--direction for \MATH{v} will be used.}

\cfcode{bool}{v.bin\_search}{const T \&x\k int \&pos\k CMP\_FUNC cmp\k int l=DEF\k int r=DEF}
{searches for \MATH{x} among the elements \MATH{v[l],\LDOTS,v[r]} using 
function \TT{(*cmp)()} to compare these entries. The function \MATH{(*cmp)()} must be of 
correct type \BF{CMP\_FUNC}. If no values for \MATH{l} and \MATH{r} are given, 
the search will be carried out on the entire vector. If \MATH{sort\_dir} is 
not specified either, the default sort direction for \MATH{v} will be 
used.}

\cfcode{bool}{v.bin\_search}{const T \&x\k int \&pos\k int l\k int r}
{searches for \MATH{x} among the elements \MATH{v[l],\LDOTS,v[r]} using the 
default sort direction of \MATH{v}.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\STITLE{Insert Functions}
The class \sortv also supports several functions to insert a new
element into a vector. 
These use the member function \TT{v.set\_size()} to extend the size of a vector 
\MATH{v} by 1. If this cannot successfully be done, the vector 
will be left unchanged. In that case, the \TT{lidia\_error\_handler} will 
be invoked.

An element \MATH{x} can either be inserted at a specified position (using 
the function \TT{insert\_at()} of class \basev) or it can also be automatically inserted at 
its \BF{correct} position according to the vector's sort direction.

The function \TT{insert()} provides several prototypes that allow to 
optionally specify a sort direction or a part of the vector in a call to it. If 
these parameters are missing, \MATH{insert()} will refer to the vector 
default sort direction or consider the entire vector, respectively.

Note, that a vector must have been sorted before using the function 
\TT{insert()}. The sort direction used in the sort procedure must 
correspond to the one specified here.

\fcode{void}{v.insert}{const T \&x\k  char sort\_dir=DEF\k int l=DEF\k int r=DEF}
{uses the function \MATH{bin\_search()} to determine the correct position of 
\MATH{x} in \MATH{v} according to the specified sort direction. If \MATH{l} and 
\MATH{r} are specified, the search for \MATH{x} will be restricted to the part
\MATH{v[l],\LDOTS,v[r]}. After \MATH{x} is inserted at the corresponding 
position, every succeeding element in \MATH{v} will be moved one place to the 
right. The value of \MATH{v.sort\_dir} must be either one of the two constants 
SORT\_VECTOR\_UP or SORT\_VECTOR\_DOWN. If \MATH{v.sort\_dir} differs from 
these values, the \TT{lidia\_error\_handler} will be invoked.

If no values are given for \MATH{l}, \MATH{r} or \MATH{sort\_dir}, the default 
values will be passed on to the function \TT{bin\_search()}, i.e. the search for 
\MATH{x} will be carried out on the entire vector and according to its default 
sort direction.}

\fcode{void}{v.insert}{const T \&x\k  CMP\_FUNC cmp\k int l=DEF\k int r=DEF}
{uses the function \TT{bin\_search()} to determine the correct position of 
\MATH{x} in \MATH{v} according to the compare function \TT{(*cmp)()}. If \MATH{l} 
and \MATH{r} are specified, the search for \MATH{x} will be restricted to the 
part \MATH{v[l],\LDOTS,v[r]}. After \MATH{x} is inserted at the corresponding 
position, every succeeding element in \MATH{v} will be moved one place to the 
right. 

If no values are given for \MATH{l} and \MATH{r}, the default values will be 
passed on to the function \TT{bin\_search()}, i.e. the search for \MATH{x} will 
be carried out on the entire vector.}

\fcode{void}{v.insert}{const T \&x\k int l\k int r}
{uses the function \TT{bin\_search()} to determine the correct position of 
\MATH{x} in \MATH{v} according to the default sort direction of \MATH{v}. 
The search for \MATH{x} will be restricted to the part \MATH{v[l],\LDOTS,v[r]}. 
After \MATH{x} is inserted at the corresponding position, every succeeding 
element in \MATH{v} will be moved one place to the right.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\STITLE{Remove Functions}
Furthermore, the class \sortv supports functions to remove elements from a 
vector. These functions use \TT{v.set\_size()} to deminish the size of the 
vector after the removal.

The function \TT{remove()} initiates \TT{bin\_search()} first to 
find a given element \MATH{x} in a vector. If this search was successfully done,
\MATH{one} occurrence of \MATH{x} will be removed from \MATH{v}. Any element 
in \MATH{v} succeeding \MATH{x} will be moved one position to the left and 
the size of the vector will be diminished by 1. If \MATH{x} cannot be found in the 
vector, \MATH{v} will be left unchanged and the return value will be 
\FALSE.

The function \TT{remove()} also provides several prototypes that allow to 
optionally specify a sort direction or a part of the vector. 
If these parameters are missing, \TT{remove()} will refer to the 
vector default sort direction and consider the entire vector, respectively.

\fcode{bool}{v.remove}{const T \&x\k  char sort\_dir = DEF\k int l = DEF\k int r = DEF}
{uses the function \TT{bin\_search()} to find \MATH{x} in \MATH{v} using the 
specified sort direction. If \MATH{l} and \MATH{r} are specified, the search 
for \MATH{x} will be restricted to the part \MATH{v[l],\LDOTS,v[r]}. If 
\MATH{x} can be found in the vector, its first occurence will be deleted. The 
value of \MATH{v.sort\_dir} must be one either of the two constants 
SORT\_VECTOR\_UP or SORT\_VECTOR\_DOWN. If \MATH{v.sort\_dir} differs from 
these values, the \TT{lidia\_error\_handler} will be invoked.

If no values are given for \MATH{l}, \MATH{r} or \MATH{v.sort\_dir}, the default 
values will be passed on to the function \TT{bin\_search()}, i.e. the search for 
\MATH{x} will be carried out on the entire vector and according to its default 
sort direction.}

\fcode{bool}{v.remove}{const T \&x\k  CMP\_FUNC cmp\k int l = DEF\k int r = DEF}
{uses the function \TT{v.bin\_search()} to find \MATH{x} in \MATH{v} using 
the compare function \TT{(*cmp)()}. If \MATH{l} and \MATH{r} are specified, the 
search for \MATH{x} will be restricted to the part \MATH{v[l],\LDOTS,v[r]}. If 
\MATH{x} can be found in the vector, its first occurence will be deleted.

If no values are given for \MATH{l} and \MATH{r}, the default values will be 
passed on to the function \TT{bin\_search()}, i.e. the search for \MATH{x} will 
be carried out on the entire vector.}

\fcode{bool}{v.remove}{const T \&x\k int l\k int r}
{uses the function \TT{bin\_search()} to find \MATH{x} in \MATH{v} using the 
default sort--direction of \MATH{v}. The search for \MATH{x} will be 
restricted to the part \MATH{v[l],\LDOTS,v[r]}. If \MATH{x} can be found in 
the vector, its first occurence will be deleted.}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\SEEALSO
\BF{base\_vector}, \BF{file\_vector}, \BF{math\_vector}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\NOTES
As described in the template introduction (see page \pageref{template_introduction})
for using an instance of type \sortv the type \MATH{T} has to have at least
\begin{itemize}
\item a swap function \TT{void swap(T \&, T\&)},
\item the input operator \TT{>>},
\item the output operator \TT{<<},
\item the assignment operator \TT{=} and 
\item the compare operators \TT{<} and \TT{>}.
\end{itemize}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\EXAMPLES
\begin{verbatim}
 #include <LiDIA/lidia.h>
 #include <LiDIA/sort_vector.h>

 main()
 {
   sort_vector <double> w ;

   cout << " w = " ;
   cin >> w ;

   w.sort();

   cout << w << flush;
 }
\end{verbatim}

For further examples please refer to \\
\TT{LiDIA/src/templates/vector/vector\_appl.c}

%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\AUTHOR
Frank Lehmann, Markus Maurer, Stefan Neis, Thomas Papanikolaou, Patrick 
Theobald 

\end{lidia_man}

