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

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

\NAME

\CLASS{file_vector< T >} \dotfill vectors with special file operations


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

\ABSTRACT

\code{file_vector< T >} is a class for doing simple file operations.  \code{T} is allowed to be
either a built-in type or a class.

According to the template introduction the class \code{file_vector< T >} is derived from the
class \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{file_vector< T >}.


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

\DESCRIPTION

A variable of type \code{file_vector< T >} contains the same components as a variable of type
\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{file_vector}.

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

\begin{fcode}{ct}{file_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}{file_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}{file_vector< T >}{const file_vector< T > & $w$}
  constructs a vector with capacity \code{w.size} initialized with the elements of $w$.
\end{fcode}

\begin{fcode}{ct}{file_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}{~file_vector< T >}{}
\end{fcode}


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

\IO

In the sequel \code{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 \code{fopen()}).

\begin{cfcode}{void}{$v$.print_to_file}{FILE *fp}
  writes a vector in text format to the file, which \code{fp} is pointing to.  The output is of the
  form ''$[ v_0 \dots v_n-1 ]$'', where $n$ is the size of $v$.  This function requires the
  member function \code{print_to_file()} for type \code{T}.
\end{cfcode}

\begin{fcode}{void}{$v$.scan_from_file}{FILE *fp}
  reads a vector in text format from the file, which \code{fp} is pointing to.  The vector must be
  stored as ''$[ v_0 \dots v_n-1 ]$''.  The size and capacity of $v$ will then be set to $n$.  If
  $v$ can not successfully be read, the \LEH will be invoked.  This function requires the member
  function \code{scan_from_file()} for type \code{T}.
\end{fcode}

\begin{cfcode}{void}{$v$.write_to_file}{FILE *fp}
  writes a vector in binary format to the file, which \code{fp} is pointing to.  First, the length of
  $v$ is written to the file.  Afterwards, the elements of $v$ are successively stored to \code{fp} by
  using the member function \code{write_to_file()} for elements of type \code{T}.
\end{cfcode}

\begin{fcode}{void}{$v$.read_from_file}{FILE *fp}
  reads a vector in binary format from the file, which \code{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 $v$ by using the function
  \code{v.set_capacity()}.  Then, the elements are successively read into $v$.  If $v$ can not
  successfully be read, the \LEH will be invoked.  This function requires the member function
  \code{read_from_file()} for type \code{T}.
\end{fcode}

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

\begin{cfcode}{void}{$v$.append_a}{FILE *fp}
  appends the elements of vector $v$ to another vector that is stored at the end of a text file.
  If \code{fp} indicates the beginning of a vector, this one will be extended by the elements of $v$.
  If \code{fp} is pointing to the end of a file, this function is equivalent to
  \code{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 $v$ can not
  successfully be written to the file, the \LEH will be invoked.
\end{cfcode}

\begin{cfcode}{void}{$v$.append_a}{FILE *fp, lidia_size_t $n$}
  appends the $n+1$-st element of $v$ to another vector that is stored at the end of a text
  file.  If \code{fp} indicates the beginning of a vector, this one will be extended by $v[n]$.
  If \code{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 $v$ can not successfully be written to the
  file, the \LEH will be invoked.
\end{cfcode}

\begin{cfcode}{void}{$v$.append_b}{FILE *fp}
  appends the elements of vector $v$ to another vector that is stored at the end of a binary
  file.  If \code{fp} indicates the beginning of a vector, this one will be extended by the elements
  of $v$.  If \code{fp} specifies the end of a file, this function is equivalent to
  \code{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 $v$ can not
  successfully be written to the file, the \LEH will be invoked.
\end{cfcode}

\begin{cfcode}{int}{$v$.append_b}{FILE *fp, lidia_size_t $n$}
  appends the $n+1$-st element of $v$ to another vector that is stored at the end of a binary
  file.  If \code{fp} indicates the beginning of a vector, this one will be extended by $v[n]$.
  If \code{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 $v$ can not successfully be written to
  the file, the \LEH will be invoked.
\end{cfcode}


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

\SSTITLE{Remark}

The read functions for type \code{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 ``\code{\bschar
  n}'' appended to a type \code{T} element by the print function must be read by the scan
function.


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

\SEEALSO

\SEE{base_vector}, \SEE{math_vector},
\SEE{sort_vector}


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

\NOTES

As described in the template introduction (see page \pageref{template_introduction}) for using
an instance of type \code{file_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 function \code{print_to_file(fp)} (i.e. writing in text-format),
\item the function \code{write_to_file(fp)} (i.e. binary-writing),
\item the function \code{scan_from_file(fp)} (i.e. reading in text-format)
and
\item the function \code{read_from_file(fp)} (i.e. binary-writing), where \code{fp} is of type
  \code{FILE *}.
\end{itemize}


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

\EXAMPLES

\begin{quote}
\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;
        return 1;
    }
    v.write_to_file(dz);

    fclose(dz);
    return 0;
}
\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
