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

\def\basev{base\_vector\TEMPL{T} }
\def\sortv{sort\_vector\TEMPL{T} }
\def\filev{file\_vector\TEMPL{T} }
\def\mathv{math\_vector\TEMPL{T} }

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

\NAME
        \BF{lidia\_vector\TEMPL{T}} \dotfill parameterized vector--class

\ABSTRACT
        Including \BF{lidia\_vector.h} in an application allows the use of the
	C++ type
        \begin{center}
        \BF{lidia\_vector \TEMPL{T}}
        \end{center}
        for some data type \BF{T} which is allowed to be either a built-in type
        or a class.

\DESCRIPTION

 The template class \BF{lidia\_vector} is the most derived class
 in a hierachy of derived vector template classes. The base class
 of this structure is \BF{base\_vector}. By the first derivation step we
 obtain the vector classes \BF{math\_vector}, \BF{sort\_vector},
 and \BF{file\_vector};
 by the second step we acquire \BF{lidia\_vector} itself. This structure
 is shown in the following diagram:

 \begin{tiny}
 \unitlength=1.00mm
 \linethickness{0.4pt}
 \begin{picture}(130.00, 80.00)
 \put(50.00, 70.00){\framebox(20.00,10.00)[cc]{base\_vector}}
% \put(80.00, 70.00){\framebox(20.00,10.00)[cc]{comparator}}
% \put(109.00, 70.00){\framebox(21.00,10.00)[cc]{file\_io\_class}}
 \put(50.00,40.00){\framebox(20.00,10.00)[cc]{sort\_vector}}
 \put(20.00,40.00){\framebox(20.00,10.00)[cc]{math\_vector}}
 \put(80.00,40.00){\framebox(20.00,10.00)[cc]{file\_vector}}
% \put(20.00,10.00){\framebox(20.00,10.00)[cc]{math\_sort\_vector}}
 \put(50.00,10.00){\framebox(20.00,10.00)[cc]{lidia\_vector}}
% \put(80.00,10.00){\framebox(20.00,10.00)[cc]{file\_sort\_vector}}

 \put(30.00, 50.00){\vector(3,2){30.00}}

 \put(60.00, 50.00){\vector(0,1){20.22}}

 \put(90.00, 50.00){\vector(-3,2){30.00}}

 \put(60.00,20.00){\vector(-3,2){30.00}}

 \put(60.00,20.00){\vector(0,1){19.89}}

 \put(60.00,20.00){\vector(3,2){30.00}}
 \end{picture}
 \end{tiny}


 The notation ''B $\leftarrow$ D'' indicates class--inclusion and
 thus says that B is a base class of the derived class D.

 %The classes \EM{comparator} and \EM{file\_io\_class} are not
 %exclusively designed for the vector application, but they can be useful
 %for other classes as well. The class \EM{comparator} contains functions
 %for comparisons, like \EM{less\_than()} etc., and \EM{file\_io\_class}
 %contains functions for reading from and writing to a file, e.g.
 %\EM{read\_from\_file()}. For a more detailed description of these
 %classes see \EM{comparator.h} or \EM{file\_io\_class.h}, respectively.

 The different vector classes distinguish in the requirements on the
 type \BF{T}, to which the elements of a vector belong. Each
 step of inheritance in the structure requires more properties for
 a type \BF{T} used in the template.

 Before we describe the functions which are associated with individual
 vector classes and the requirements on \BF{T}, we'll explain the basic
 concept of \EM{base\_vector} which is passed to all derived vector
 classes.

 For a \BF{base\_vector} \MATH{v} we distinguish two values which
 describe the length of \MATH{v}. We call the number of allocated elements
 the \BF{capacity} of \MATH{v}. The \BF{size} of the vector is the
 number of items actually used in \MATH{v}, which corresponds to the
 largest index ever accessed in \MATH{v}. Thus, this value will never
 decrease; neither will it exceed the capacity.

 Both values can individually be changed by using functions
 \BF{set\_capacity()} and \BF{set\_size()}, respectively.


 As an example, the declaration
 \begin{quote}
     base\_vector $<$int$>$ \MATH{v}(10)
 \end{quote}
 will create a \EM{base\_vector} with 10 elements allocated, so
 \MATH{v}.capacity() = 10. If we use the first $s$ elements of \MATH{v} only,
 $s$ will be the \BF{size} of \MATH{v}. In our example, after the declaration,
 \MATH{v} has $size$ = 0 and if we assign
 \begin{quote}
      \MATH{v}[0] = 1, \MATH{v}[1] = 2
 \end{quote}
 we obtain \MATH{v}.size() = 2. As shown in this example the first element
 of \MATH{v}  is put on  index 0 and the last one is put on index \MATH{v}.size()$-1$.


 Furthermore, a \EM{base\_vector} \MATH{v} can be of either \BF{fixed}
 or \BF{expanding} size. For so--called fixed vectors, one can
 only change the number of \EM{allocated} items in the vector by
 using member--function set\_capacity(). I.e., neither is it
 possible to access the vector at an index which is not smaller
 than the vector's capacity, nor may function set\_size() be
 called with a size greater than this value.

 Vectors of expanding size automatically allocate memory, if access
 is required for an index greater than its current capacity, or the
 number of items in a call to set\_size() exceeds that value.
 The new amount of memory to be allocated in these cases will then
 be computed using the \BF{expansion\_ratio} of the vector.
 This is a factor by which the required number of elements will
 be multiplied by before actually reallocating memory. The value
 of this factor is $2.0$ by default and may be altered at any
 time to a new value, which must be $1.0$ at least, by using
 the member--function set\_exp\_ratio().

 The property, whether a vector is of fixed or expanding size,
 is stored in a member called \BF{mode}. The value of this
 member can be either of the constants ''\BF{FIXED}'' or
 ''\BF{EXPAND}''. By default, each vector is of \EM{fixed}
 size. Its mode can explicitly be set by either using function
 set\_mode() or by adding ''\BF{FIXED}'' or ''\BF{EXPAND}'' as
 an additional argument to the corresponding constructor.


 In the sequel we list every function of each vector class and
 the corresponding requirements on the type T elements a vector
 consists of. Pay attention to the fact that every function which
 is put at disposal by a base class is put at disposal by a derived
 class, too (see picture above).



