%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  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
%%


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

\NAME

\CLASS{math_vector< T >} \dotfill vectors with basic mathematical operations


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

\ABSTRACT

\code{math_vector< T >} 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 \code{math_vector< T >} is derived from \code{base_vector< T >}.  So you can apply all the
functions and operators of class \code{base_vector< T >} to instances of the type
\code{math_vector< T >}.  \code{T} is allowed to be either a built-in type or a class.


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

\DESCRIPTION

A variable of type \code{math_vector< T >} contains the same components as \code{base_vector< T
  >}.


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

\CONS

Each of the following constructors can get an additional parameter (\code{FIXED} or
\code{EXPAND}) to indicate the mode of the \code{math_vector}.

\begin{fcode}{ct}{math_vector< T >}{}
  constructs a vector with capacity 0.
\end{fcode}

\begin{fcode}{ct}{math_vector< T >}{lidia_size_t $c$}
  constructs a vector with capacity $c$ initialized with values generated by the default
  constructor for type \code{T}.
\end{fcode}

\begin{fcode}{ct}{math_vector< T >}{lidia_size_t $c$, lidia_size_t $s$}
  constructs a vector with capacity $c$ and size $s$ initialized with values generated by the
  default constructor for type \code{T}.
\end{fcode}

\begin{fcode}{ct}{math_vector< T >}{const math_vector< T > & $w$}
  constructs a vector with capacity $w.size$ initialized with the elements of $w$.
\end{fcode}

\begin{fcode}{ct}{math_vector< T >}{const T * $a$, lidia_size_t $l$}
  constructs a vector with capacity $l$ and size $l$ initialized with the first $l$ elements of
  the array $a$.
\end{fcode}

\begin{fcode}{dt}{~math_vector< T >}{}
\end{fcode}


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

\ARTH

The class \code{math_vector< T >} supports the following operators:

\begin{center}
  \begin{tabular}{|c|rcl|l|}\hline
    unary & & \codeit{op} & \code{math_vector< T >} & $\codeit{op} \in \{ \code{-} \}$ \\\hline
    binary & \code{math_vector< T >} & \codeit{op} & \code{math_vector< T >}
    & $\codeit{op} \in \{ \code{+}, \code{-}, \code{*} \}$ \\\hline
    binary with & \code{math_vector< T >} & \codeit{op} & \code{math_vector< T >}
    & $\codeit{op} \in \{ \code{+=}, \code{-=} \}$ \\
    assignment & & & & \\\hline
    binary & \code{math_vector< T >} & \codeit{op} & \code{T}
    & $\codeit{op} \in \{ \code{+}, \code{-}, \code{*}, \code{/} \}$ \\\hline
    binary & \code{T} & \codeit{op} & \code{math_vector< T >}
    & $\codeit{op} \in \{ \code{+}, \code{-}, \code{*} \}$ \\\hline
    binary with & \code{math_vector< T >} & \codeit{op} & \code{T}
    & $\codeit{op} \in \{\code{+=}, \code{-=}, \code{*=}, \code{/=} \}$ \\
    assignment & & & &\\\hline
  \end{tabular}
\end{center}

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 \LEH will be invoked.  If the
result vector has not the right size it will be adapted automatically.


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

\SSTITLE{Addition}

\begin{fcode}{void}{add}{math_vector< T > & $r$, const math_vector< T > & $v$, const math_vector< T > & $w$}
  adds two \code{math_vector}s $v$ and $w$ componentwise and stores the result in $r$.
\end{fcode}

\begin{fcode}{void}{add}{math_vector< T > & $r$, const math_vector< T > & $v$, const T & $\alpha$}
  adds $\alpha$ from the right to each component of \code{math_vector} $v$ and stores the result
  in $r$.
\end{fcode}

\begin{fcode}{void}{add}{math_vector< T > & $r$, const T & $\alpha$, const math_vector< T > & $v$}
  adds $\alpha$ from the left to each component of \code{math_vector} $v$ and stores the result
  in $r$.
\end{fcode}


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

\SSTITLE{Subtraction}

\begin{fcode}{void}{subtract}{math_vector< T > & $r$, const math_vector< T > &  $v$,
    const math_vector< T > & $w$}%
  subtracts \code{math_vector} $w$ from $v$ componentwise and stores the result in $r$.
\end{fcode}

\begin{fcode}{void}{subtract}{math_vector< T > & $r$, const math_vector< T > & $v$, const T & $\alpha$}
  subtracts $\alpha$ from each component of \code{math_vector} $v$ and stores the result in $r$.
\end{fcode}

