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

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

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

\NAME
\basev \DOTFILL parameterized base vector class

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

\ABSTRACT
The class \basev realizes the concept of a vector as a more advanced array
\[v=(v_i)_{0\LE i<m}\IN T^m.\]
It allows to create vectors and offers elementary access functions. \BF{T}
is allowed to be either a built-in type or a class.

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

\DESCRIPTION
A variable \MATH{v} of type \basev consists of a 1-dimensional array 
\BF{T \TT{*}data}, an unsigned integer \BF{mode}, a float \BF{expansion\_ratio} as
well as two integers \BF{size} and \BF{capacity} which describe the length of the 
vector. We call the number of allocated elements the capacity of 
\MATH{v}. The size of the vector is the number of items actually used in 
\MATH{v}. Thus, this value will never decrease; neither will it exceed the 
capacity.

Both values can individually be changed for a vector \MATH{v} by using the 
functions \TT{v.set\_capacity()} and \TT{v.set\_size()}, respectively.

As an example, the declaration
\begin{quote}
base\_vector \LT int\GT\ \MATH{v}(10)
\end{quote}
will create a \BF{base\_vector} with 10 elements allocated, so 
\MATH{v.capacity = 10}. If we use the first \MATH{s} elements of \MATH{v} 
only, \MATH{s} will be the size of \MATH{v}. In our example, after the 
declaration, \MATH{v} has \MATH{v.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} has index 0 and the last one has index \MATH{v.size-1}.

Furthermore, a \BF{base\_vector} \MATH{v} can be of either fixed or 
expanding size. For so called fixed vectors one can only change the number 
of allocated items in the vector by using the member function 
\TT{v.set\_capacity()}. I.e. neither is it possible to access the vector 
at an index which is greater than the vector's capacity, nor may function 
\TT{v.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 by 
using the member function \TT{v.set\_size()} exceeds that value. The new 
amount of memory to be allocated in these cases will then be computed using 
the expansion\_ratio of the vector. This is a factor by which the required 
number of elements will be multiplied before actually reallocating memory. 
The value of this factor for a vector \MATH{v} is \MATH{2.0} by default and 
may be altered at any time using the member--function 
\TT{v.set\_exp\_ratio()}. The expansion\_ratio has to be at least \MATH{1.0}. 

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

In the following descriptions we use \MATH{v.size} to label the size and 
\MATH{v.capacity} to label the capacity of vector \MATH{v}. 

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

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

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

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

\fcode{ct}{\basev}{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}. If the array \MATH{a}
has less than \MATH{l} elements the \TT{lidia\_error\_handler} will be invoked.}

\fcode{dt}{\SIM \basev}{}{}

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

\ACCS
Let \MATH{v} be of type \basev. Note, that we start the numbering of elements 
of a \BF{base\_vector} with zero.

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

\SSTITLE{Access to the size}
\cfcode{lidia\_size\_t}{v.size}{}
{returns the size of \MATH{v}.}

\cfcode{lidia\_size\_t}{v.get\_size}{}
{returns the size of \MATH{v}.}

\fcode{void}{v.set\_size}{lidia\_size\_t s}
{sets the size of \MATH{v} to \MATH{s} if the capacity of \MATH{v} is large 
enough. If \MATH{s} exceeds \MATH{v.capacity} and \MATH{v} is of expanding 
size, new memory will be allocated by using the function 
\TT{v.set\_capacity()}. The number of elements allocated in that case is 
\MATH{v.exp\_ratio * s}. If these actions can not successfully be performed, 
the \TT{lidia\_error\_handler} will be invoked.}

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

\SSTITLE{Access to the capacity}
\cfcode{lidia\_size\_t}{v.capacity}{}
{returns the capacity of \MATH{v}.}

\cfcode{lidia\_size\_t}{v.get\_capacity}{}
{returns the capacity of \MATH{v}.}

\fcode{void}{v.set\_capacity}{lidia\_size\_t c}
{sets the capacity of \MATH{v} to \MATH{c} by allocating exactly \MATH{c} 
elements for \MATH{v}. Here, \MATH{c} must be a positive value. If \MATH{c} 
is \MATH{0}, the elements of \MATH{v} will be deleted. If an error occurs in 
this function, the \TT{lidia\_error\_handler} will be invoked.}

\fcode{void}{v.reset}{}
{deallocates the vector elements and sets \MATH{v.capacity} and 
\MATH{v.size} to zero.}

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

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

\SSTITLE{Access to the exp\_ratio}
\cfcode{float}{v.exp\_ratio}{}
{returns the expansion ratio of \MATH{v}.}

\cfcode{float}{v.get\_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 \MATH{e}. The value of \MATH{e} must 
be at least \MATH{1.0}. If \MATH{e} is invalid, the expansion ratio of 
\MATH{v} will be set to \MATH{1.0}.}

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

\SSTITLE{Access to the mode}
\cfcode{char}{v.get\_mode}{}
{returns the mode of \MATH{v}.}

\fcode{void}{v.set\_mode}{char m}
{sets mode of \MATH{v} to \MATH{m} which must be either of the two constants 
FIXED or EXPAND. If \MATH{m} differs from these values, the mode of \MATH{v} 
will be set to FIXED.}

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

