%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
%%
%%  file_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\filev{\BF{file\_vector\TEMPL{T}} }

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

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

\NAME
\filev \DOTFILL vectors with special file operations 

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

\ABSTRACT
\filev is a class for doing simple file operations. \BF{T} is allowed to be
either a built-in type or a class.

According to the template introduction the class \filev is derived from 
the class \basev. So you can apply all the functions and operators of class \basev to 
instances of the type \filev.

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

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

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

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

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

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

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

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

\IO
In the sequel \MATH{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{void}{v.print\_to\_file}{FILE *fp}
{writes a vector in text format to the file, which \MATH{fp} is pointing to. 
The output is of the form ''\MATH{[ v_{0} \LDOTS v_{n-1} ]}'', where \MATH{n} is 
the size of \MATH{v}. This function requires the member function 
\TT{print\_to\_file()} for type \BF{T}.}

\fcode{void}{v.scan\_from\_file}{FILE *fp}
{reads a vector in text format from the file, which \MATH{fp} is pointing to.
The vector must be stored as ''\MATH{[ v_{0} \LDOTS 
v_{n-1} ]}''. The size and capacity of \MATH{v} will then be set to \MATH{n}. 
If \MATH{v} can not successfully be read, the \TT{lidia\_error\_handler} will 
be invoked. This function requires the member function 
\TT{scan\_from\_file()} for type \BF{T}.}

\cfcode{void}{v.write\_to\_file}{FILE *fp}
{writes a vector in binary format to the file, which \MATH{fp} is pointing to.
First, the length of \MATH{v} is written to the file.
Afterwards, the elements of \MATH{v} are successively stored to
\MATH{fp} by using the member function \TT{write\_to\_file()} for elements of type 
\BF{T}.}

\fcode{void}{v.read\_from\_file}{FILE *fp}
{reads a vector in binary format from the file, which \MATH{fp} is pointing to.
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 function 
\TT{v.set\_capacity()}. Then, the elements are successively read into 
\MATH{v}. If \MATH{v} can not successfully be read, the 
\TT{lidia\_error\_handler} will be invoked. This function requires the 
member function \TT{read\_from\_file()} for type \BF{T}.}

The 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{void}{v.append\_a}{FILE *fp}
{appends the elements of vector \MATH{v} to another vector that is stored at 
the end of a text file. If \MATH{fp} indicates the beginning of a vector, 
this one will be extended by the elements of \MATH{v}. If \MATH{fp} is 
pointing to the end of a file, this function is equivalent to 
\TT{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 not successfully be written to the file, 
the \TT{lidia\_error\_handler} will be invoked.}

\cfcode{void}{v.append\_a}{FILE *fp\k lidia\_size\_t n}
{appends the \MATH{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 \MATH{v[n]}. If \MATH{fp} specifies the 
end of a file, this function will add a vector of size \MATH{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 not successfully be written to the file, the 
\TT{lidia\_error\_handler} will be invoked.}

\cfcode{void}{v.append\_b}{FILE *fp}
{appends the elements of vector \MATH{v} to another vector that is stored at 
the end of a binary file. If \MATH{fp} indicates the beginning of a vector, 
this one will be extended by the elements of \MATH{v}. If \MATH{fp} specifies 
the end of a file, this function is equivalent to \TT{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 not successfully be written to the file, the \TT{lidia\_error\_handler} 
will be invoked.}

\cfcode{int}{v.append\_b}{FILE *fp\k lidia\_size\_t n}
{appends the \MATH{n+1}--st element of \MATH{v} to another vector that is 
stored at the end of a binary file. If \MATH{fp} indicates the beginning of 
a vector, this one will be extended by \MATH{v[n]}. If \MATH{fp} specifies the 
end of a file, this function will add a vector of size \MATH{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 not successfully be written to the file, the 
\TT{lidia\_error\_handler} will be invoked.}

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

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

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

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

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

\NOTES
As described in the template introduction (see page \pageref{template_introduction})
for using an instance of type \filev 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 function \TT{print\_to\_file(fp)} (i.e. writing in text--format),
\item the function \TT{write\_to\_file(fp)} (i.e. binary--writing), 
\item the function \TT{scan\_from\_file(fp)} (i.e. reading in text--format) 
and   
\item the function \TT{read\_from\_file(fp)} (i.e. binary--writing), where 
\TT{fp} is of type \BF{FILE *}. 
\end{itemize}

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

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

 int main()
 {
   file_vector <double> v;
   cin >> v;
  
   FILE *dz=fopen("LiDIA-OUTPUT","w");
   if (dz == NULL)
    {
     cout << "ERROR !! " << flush;
     exit(1);
    }
   v.write_to_file(dz);
 
   fclose(dz);
 }
\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}