% \markright{\BF{base\_vector}}
\STITLE{class \basev}

\STITLE{REQUIREMENTS}

Class \basev requires the operators \TT{=}, \TT{<<}, and \TT{>>} for type T elements.

\CONS

\fcode{\basev}{}{
	initializes a vector with capacity 0.}
\fcode{\basev}{lidia\_size\_t $c$}{
        initializes a vector with capacity $c$.}
\fcode{\basev}{lidia\_size\_t $c$ \k lidia\_size\_t $s$}{
        initializes a vector with capacity $c$ and size $s$.}
\fcode{\basev}{const \basev \& $w$}{
	initializes a vector with capacity $w$.size() and copies
        the elements of $w$ into it; it requires the assignment operator for T.}
\fcode{\basev}{T* $a$ \k lidia\_size\_t $l$}{
        initializes \MATH{v} with the first $l$ elements of $a$ and requires
        the assignment operator for T.}

Furthermore each constructor can get an additional parameter
(FIXED or EXPAND) to indicate the mode of the base\_vector.


\STITLE{ACCESS FUNCTIONS}

Let \MATH{v} be of type \basev.

\INIT

\cfcode{lidia\_size\_t v.size}{}{
        returns the size of \MATH{v}.}
\fcode{int v.set\_size}{lidia\_size\_t $s$}{
        sets the size of \MATH{v} to $s$, if the capacity of $ v $ is
        large enough. If $s$ exceeds \MATH{v}.capacity() and \MATH{v} is of
        \EM{expanding\/} size, new memory will be allocated
        by using the set\_capacity--function for \MATH{v}. The number
        of elements allocated in that case is \MATH{v}.exp\_ratio() $\cdot s$.
        If these actions can successfully be performed, the return--value
        of this function will be $0$; otherwise, it will be $1$.
        This function requires the assignment operator for T.}

\cfcode{lidia\_size\_t v.capacity}{}{
        returns the capacity of \MATH{v}.}
\fcode{int v.set\_capacity}{lidia\_size\_t $c$}{
        sets the capacity of \MATH{v} to $c$ by allocating \EM{exactly\/}
        $c$ elements for \MATH{v}. Here, $c$ must be a non--negative value;
        if $c$ is $0$, the elements of \MATH{v} will be deleted. If no error
        occurs in this function, its return--value will be $0$;
        otherwise, it will be $1$.

        If there is not enough memory, and the allocation--process
        fails, a call to the error--handler will be initiated.
        This function requires the assignment operator for T.}

\cfcode{float v.exp\_ratio}{}{
        returns the expansion ratio of \MATH{v}.}
