\section{LOAD Load Variables From A File}

\subsection{Usage}

Loads a set of variables from a file in a machine independent format.
The \verb|load| function takes one argument:
\begin{verbatim}
  load filename,
\end{verbatim}
or alternately,
\begin{verbatim}
  load('filename')
\end{verbatim}
This command is the companion to \verb|save|.  It loads the contents of the
file generated by \verb|save| back into the current context.  Global and 
persistent variables are also loaded and flagged appropriately.  By
default, FreeMat assumes that files that end in a \verb|.mat| or \verb|.MAT|
extension are MATLAB-formatted files.  Also, FreeMat assumes that 
files that end in \verb|.txt| or \verb|.TXT| are ASCII files. 
For other filenames, FreeMat first tries to open the file as a 
FreeMat binary format file (as created by the \verb|save| function).  
If the file fails to open as a FreeMat binary file, then FreeMat 
attempts to read it as an ASCII file.  

You can force FreeMat to assume a particular format for the file
by using alternate forms of the \verb|load| command.  In particular,
\begin{verbatim}
  load -ascii filename
\end{verbatim}
will load the data in file \verb|filename| as an ASCII file (space delimited
numeric text) loaded into a single variable in the current workspace
with the name \verb|filename| (without the extension).

For MATLAB-formatted data files, you can use
\begin{verbatim}
  load -mat filename
\end{verbatim}
which forces FreeMat to assume that \verb|filename| is a MAT-file, regardless
of the extension on the filename.

You can also specify which variables to load from a file (not from 
an ASCII file - only single 2-D variables can be successfully saved and
retrieved from ASCII files) using the additional syntaxes of the \verb|load|
command.  In particular, you can specify a set of variables to load by name
\begin{verbatim}
  load filename Var_1 Var_2 Var_3 ...
\end{verbatim}
where \verb|Var_n| is the name of a variable to load from the file.  
Alternately, you can use the regular expression syntax
\begin{verbatim}
  load filename -regexp expr_1 expr_2 expr_3 ...
\end{verbatim}
where \verb|expr_n| is a regular expression (roughly as expected by \verb|regexp|).
Note that a simpler regular expression mechanism is used for this syntax
than the full mechanism used by the \verb|regexp| command.

Finally, you can use \verb|load| to create a variable containing the 
contents of the file, instead of automatically inserting the variables
into the curent workspace.  For this form of \verb|load| you must use the
function syntax, and capture the output:
\begin{verbatim}
  V = load('arg1','arg2',...)
\end{verbatim}
which returns a structure \verb|V| with one field for each variable
retrieved from the file.  For ASCII files, \verb|V| is a double precision
matrix.

\subsection{Example}

Here is a simple example of \verb|save|/\verb|load|.  First, we save some variables to a file.
\begin{verbatim}
--> D = {1,5,'hello'};
--> s = 'test string';
--> x = randn(512,1);
--> z = zeros(512);
--> who
  Variable Name      Type   Flags             Size
              D      cell                    [1 3]
              s    string                    [1 11]
              x    double                    [512 1]
              z    double                    [512 512]
--> save loadsave.dat

\end{verbatim}
Next, we clear the variables, and then load them back from the file.
\begin{verbatim}
--> clear D s x z
--> who
  Variable Name      Type   Flags             Size
            ans    double                    [0 0]
--> load loadsave.dat
--> who
  Variable Name      Type   Flags             Size
              D      cell                    [1 3]
            ans    double                    [0 0]
              s    string                    [1 11]
              x    double                    [512 1]
              z    double                    [512 512]

\end{verbatim}
