Next: Rational Approximations, Previous: Terminal Input, Up: Basic Input and Output

#### 14.1.3 Simple File I/O

The `save` and `load` commands allow data to be written to and read from disk files in various formats. The default format of files written by the `save` command can be controlled using the functions `default_save_options` and `save_precision`.

As an example the following code creates a 3-by-3 matrix and saves it to the file ``myfile.mat`'.

         A = [ 1:3; 4:6; 7:9 ];
         save myfile.mat A

Once one or more variables have been saved to a file, they can be read into memory using the `load` command.

         load myfile.mat
         A
              -| A =
              -|
              -|    1   2   3
              -|    4   5   6
              -|    7   8   9

— Command: save options file v1 v2 ...

> Save the named variables v1, v2, ..., in the file file. The special filename ``-`' can be used to write the output to your terminal. If no variable names are listed, Octave saves all the variables in the current scope. Valid options for the `save` command are listed in the following table. Options that modify the output format override the format specified by `default_save_options`.

> If save is invoked using the functional form

>               save ("-option1", ..., "file", "v1", ...)

> then the options, file, and variable name arguments (v1, ...) must be specified as character strings.

> `-ascii`
>   Save a single matrix in a text file.
> `-binary`
>   Save the data in Octave's binary data format.
> `-float-binary`
>   Save the data in Octave's binary data format but only using single precision. You should use this format only if you know that all the values to be saved can be represented in single precision.
> `-V7`
> `-v7`
> `-7`
> `-mat7-binary`
>   Save the data in Matlab's v7 binary data format.
> `-V6`
> `-v6`
> `-6`
> `-mat`
> `-mat-binary`
>   Save the data in Matlab's v6 binary data format.
> `-V4`
> `-v4`
> `-4`
> `-mat4-binary`
>   Save the data in the binary format written by Matlab version 4.
> `-hdf5`
>   Save the data in HDF5 format. (HDF5 is a free, portable binary format developed by the National Center for Supercomputing Applications at the University of Illinois.)
> `-float-hdf5`
>   Save the data in HDF5 format but only using single precision. You should use this format only if you know that all the values to be saved can be represented in single precision.
> `-zip`
> `-z`
>   Use the gzip algorithm to compress the file. This works equally on files that are compressed with gzip outside of octave, and gzip can equally be used to convert the files for backward compatibility.

> The list of variables to save may include wildcard patterns containing the following special characters:

> `?`
>   Match any single character.
> `*`
>   Match zero or more characters.
> `[` list`]`
>   Match the list of characters specified by list. If the first character is `!` or `^`, match all characters except those specified by list. For example, the pattern ``[a-zA-Z]`' will match all lower and upper case alphabetic characters.
> `-text`
>   Save the data in Octave's text data format.

> Except when using the Matlab binary data file format, saving global variables also saves the global status of the variable, so that if it is restored at a later time using ``load`', it will be restored as a global variable.

> The command

>               save -binary data a b*

> saves the variable ``a`' and all variables beginning with ``b`' to the file `data` in Octave's binary format.

— Command: load options file v1 v2 ...

> Load the named variables v1, v2, ..., from the file file. As with `save`, you may specify a list of variables and `load` will only extract those variables with names that match. For example, to restore the variables saved in the file `data`, use the command

>               load data

> If load is invoked using the functional form

>               load ("-option1", ..., "file", "v1", ...)

> then the options, file, and variable name arguments (v1, ...) must be specified as character strings.

> If a variable that is not marked as global is loaded from a file when a global symbol with the same name already exists, it is loaded in the global symbol table. Also, if a variable is marked as global in a file and a local symbol exists, the local symbol is moved to the global symbol table and given the value from the file. Since it seems that both of these cases are likely to be the result of some sort of error, they will generate warnings.

> If invoked with a single output argument, Octave returns data instead of inserting variables in the symbol table. If the data file contains only numbers (TAB- or space-delimited columns), a matrix of values is returned. Otherwise, `load` returns a structure with members corresponding to the names of the variables in the file.

> The `load` command can read data stored in Octave's text and binary formats, and Matlab's binary format. It will automatically detect the type of file and do conversion from different floating point formats (currently only IEEE big and little endian, though other formats may added in the future).

> Valid options for `load` are listed in the following table.

> `-force`
>   The ``-force`' option is accepted but ignored for backward compatibility. Octave now overwrites variables currently in memory with the same name as those found in the file.
> `-ascii`
>   Force Octave to assume the file contains columns of numbers in text format without any header or other information. Data in the file will be loaded as a single numeric matrix with the name of the variable derived from the name of the file.
> `-binary`
>   Force Octave to assume the file is in Octave's binary format.
> `-mat`
> `-mat-binary`
> `-6`
> `-v6`
> `-7`
> `-v7`
>   Force Octave to assume the file is in Matlab's version 6 or 7 binary format.
> `-V4`
> `-v4`
> `-4`
> `-mat4-binary`
>   Force Octave to assume the file is in the binary format written by Matlab version 4.
> `-hdf5`
>   Force Octave to assume the file is in HDF5 format. (HDF5 is a free, portable binary format developed by the National Center for Supercomputing Applications at the University of Illinois.) Note that Octave can read HDF5 files not created by itself, but may skip some datasets in formats that it cannot support.
> `-import`
>   The ``-import`' is accepted but ignored for backward compatibility. Octave can now support multi-dimensional HDF data and automatically modifies variable names if they are invalid Octave identifiers.
> `-text`
>   Force Octave to assume the file is in Octave's text format.

There are three functions that modify the behavior of `save`.

— Built-in Function: val = default_save_options ()
— Built-in Function: old_val = default_save_options (new_val)

> Query or set the internal variable that specifies the default options for the `save` command, and defines the default format. Typical values include `"-ascii"`, `"-ascii -zip"`. The default value is `-ascii`.

> See also: save.

— Built-in Function: val = save_precision ()
— Built-in Function: old_val = save_precision (new_val)

> Query or set the internal variable that specifies the number of digits to keep when saving data in text format.

— Built-in Function: val = save_header_format_string ()
— Built-in Function: old_val = save_header_format_string (new_val)

> Query or set the internal variable that specifies the format string used for the comment line written at the beginning of text-format data files saved by Octave. The format string is passed to `strftime` and should begin with the character ``#`' and contain no newline characters. If the value of `save_header_format_string` is the empty string, the header comment is omitted from text-format data files. The default value is

>               "# Created by Octave VERSION, %a %b %d %H:%M:%S %Y %Z <USER@HOST>"

> See also: strftime.

— Built-in Function: native_float_format ()

> Return the native floating point format as a string

It is possible to write data to a file in a way much similar to the `disp` function for writing data to the screen. The `fdisp` works just like `disp` except its first argument is a file pointer as created by `fopen`. As an example, the following code writes to data ``myfile.txt`'.

         fid = fopen ("myfile.txt", "w");
         fdisp (fid, "3/8 is ");
         fdisp (fid, 3/8);
         fclose (fid);

See Opening and Closing Files, for details on how to use `fopen` and `fclose`.

— Built-in Function: fdisp (fid, x)

> Display the value of x on the stream fid. For example,

>               fdisp (stdout, "The value of pi is:"), fdisp (stdout, pi)

>                    -| the value of pi is:
>                    -| 3.1416

> Note that the output from `fdisp` always ends with a newline.

> See also: disp.