%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  math_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\mathv{\BF{math\_vector\TEMPL{T}} }

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

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

\NAME
\mathv \DOTFILL vectors with basic mathematical operations 

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

\ABSTRACT
\mathv is a class for doing simple mathematical operations 
over vectors such as vector addition or the computation of the inner product.

According to the template introduction (see page \pageref{template_introduction}) 
the vector class \mathv is derived from \basev. So you can apply all
the functions and operators of class \basev to instances of the type
\mathv. \BF{T} is allowed to be either a built-in type or a class. 

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

\DESCRIPTION
A variable of type \mathv contains the same components as \basev.

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

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

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

\fcode{ct}{\mathv}{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}{\mathv}{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}{\mathv}{const \mathv \& w}
{constructs a vector with capacity \MATH{w.size} initialized with the elements 
of \MATH{w}.}

\fcode{ct}{\mathv}{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 \mathv}{}{}

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

\ARTH
The class \mathv (mv\TEMPL{T}) supports the following operators:\hfill\\
\begin{tabular}{|c|rcl|l|}\hline
unary & & \MATH{op} & mv\TEMPL{T} & \MATH{op\IN\{\TT{-}\}} \\\hline
binary & mv\TEMPL{T} & \MATH{op} & mv\TEMPL{T} 
& \MATH{op\IN\{\TT{+},\TT{-},\TT{*}\}}\\\hline
binary with & mv\TEMPL{T} & \MATH{op} & mv\TEMPL{T}
& \MATH{op\IN\{\TT{+=},\TT{-=}\}}\\
assignment & & & &\\\hline
binary & mv\TEMPL{T} & \MATH{op} & T
& \MATH{op \IN\{\TT{+},\TT{-},\TT{*},\TT{/}\}}\\\hline
binary & T & \MATH{op} & mv\TEMPL{T}
& \MATH{op \IN\{\TT{+},\TT{-},\TT{*}\}}\\\hline
binary with & mv\TEMPL{T} & \MATH{op} & T
& \MATH{op \IN\{\TT{+=},\TT{-=},\TT{*=},\TT{/=}\}}\\
assignment & & & &\\\hline
\end{tabular}

Componentwise combination of two vectors requires that they are both of the 
same size. If this requirement is not met during a call of these operators, 
the \TT{lidia\_error\_handler} will be invoked. If the result vector 
has not the right size it will be adapted automatically.

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

\SSTITLE{Addition}
\fcode{void}{add}{\mathv \& r\k const \mathv \& v\k const \mathv \& w}
{adds two \BF{math\_vector}s \MATH{v} and \MATH{w} componentwise and stores 
the result in \MATH{r}.}

\fcode{void}{add}{\mathv \& r\k const \mathv \& v\k const T \& \MATH{\alpha}}
{adds \MATH{\alpha} from the right to each component of \BF{math\_vector} 
\MATH{v} and stores the result in~\MATH{r}.}

\fcode{void}{add}{\mathv \& r\k const T \& \MATH{\alpha}\k const \mathv \& v}
{adds \MATH{\alpha} from the left to each component of \BF{math\_vector} 
\MATH{v} and stores the result in~\MATH{r}.}

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

\SSTITLE{Subtraction}
\fcode{void}{subtract}{\mathv \& r\k const \mathv \&  v\k const \mathv \& w}
{subtracts \BF{math\_vector} \MATH{w} from \MATH{v} componentwise and stores 
the result in \MATH{r}.}

\fcode{void}{subtract}{\mathv \& r\k const \mathv \& v\k const T \& 
\MATH{\alpha}}
{subtracts \MATH{\alpha} from each component of \BF{math\_vector} \MATH{v} and 
stores the result in \MATH{r}.}

\fcode{void}{subtract}{\mathv \& r\k const T \& \MATH{\alpha}\k 
const \mathv \& v}
{subtracts successively each component of \BF{math\_vector} \MATH{v} from 
\MATH{\alpha} and stores the result in \MATH{r}.}

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

\SSTITLE{Multiplication}
\fcode{void}{multiply}{T \& res\k const \mathv \& v\k const \mathv \& w}
{stores the inner product of \MATH{v} and \MATH{w} in \MATH{res}.}

\fcode{void}{multiply}{\mathv \& r\k const \mathv \& v\k const T \& 
\MATH{\alpha}}
{multiplies each component of \BF{math\_vector} \MATH{v} from the right by 
\MATH{\alpha} and stores the result in \MATH{r}.}

\fcode{void}{multiply}{\mathv \& r\k const T \& \MATH{\alpha}\k 
const \mathv \& v}
{multiplies each component of \BF{math\_vector} \MATH{v} from the left by 
\MATH{\alpha} and stores the result in \MATH{r}.}

\fcode{void}{compwise\_multiply}{\mathv \& r\k const \mathv \& v\k 
const \mathv \& w}
{multiplies two \BF{math\_vector}s \MATH{v} and \MATH{w} componentwise and 
stores the result in \MATH{r}.}

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

\SSTITLE{Division}
\fcode{void}{divide}{\mathv \& r\k const \mathv \& v\k const T \& 
\MATH{\alpha}}
{divides each component of \BF{math\_vector} \MATH{v} by \MATH{\alpha} and 
stores the result in \MATH{r}.}

\fcode{void}{compwise\_divide}{\mathv \& r\k const \mathv \& v\k const \mathv \& w}
{divides \BF{math\_vector} \MATH{v} by \MATH{w} componentwise and stores the 
result in \MATH{r}.}

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

\SSTITLE{Negation}
\fcode{void}{negate}{\mathv \& r\k const \mathv v}
{negates the \BF{math\_vector} \MATH{v} componentwise and stores the result 
in \MATH{r}.}

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

\STITLE{Sum of squares}
\fcode{T}{v.sum\_of\_squares}{}
{returns the sum of the squares of elements of vector \MATH{v}.}

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

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

\COMP
The  binary operators \TT{==} and \TT{!=} are overloaded and can be used for 
componentwise comparison. Let \MATH{v} be an instance of type \mathv.

\cfcode{bool}{v.equal}{const \mathv \& w}
{returns \TRUE\ if the vectors \MATH{v} and \MATH{w} are equal in each 
component, \FALSE\ otherwise.}

\fcode{bool}{equal}{const \mathv \& v\k const \mathv \& w}
{returns \TRUE\ if the vectors \MATH{v} and \MATH{w} are equal in each 
component, \FALSE\ otherwise.}

\cfcode{bool}{v.unequal}{const \mathv \& w}
{returns \TRUE\ if the two vectors \MATH{v} and \MATH{w} differ in at least 
one component, \FALSE\ otherwise.}

\fcode{bool}{unequal}{const \mathv \& v\k const \mathv \& w}
{returns \TRUE\ if the two vectors \MATH{v} and \MATH{w} differ in at least 
one component, \FALSE\ otherwise.}

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

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

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

\NOTES
\begin{enumerate}
\item As described in the template introduction (see page \pageref{template_introduction})
for using an instance of type \mathv the type \BF{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{=}, 
\item the multiplication operator \TT{*}, 
\item the addition operator \TT{+}, 
\item the division operator \TT{/}, 
\item the subtraction operator \TT{-}, 
\item the unary minus \TT{-} and 
\item the equal operator \TT{==}.
\end{itemize}
\item Beware of the use of 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 \MATH{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{enumerate}

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

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

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

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

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

   w = u + v;
   cout << w << u - w << (v + w)*10 << 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}