\fcode{void v.set\_exp\_ratio}{float $e$}{
        sets the expansion ratio of \MATH{v} to $e$. The value of $e$
        must be $1.0$ at least. If $e$ is invalid, the expansion ratio
        of \MATH{v} will remain unchanged, and the return--value
        of the function will be $1$. Otherwise, the return--code will be
        $0$.}

  \fcode{int v.set\_mode}{char $m$}{
        sets mode of \MATH{v} to $m$; $m$ must be either of the
        two constants ''FIXED'' or ''EXPAND''. If $m$ differs from these
        values, the mode of \MATH{v} will remain unchanged, and the return--value
        of the function will be $1$. Otherwise, the return--code will be
        $0$.}

  \IO

  \fcode{int v.read}{istream \& $in$}{
        reads a vector from stream $in$. The input must be of the
        form ''$[ v_{0} \ldots v_{n-1} ]$''. The size and capacity
        of \MATH{v} will then be set to $n$. This function will always
        return $0$; it requires operator$>>$ for T.}

  \fcode{istream \& operator$>>$}{istream \& $in$ \k \basev \& \MATH{v}}{
        performs a function call to \MATH{v}.read( $in$ ) and returns
        a reference to the input stream.}

  \cfcode{int v.write}{ostream \& $out$}{
        writes \MATH{v} in form of ''$[ v_{0} \ldots  v_{n-1} ]$'' to
        ostream $out$, when the size of \MATH{v} is $n$. The return--code
        will always be $0$. This function requires opertor$<<$ for T.}

  \fcode{operator$<<$}{ostream \& $out$ \k const \basev \& \MATH{v}}{
        performs a function call to \MATH{v}.write( $out$ ) and returns
        a reference to the output stream.}

  \ACCS

  \fcode{T \& operator[]}{lidia\_size\_t $i$}{
        If the mode of \MATH{v} is FIXED, the operator
        returns a reference to the $i+1$-st element in \MATH{v},
        provided that $i$ is less than the capacity of the vector;
        if $i$ is too large, a call to the error\_handler will
        be initiated. The size of the vector will be set
        appropriately after a successful access (i.e., it will be
        set to $i+1$ if this value is greater than the previous
        size).

        If \MATH{v} is of expanding size, the capacity of the vector
        will be extended, if $i$ is not less than its current
        value. This is done by a call to \MATH{v}.set\_capacity().
        The number of elements that will be allocated is
        $(i+1)\cdot$ \MATH{v}.exp\_ratio().
        In any way, provided that the memory reallocation
        succeeds, the operator will return a reference to the
        $i+1$-st element in \MATH{v}. The size of the vector will be set
        appropriately.}

  \cfcode{const T \& operator[]}{lidia\_size\_t $i$}{
        returns a constant reference to the $i+1$-st element in \MATH{v}.
        In either mode, ''FIXED'' or ''EXPAND'', $i$ must be non-negative
        and less than \MATH{v}.size(); neither the capacity nor the size of
        \MATH{v} will be changed by an access.}

  \cfcode{T \& member}{lidia\_size\_t $i$}{
        returns a reference to the $i+1$-st element in \MATH{v}.
        In either mode, ''FIXED'' or ''EXPAND'', $i$ must be non-negative
        and less than \MATH{v}.size(); neither the capacity nor the size of
        \MATH{v} will be changed by an access.}

  \fcode{\basev \& operator=}{const \basev \& $w$}{
         the assignment operator allocates $w$.size() elements for
         \MATH{v} using \MATH{v}.set\_capacity() and copies the entries of $w$
         into \MATH{v}. It then returns a reference to \MATH{v}.
         This function requires the assignment
         operator for T.}

 \fcode{void v.kill}{}{
        deallocates the vector's elements and sets its capacity
        and size to zero.}

  \fcode{int v.reverse}{}{
        rearranges elements of vector \MATH{v} in reverse order. The
        return--code of this function is always $0$.}

  \fcode{int v.reverse}{const \basev \& $w$}{
        copies the elements of $w$ in reverse order into
        vector \MATH{v}. If $w$ does not alias \MATH{v}, $w$.size() elements
        will be allocated for \MATH{v} by using \MATH{v}.set\_capacity().
        The return--code of this function is always $0$.}

  %\fcode{void v.swap}{\basev \& $w$}{
  %      exchanges the complete information of \MATH{v} and $w$.
  %      Neither of the capacities of the two vectors will
  %      be changed.}

  \fcode{int v.concat}{const \basev $u$ \k const \basev $w$}{
        stores in \MATH{v} the concatenation of $u$ and $w$.
        The capacity of \MATH{v} will be set to the sum of the
        sizes of two vectors $u$ and $w$. Either of the
        two parameters may alias \MATH{v}. The return value will
        always be $0$.}

  \fcode{int v.shift\_left}{lidia\_size\_t pos \k lidia\_size\_t num}{
        moves the elements of \MATH{v}, starting at $v[pos]$,
        $num$ positions to the left; thus overwriting
        some preceeding entries. The size of \MATH{v} will
        be reduced by $num$ using function set\_size();
        the return--value of that function will be
        passed on. The value of $num$ may not exceed $pos$.}

  \fcode{int v.shift\_right}{lidia\_size\_t pos \k lidia\_size\_t num}{
        copies the elements of \MATH{v}, starting at \MATH{v}[pos],
        $num$ positions to the right; possibly overwriting some
        succeeding elements in \MATH{v}.
        The size of \MATH{v} will be increased by $num$ using function
        set\_size(); the return--value of that function will be
        passed on.}

  \fcode{int v.assign}{lidia\_size\_t at \k const \basev \& $w$ \k lidia\_size\_t from \k lidia\_size\_t to}{
        copies the elements $w[from], \ldots, w[to]$ to vector \MATH{v},
        starting at position $v[at]$. The corresponding elements of \MATH{v}
        will be overwritten. Vector $w$ may alias \MATH{v}.
        The size of \MATH{v} will be adjusted using function
        set\_size(); the return--value of that function will be
        passed on.}

  \fcode{int v.set\_data}{T * d \k lidia\_size\_t l)}{
        copies $l$ elemtens $d[0], \ldots, d[l-1]$ to vector \MATH{v} and
        adjusts its capacity. The return--code of this function
        is always $0$.}

  \fcode{T * v.get\_data}{}{
        returns a pointer to a copy of the vector`s elements. If
        there is not enough memory to allocate a duplicate of these
        data, the error\_handler will be called.}

  \fcode{T * v.get\_data\_address}{}{
        returns a pointer to the internal array of elements.

        {\sc \BF{CAUTION:} This Function Should Only Be Used, If One
        Can Guarantee That No Internal Information of \MATH{v} Will Become
        Invalid After Access Via The Returned Pointer. In Particular,
        One Must Not Use {\rm ''new''} Or {\rm ''delete''} On The
        Return--Value Of This Function.
        This Function Is Accessible Only If ''LiDIA\_VECTOR\_INTERNAL\_DATA\_ACCESS''
        Has Been Defined Before Including The Header--Filer; After The
	Include Statement This Definition Should Be Deleted Using The
 	''\#undef'' Directive.}}


 \SUBK{\basev, friend functions:}

 \fcode{void swap}{\basev \& \MATH{v} \k \basev \& $w$}{
        exchanges the complete information of \MATH{v} and $w$.
        Neither of the capacities of the two vectors will
        be changed.}



% \markright{\BF{math\_vector}}
 \STITLE{class \mathv}

 Class \mathv requires the operators \TT{=}, \TT{<<}, \TT{>>},
 \TT{+},\TT{-},\TT{*},\TT{/}, \TT{==}, and \TT{!=} for type T elements.


 This class puts at disposal all the constructors, member, and friend functions
 which are available for the virtual base class \EM{base\_vector}. Furthermore
 \EM{math\_vector} provides the following friend and member
 functions; corresponding arithmetical operators are implemented.


 \ARTH

   Componentwise combination of two vectors requires that they are
   both of the same size. If this requirement is not met during
   a call to the functions below, the error\_handler will be
   initiated. Apart from this, these functions will  always return $0$.


   \fcode{int add}{        \mathv \&  $r$ \k
                     const \mathv \&  \MATH{v} \k const \mathv \& $w$}{
         adds two  math\_vectors \MATH{v} and $w$ elementwise and stores the result
         in $r$; requires operator$+$ for type T.}

   \fcode{int subtract}{   \mathv \&  $r$ \k
                     const \mathv \&  \MATH{v} \k const \mathv \& $w$}{
         subtracts math\_vector  $w$ from \MATH{v} elementwise and stores the result
         in $r$; requires operator$-$ for type T.}

   \fcode{int multiply}{  \mathv \&  $r$ \k
                     const \mathv \&  \MATH{v} \k const \mathv \& $w$}{
         multiplies two  math\_vectors \MATH{v} and $w$ elementwise and stores the result
         in $r$; requires operator$\ast$ for type T.}

   \fcode{int divide}{    \mathv \&  $r$ \k
                     const \mathv \&  \MATH{v} \k const \mathv \& $w$}{
         divides   math\_vector \MATH{v} by   $w$ elementwise and stores the result
         in $r$; requires operator$/$ for type T.}

   \fcode{int negate}{\mathv \& \MATH{v} \k const \mathv \MATH{v}}{
         negates the  math\_vector \MATH{v} elementwise and stores the resulting
         vector in $r$; requires unary operator$-$ for type T.}


   \SUBK{Scalar Operations}



   \fcode{int add}{      \mathv \& $r$ \k
                    const \mathv \& \MATH{v} \k const T \& $\alpha$}{
         adds $\alpha$ from the right to each component of  math\_vector
         \MATH{v} and stores the result in $r$; requires operator$+$
         for type T.}

   \fcode{int add}{      \mathv \& $r$ \k
                    const T \& $\alpha$ \k const \mathv \& \MATH{v}}{
         adds $\alpha$ from the left to each component of  math\_vector
         \MATH{v} and stores the result in $r$; requires operator$+$
         for type T.}


   \fcode{int subtract}{ \mathv \& $r$ \k
                    const \mathv \& \MATH{v} \k const T \& $\alpha$}{
         subtracts $\alpha$  from each component of  math\_vector
         \MATH{v} and stores the result in $r$; requires operator$-$
         for type T.}

   \fcode{int subtract}{ \mathv \& $r$ \k
                    const T \& $\alpha$ \k const \mathv \& \MATH{v}}{
         subtracts successively each component of  math\_vector \MATH{v} from
         $\alpha$ and stores the resulting vector in $r$; requires
         operator$-$ for type T.}

   \fcode{int multiply}{ \mathv \& $r$ \k
                    const \mathv \& \MATH{v} \k const T \& $\alpha$}{
         multiplies each component of math\_vector \MATH{v} from the right
         by $\alpha$ and stores the result in $r$; requires operator$\ast$
         for type T.}

   \fcode{int multiply}{ \mathv \& $r$ \k
                    const T \& $\alpha$ \k const \mathv \& \MATH{v}}{
         multiplies each component of math\_vector \MATH{v} from the left
         by $\alpha$ and stores the result in $r$; requires operator$\ast$
         for type T.}

   \fcode{int divide}{   \mathv \& $r$ \k
                    const \mathv \& \MATH{v} \k const T \& $\alpha$}{
         divides each component of math\_vector \MATH{v}
         by $\alpha$ and stores the result in $r$; requires operator$/$
         for type T.}

   \fcode{int divide}{   \mathv \& $r$ \k
                    const T \& $\alpha$ \k const \mathv \& \MATH{v}}{
         divides $\alpha$ successively by  each component of  math\_vector
         \MATH{v} and stores the resulting vector in $r$; requires operator$/$
         for type T.}

   \HIGH

   \fcode{T inner\_product}{const \mathv \& \MATH{v} \k const \mathv \& $w$}{
         returns the inner product of \MATH{v} and $w$.}

   \fcode{T sum\_of\_squares}{const \mathv \& \MATH{v}}{
         returns the sum of the squares of the vector's elements.}

   \COMP

   \fcode{bool operator==}{const \mathv \& $w$}{
         returns \BF{true} if the two vectors are equal in each
         component, \BF{false} otherwise.}

   \fcode{bool operator!=}{const \mathv \& $w$}{
         returns \BF{true} if the two vectors differ in at least one
         component, \BF{false} otherwise.}




% \markright{\BF{file\_vector}}
 \STITLE{class file\_vector\TEMPL{T}}


 Class \filev requires the following member--functions for type T:
 \TT{print\_to\_file(fp)} (i.e., writing in text--format),
 \TT{write\_to\_file(fp)} (i.e., binary--writing ), \TT{scan\_from\_file(fp)}
 (i.e., reading in text--format), \TT{read\_from\_file(fp)} (i.e.,
 binary--writing), where \TT{fp} is of type \TT{FILE*}. As well as
 the  operators \TT{=}, \TT{<<}, and \TT{>>}.


 This class supports any constructor, member, and friend function
 which is available for the virtual base class \EM{base\_vector}. Furthermore
 file\_vector provides the following member functions. In the sequel
 \EM{fp\/} must always be a file--pointer to a file that has already
 been opened in the appropriate mode (e.g., a non--zero pointer that
 has been returned by \TT{fopen()}).


   \cfcode{int v.print\_to\_file}{FILE * \EM{fp}}{
         writes a vector to the file, which \EM{fp} is pointing to,
         in text--format; the output is of the form ''$[ v_{0} \ldots  v_{n-1} ]$'',
         if $n$ is the size of \MATH{v}. The return--value will always be $0$.
         This function requires the member function \EM{print\_to\_file()}
         for type T.}

   \fcode{int v.scan\_from\_file}{FILE * \EM{fp}}{
         reads a vector from the file, which \EM{fp} is pointing to,
         in text--format; the vector must be stored in form of
         ''$[ v_{0} \ldots  v_{n-1} ]$''. The size and capacity of \MATH{v}
         will then be set to $n$. The return--value of this function
         is $0$, if \MATH{v} can successfully be read, and $1$ otherwise.
         This function requires the member function
         \EM{scan\_from\_file()} for type T.}

   \cfcode{int v.write\_to\_file}{FILE * \EM{fp}}{
         writes a vector to the file, which \EM{fp} is pointing to,
         in binary--format. First, the length of \MATH{v} is written to
         the file; afterwards, the elements of \MATH{v} are successively stored to
         \EM{fp\/} by using the member--function \EM{write\_to\_file()}
         for type T elements. The return--code of this function is
         always $0$.}

   \fcode{int v.read\_from\_file}{FILE * \EM{fp}}{
         reads a vector from the file, which \EM{fp} is pointing to,
         in binary--format. The function starts by reading the length
         of a vector at the current file--pointer--position. Afterwards,
         the corresponding number of elements is allocated for \MATH{v} by
         using the set\_capacity--function. Then, the elements
         are successively read into \MATH{v}. The return--value of this function
         is $0$, if \MATH{v} can successfully be read, and $1$ otherwise.
         This function requires the member function \EM{read\_from\_file()}
	 for type T.}

 The above functions read and write from the current file position the pointer
 is pointing to; the file--pointer will \BF{not} be reset after the
 reading or writing process.

   \cfcode{int v.append\_a}{FILE * \EM{fp\/}}{
         appends the elements of vector \MATH{v} to another vector that is
         stored at the end of a text--file. If \TT{fp} indicates
         the beginning of a vector, this one will be extended by
         the elements of \MATH{v}. If \TT{fp} is pointing to the end of
         a file, this function is equivalent to
         v.print\_to\_file(). The file--pointer must allow both,
         reading and writing operations. It will, at the end, reside
         in the same position as prior to the function call.

         If \MATH{v} can successfully be written to the file, the return--value
         will be $0$; otherwise, it will be $1$.}

   \cfcode{int v.append\_a}{FILE * \EM{fp\/ \k lidia\_size\_t $n$}}{
         appends the $n+1$--st element of \MATH{v} to another vector that is
         stored at the end of a text--file. If \TT{fp} indicates
         the beginning of a vector, this one will be extended by
         $v[n]$. If \TT{fp} specifies the end of a file, this function
         will add a vector of size $1$ to it. The file--pointer
         must allow both, reading and writing operations. It will, at
         the end, reside in the same position as prior to the function call.

         If \MATH{v} can successfully be written to the file, the return--value
         will be $0$; otherwise, it will be $1$.}

   \cfcode{int v.append\_b}{FILE * \EM{fp\/}}{
         appends the elements of vector \MATH{v} to another vector that is
         stored at the end of a binary--file. If \TT{fp} indicates
         the beginning of a vector, this one will be extended by
         the elements of \MATH{v}. If \TT{fp} specifies the end of a file,
         this function is equivalent to v.write\_to\_file(). The
         file--pointer must allow both, reading and writing operations.
         It will, at the end, reside in the same position as prior to the
         function call.

         If \MATH{v} can successfully be written to the file, the return--value
         will be $0$; otherwise, it will be $1$.}

   \cfcode{int v.append\_b}{FILE * \EM{fp\/ \k lidia\_size\_t $n$}}{
         appends the $n+1$--st element of \MATH{v} to another vector that is
         stored at the end of a binary--file. If \TT{fp} indicates
         the beginning of a vector, this one will be extended by
         $v[n]$. If \TT{fp} specifies the end of a file, this function
         will add a vector of size $1$ to it. The file--pointer
         must allow both, reading and writing operations. It will, at
         the end, reside in the same position as prior to the function call.

         If \MATH{v} can successfully be written to the file, the return--value
         will be $0$; otherwise, it will be $1$.}



 \SUBK{Remark}

 The read--functions for type T should work in a way that they read the whole
 stuff which has previously been written by the corresponding write--function,
 e.g. a ``$\backslash n$'' appended to a type T element by the
 print--function must be read by the scan--function.





% \markright{\BF{sort\_vector}}
 \STITLE{class sort\_vector\TEMPL{T}}

  Class \BF{\sortv} contains \BF{\basev} as a virtual base class.
  It  supports any constructor, member--, and friend--function
  of that class. Additionally it provides functions for sorting and
  searching, inserting and deleting. For this, class (or built-in type)
  \BF{T} must support the operators \TT{<, <=,} and \TT{==}.

  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
  \EM{compare--functions\/} may be used to define a relation of type T
  elements. These functions can then be  a new sort--direction
  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}
     $ < 0 $ & if \EM{(a,b)} is in correct order \\
     $ = 0 $ & if \EM{a, b}  are identified      \\
     $ > 0 $ & if \EM{(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 by function \EM{v.sort()}.
  This default--sort--direction will be set to \BF{SORT\_VECTOR\_UP}
  by any constructor in this class; i.e., vector $ v $ will be sorted
  in ascending order by default.
  This default--value may later be changed by function \EM{set\_sort\_direction()}.

  \bigskip


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

  \fcode{int v.set\_sort\_direction}{char dir}{
         sets the default sort--direction for $ v $ to \TT{dir}. The
         value of \TT{dir} may be either of the two predefined constants
         \TT{SORT\_VECTOR\_UP} or \TT{SORT\_VECTOR\_DOWN}. The
         return--value of this function will be $0$, if \TT{dir}
         is a correct value. If \TT{dir} is invalid, the
         standard--sort--direction of \MATH{v} will be left unchanged
         and the return--code will be $1$.}

  \fcode{int v.set\_sort\_direction}{int (*cmp) (const T \& a, const T \& b)}{
         sets the default sort--direction for $ v $ in a
         way that function \TT{cmp()} will be used to
         compare the entries of $ v $. The return--code of this
         function is always $0$.}


  \SSTITLE{sort--function}

  Class \EM{\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 to 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 cut of a vector
  by explicitly passing start-- and end--indices to this function.
  Whenever these values are invalid, function \TT{error\_handler()}
  will be called.

  \fcode{int v.sort}{char sort\_dir = DEF \k int l = DEF \k int r = DEF}{
         sorts the elements \EM{v[l],...,v[r]} according to the
         direction \TT{sort\_dir}. Any other element in \TT{v} will
         remain in its position.
         The value of \TT{sort\_dir} must be either of the to constants
         ''SORT\_VECTOR\_UP'' or ''SORT\_VECTOR\_DOWN''. If it differs
         from these values, the error--handler will be called.

         If no values for \TT{l} and \TT{r} are given, the entire vector
         will be sorted. If \TT{sort\_dir} is not specified either, the
         default sort--direction for \TT{v} will be considered.
         This function returns $ 0 $ after sorting the vector.
  }

  \fcode{int v.sort}{CMP\_FUNC cmp \k int l = DEF \k int r = DEF}{
         sorts the elements \EM{v[l],...,v[r]} according to the
         compare--function \TT{cmp}. Any other element in \TT{v} will
         remain in its position.
         Function \TT{cmp} must be of correct type \BF{CMP\_FUNC}.

         If no values for \TT{l} and \TT{r} are given, the entire vector
         will be sorted.  The return--value of this call is always 0.
  }


  \fcode{int v.sort}{int l \k int r}{
         sorts the elements \EM{v[l],...,v[r]} according to the
         default sort--direction of \TT{v}.
         The return--value of this call is always $0$.
  }



  \SSTITLE{search--function}

  As a second feature, class \sortv  provides functions for linear
  and binary search in a vector.


  \fcode{int v.linear\_search}{ T \&x \k int \&pos}{
      searches $ x $ in vector $ v $. If $ x $ can be found,
      this function will return 1, and $ pos $ will
      hold the index of its \EM{first} occurence in $ v $.
      Otherwise, the return--value will be 0.
    }

  Function \TT{bin\_search()} searches for an element \EM{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 $1$, if it succeeds, and $0$ otherwise.
  If \EM{x} can be found in a vector, \EM{pos} will hold the index of its
  \EM{first} occurence; or else, \EM{pos} will be the index, where \EM{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 cut of a vector
  by explicitly passing start-- and end--indices to this function.
  Whenever these values are invalid, function \TT{error\_handler()}
  will be called.

  \fcode{int v.bin\_search}{T \&x \k int \&pos \k char sort\_dir=DEF \k int l=DEF \k int r=DEF}{
        searches for $ x $ among the elements \TT{v[l],...,v[r]}
        using sort--direction \TT{sort\_dir}. Its value must be either
        of the two constants ''SORT\_VECTOR\_UP'' or ''SORT\_VECTOR\_DOWN''.
        If \TT{sort\_dir} differs from these values, the error--handler will
        be called.

        If no values for \TT{l} and \TT{r} are given, the search will be
        carried out in the entire vector. If \TT{sort\_dir} is not specified
        either, the default sort--direction for \TT{v} will be considered.
  }

  \fcode{int v.bin\_search}{T \&x \k int \&pos \k CMP\_FUNC cmp \k int l=DEF \k int r=DEF}{
        searches for $ x $ among the elements \TT{v[l],...,v[r]}
        using function \TT{cmp} to compare these entries.
        Function \TT{cmp} must be of correct type \BF{CMP\_FUNC}.

        If no values for \TT{l} and \TT{r} are given, the search will be
        carried out in the entire vector. If \TT{sort\_dir} is not specified
        either, the default sort--direction for \TT{v} will be considered.
  }

  \fcode{int v.bin\_search}{T \&x \k int \&pos \k int l \k int r}{
        searches for $ x $ among the elements \TT{v[l],...,v[r]}
        using the default sort--direction of \TT{v}.
  }



  \SSTITLE{insert-function}

  Class \sortv also supports  functions to insert a new element into
  a vector. These use member--function \TT{set\_size()} to extend the
  size of a vector by 1. If this cannot successfully be done,
  they will pass on the error--code returned by \TT{set\_size()};
  the vector will then be left unchanged. In that case, the
  error--handler--function will be called. If an element can be
  inserted, the return--value of these functions will be $0$.

  An element $ x $ can either be inserted at a specified position
  (using function \EM{insert\_at()\/}), and it can also be automatically
  inserted at its, according to the vector's sort--direction, \EM{correct}
  position (using function \EM{insert()\/}).

  \fcode{int insert\_at}{ T \&x \k int pos}{
     moves the elements of $ v $, starting at \EM{v[pos]}, one
     position to the right, and sets \EM{v[pos] = x}.
  }

  Function \EM{insert()\/} provides several prototypes, that allow to
  optionally specify a sort--direction or a cut of the vector
  in a call it.
  If these paramters are missing, \EM{insert()\/} will refer to the vector's
  default sort--direction or consider the entire vector, respectively.

  Take care, that a vector has been sorted, before the use of
  function \TT{insert()} . The sort--direction used in the sort--procedure
  must correspond to the one specified here.

  \fcode{int insert}{T \&x \k  char sort\_dir=DEF \k int l=DEF \k int r=DEF}{
     uses function \EM{v.bin\_search()} to determine the
     correct position of \MATH{x} in \MATH{v} according to specified  sort--direction.
     If \TT{l} and \TT{r} are specified, the search for \MATH{x}
     will be restricted to the cut \TT{v[l],...,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 \TT{sort\_dir} must be either of the two
     constants ''SORT\_VECTOR\_UP'' or ''SORT\_VECTOR\_DOWN''. If
     \TT{sort\_dir} differs from these values, the error--handler will be
     called.

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



  \fcode{int insert}{T \&x \k  CMP\_FUNC cmp \k int l=DEF \k int r=DEF}{
     uses function \EM{v.bin\_search()} to determine the
     correct position of \MATH{x} in \MATH{v} according to compare--function \TT{cmp}.
     If \TT{l} and \TT{r} are specified, the search for \MATH{x}
     will be restricted to the cut \TT{v[l],...,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 \TT{l} and \TT{r},
     default values will be passed on to function \TT{bin\_search()};
     i.e., the search for \MATH{x} will be carried out in the entire
     vector.
  }

  \fcode{int insert}{T \&x \k int l \k int r}{
     uses function \EM{v.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 cut
     \TT{v[l],...,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.
  }




  \SSTITLE{remove-function}

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


  \fcode{int remove\_from}{ int pos \k int n = 1}{
     removes \EM{n} elements from within vector \EM{v}
     starting at \EM{v[pos]}. Any element in \EM{v}
     succeeding \EM{v[pos]} will be moved \EM{n}
     positions to the left.
     After a successfull deletion, the size of vector \EM{v}
     will be diminshed by \EM{n}.

     If \EM{v} contains less than \EM{pos+n } elements,
     a call to function \EM{error\_handler()} will be initiated.

     This function passes on the return--code of v.set\_size()
     after changing the size of the vector.
  }

  The following function, \TT{remove()}, initiates \TT{bin\_search()} first,
  to find a given element $ x $ in a vector. If this search is successfull,
  \EM{one\/} occurrence of $ x $ will be removed from $ v $.
  Any element in $ v $ succeeding  $ x $ will be moved one
  position to the left, and the size of the vector will diminish
  by 1; the return--code of function \TT{v.set\_size()} will be passed on.
  If $ x $ cannot be found in the vector, $ v $ will be left
  unchanged; the return--value will then be $ 1$.


  Function \EM{remove()\/} also provides several prototypes, that allow to
  optionally specify a sort--direction or a cut of the vector
  in a call for it.
  If these paramters are missing, \EM{remove()\/} will refer to the vector's
  default sort--direction or consider the entire vector, respectively.


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

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

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

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

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



 \STITLE{Additional Classes}

 The class \BF{lidia\_vector\TEMPL{T}} is a combination of the classes
 \EM{math\_vector}, \EM{sort\_vector}, and \EM{file\_vector}. That means
 that it puts at disposal all functions of its base--classes. Obviously,
 this derived class requires the same functions for type $T$ as the
 corresponding base--classes do.



\SEEALSO

        base\_vector.h, file\_vector.h, math\_vector.h, sort\_vector.h,
\NOTES
        \begin{itemize}

%	\item
%	To improve efficiency, it is possible to avoid range checking
%	while using \EM{operator[]} and function \EM{set\_size()}.
%	This can be done by inserting
%	\begin{center}
%     	\#define LiDIA\_VECTOR\_NO\_RANGE\_CHECK
%	\end{center}
%	before including the header--file of any vector class. If this feature
%	is used, the class is restricted to vectors of mode FIXED.

        \item
        Beware of the use of \EM{expanding\/} vectors. Unpredictable
        errors might occur in situations like the following.
        Consider the command
        \begin{verbatim}
                          add ( v[2] , v[1] , a )
        \end{verbatim}
        for a vector \MATH{v} with capacity 2. If the parameters of that
        call are evaluated right to left, the address of v[1] will be
        stored before the access to v[2] will cause a memory
        reallocation for \MATH{v}. The latter might change the address
        of v[1] and thus invalidate the previously stored value.



        \end{itemize}


\EXAMPLES

\begin{verbatim}
#include <LiDIA/lidia_vector.h>

int main()
{
  lidia_vector <int> u, v, w ;

  cout << " u = " ;
  cin >> u ;

  cout << " v = " ;
  cin >> v ;

  w = u + v ;

  cout << " sum : " << w ;

  return 0;
}
\end{verbatim}

\AUTHOR
        Frank Lehmann \& Markus Maurer \& Thomas Papanikolaou



\end{lidia_man}