\SSTITLE{Access to an element}
\fcode{T \&}{operator[]}{lidia\_size\_t i}
{If the mode of \MATH{v} is FIXED, the operator returns a reference to the 
\MATH{i+1}-st element in \MATH{v}, provided that \MATH{i} is less than the 
capacity of the vector. If \MATH{i} is too large, the 
\TT{lidia\_error\_handler} will be invoked. The size of the vector will be 
set appropriately after a successful access (i.e. it will be set to \MATH{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 \MATH{i} is not less than its current value. This is done by a call of the 
function \TT{v.set\_capacity()}. The number of elements that will be allocated 
is \MATH{(i+1) * v.exp\_ratio}. Provided that the memory reallocation 
succeeds, the operator will return a reference to the \MATH{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 \MATH{i+1}-st element in \MATH{v} where
\MATH{i} has to be non-negative and less than \MATH{v.size}. Otherwise the 
\TT{lidia\_error\_handler} will be invoked.}

\cfcode{const T \&}{member}{lidia\_size\_t i}
{returns a constant reference to the \MATH{i+1}-st element in \MATH{v} where \MATH{i}
has to be non-negative and less than \MATH{v.size}. Otherwise the 
\TT{lidia\_error\_handler} will be invoked.}

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

\SSTITLE{Access to the array of datas}
\fcode{void}{v.set\_data}{const T *d\k lidia\_size\_t l)}
{copies \MATH{l} elements \MATH{d[0], \LDOTS, d[l-1]} to vector \MATH{v} and 
adjusts its capacity. If array \MATH{d} has less than \MATH{l}
elements the behaviour of this function is undefined.}

\cfcode{T *}{v.get\_data}{}
{returns a pointer to a copy of the vector elements.}

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

\ASGN
Let \MATH{v} be of type \basev. The operator \TT{=} is overloaded. For 
efficiency reasons the following functions are also implemented:

\fcode{void}{assign}{\basev \& v\k const \basev \& w}
{allocates \MATH{w.size} elements for \MATH{v} using \TT{v.set\_capacity()} 
and copies the entries of \MATH{w} into \MATH{v}.}

\fcode{void}{v.assign}{lidia\_size\_t at\k const \basev \& \MATH{w}\k 
lidia\_size\_t from\k lidia\_size\_t to}
{copies the elements \MATH{w[from], \LDOTS, w[to]} to vector \MATH{v}, 
starting at position \MATH{v[at]}. The corresponding elements of \MATH{v} 
will be overwritten. The size of \MATH{v} will be adjusted appropriately.}

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

\STITLE{Reverse Functions}
\fcode{void}{v.reverse}{}
{rearranges the elements of vector \MATH{v} in reverse order.}

\fcode{void}{v.reverse}{const \basev \& w}
{copies the elements of \MATH{w} in reverse order into vector \MATH{v}. If 
\MATH{w} does not alias \MATH{v}, \MATH{w.size} elements will be allocated 
for \MATH{v} by using \TT{v.set\_capacity()}.}

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

\STITLE{Swap Functions}
\fcode{void}{swap}{\basev \& v\k \basev \& w}
{exchanges the complete information of \MATH{v} and \MATH{w}.}

%% \fcode{void}{v.swap}{\basev \& w}
%% {exchanges the complete information of \MATH{v} and \MATH{w}.}

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

\STITLE{Concatenation}
\fcode{void}{v.concat}{const \basev u\k const \basev w}
{stores in \MATH{v} the concatenation of \MATH{u} and \MATH{w}. The capacity 
of \MATH{v} will be set to the sum of the sizes of the two vectors \MATH{u} and 
\MATH{w}.}

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

\STITLE{Shift Functions}
\fcode{void}{v.shift\_left}{lidia\_size\_t pos\k lidia\_size\_t num}
{moves the elements of \MATH{v} \MATH{num} positions to the left starting at 
\MATH{v[pos]} thus overwriting some preceeding entries. The size of 
\MATH{v} will be reduced by \MATH{num} using the function \TT{v.set\_size()}. The 
value of \MATH{num} may not exceed \MATH{pos}.}

\fcode{void}{v.shift\_right}{lidia\_size\_t pos\k lidia\_size\_t num}
{copies the elements of \MATH{v} \MATH{num} positions to the right starting at 
\MATH{v[pos]} possibly overwriting some succeeding elements in 
\MATH{v}. The size of \MATH{v} will be increased by \MATH{num} using the function 
\TT{v.set\_size()}.}

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

\STITLE{Insert Functions}
\fcode{void}{v.insert\_at}{const T \&x\k int pos}
{extends the size of vector \MATH{v} by 1 using \TT{v.set\_size()},
moves the elements of \MATH{v} one position to the right starting at
\MATH{v[pos]} and sets \MATH{v[pos] = x}. If \MATH{pos < 0} the
\TT{lidia\_error\_handler} will be invoked.}

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

\STITLE{Remove Functions}
\fcode{void}{remove\_from}{lidia\_size\_t pos\k lidia\_size\_t n = 1}
{removes \MATH{n} elements from the vector \MATH{v} starting at 
\MATH{v[pos]}. Any element in \MATH{v} succeeding \MATH{v[pos]} will be moved 
\MATH{n} positions to the left. After a successfull deletion, the size of 
vector \MATH{v} will be diminshed by \MATH{n} using \TT{v.set\_size()}.}

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

\IO
The \BF{istream} operator \TT{>>} and the \BF{ostream} operator \TT{<<} are 
overloaded. The \BF{istream} operator \TT{>>} reads vectors of the form 
''\MATH{[ v_{0} \LDOTS v_{n-1} ]}'' from istream.

The \BF{ostream} operator \TT{<<} outputs the vector in the above described 
format. 

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

\SEEALSO
\BF{file\_vector}, \BF{math\_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 \basev 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{<<} and 
\item the assignment operator \TT{=}.
\end{itemize}
\item As usually in ''C'' the numbering of the elements in a \BF{base\_vector} starts with zero. 
\end{enumerate}

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

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

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

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

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

   w.concat(u,v);

   cout << w ;
 }
\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}