\begin{fcode}{void}{subtract}{math_vector< T > & $r$, const T & $\alpha$, const math_vector< T > & $v$}
  subtracts successively each component of \code{math_vector} $v$ from $\alpha$ and stores the
  result in $r$.
\end{fcode}


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

\SSTITLE{Multiplication}

\begin{fcode}{void}{multiply}{T & $r$, const math_vector< T > & $v$, const math_vector< T > & $w$}
  stores the inner product of $v$ and $w$ in $r$.
\end{fcode}

\begin{fcode}{void}{multiply}{math_vector< T > & $r$, const math_vector< T > & $v$, const T & $\alpha$}
  multiplies each component of \code{math_vector} $v$ from the right by $\alpha$ and stores the
  result in $r$.
\end{fcode}

\begin{fcode}{void}{multiply}{math_vector< T > & $r$, const T & $\alpha$, const math_vector< T > & $v$}
  multiplies each component of \code{math_vector} $v$ from the left by $\alpha$ and stores the
  result in $r$.
\end{fcode}

\begin{fcode}{void}{compwise_multiply}{math_vector< T > & $r$, const math_vector< T > & $v$,
    const math_vector< T > & $w$}%
  multiplies two \code{math_vectors} $v$ and $w$ componentwise and stores the result in $r$.
\end{fcode}


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

\SSTITLE{Division}

\begin{fcode}{void}{divide}{math_vector< T > & $r$, const math_vector< T > & $v$, const T & $\alpha$}
  divides each component of \code{math_vector} $v$ by $\alpha$ and stores the result in $r$.
\end{fcode}

\begin{fcode}{void}{compwise_divide}{math_vector< T > & $r$, const math_vector< T > & $v$,
    const math_vector< T > & $w$}%
  divides \code{math_vector} $v$ by $w$ componentwise and stores the result in $r$.
\end{fcode}


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

\SSTITLE{Negation}

\begin{fcode}{void}{negate}{math_vector< T > & $r$, const math_vector< T > $v$}
  negates the \code{math_vector} $v$ componentwise and stores the result in $r$.
\end{fcode}


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

\STITLE{Sum of squares}

\begin{fcode}{T}{$v$.sum_of_squares}{}
  returns the sum of the squares of elements of vector $v$.
\end{fcode}

\begin{fcode}{T}{sum_of_squares}{const math_vector< T > & $v$}
  returns the sum of the squares of elements of vector $v$.
\end{fcode}


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

\COMP

The binary operators \code{==} and \code{!=} are overloaded and can be used for componentwise
comparison.  Let $v$ be an instance of type \code{math_vector< T >}.

\begin{cfcode}{bool}{$v$.equal}{const math_vector< T > & $w$}
  returns \TRUE if the vectors $v$ and $w$ are equal in each component, \FALSE otherwise.
\end{cfcode}

\begin{fcode}{bool}{equal}{const math_vector< T > & $v$, const math_vector< T > & $w$}
  returns \TRUE if the vectors $v$ and $w$ are equal in each component, \FALSE otherwise.
\end{fcode}

\begin{cfcode}{bool}{$v$.unequal}{const math_vector< T > & $w$}
  returns \TRUE if the two vectors $v$ and $w$ differ in at least one component, \FALSE
  otherwise.
\end{cfcode}

\begin{fcode}{bool}{unequal}{const math_vector< T > & $v$, const math_vector< T > & $w$}
  returns \TRUE if the two vectors $v$ and $w$ differ in at least one component, \FALSE
  otherwise.
\end{fcode}


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

\SEEALSO

\SEE{base_vector}, \SEE{file_vector},
\SEE{sort_vector}


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

\NOTES

\begin{enumerate}
\item
As described in the template introduction
(see page \pageref{template_introduction}) for using an instance of
type \code{math_vector< T >} the type \code{T} has to have at least
\begin{itemize}
\item a swap function \code{void swap(T &, T&)},
\item the input operator \code{>>},
\item the output operator \code{<<},
\item the assignment operator \code{=},
\item the multiplication operator \code{*},
\item the addition operator \code{+},
\item the division operator \code{/},
\item the subtraction operator \code{-},
\item the unary minus \code{-} and
\item the equal operator \code{==}.
\end{itemize}
\item Beware of the use of expanding vectors.  Unpredictable errors might occur in situations
  like the following.  Consider the statement
\begin{verbatim}
          add ( v[2] , v[1] , a );
\end{verbatim}
  for a vector $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 $v$.  The latter might change the address of v[1] and thus invalidate the
  previously stored value.
\end{enumerate}


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

\EXAMPLES

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

int 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}
\end{quote}

For further examples please refer to \path{LiDIA/src/templates/vector/vector_appl.cc}


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

\AUTHOR

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