<html lang="en">
<head>
<title>Formatted Input - GNU Octave</title>
<meta http-equiv="Content-Type" content="text/html">
<meta name="description" content="GNU Octave">
<meta name="generator" content="makeinfo 4.13">
<link title="Top" rel="start" href="index.html#Top">
<link rel="up" href="C_002dStyle-I_002fO-Functions.html#C_002dStyle-I_002fO-Functions" title="C-Style I/O Functions">
<link rel="prev" href="Other-Output-Conversions.html#Other-Output-Conversions" title="Other Output Conversions">
<link rel="next" href="Input-Conversion-Syntax.html#Input-Conversion-Syntax" title="Input Conversion Syntax">
<link href="http://www.gnu.org/software/texinfo/" rel="generator-home" title="Texinfo Homepage">
<meta http-equiv="Content-Style-Type" content="text/css">
<style type="text/css"><!--
pre.display { font-family:inherit }
pre.format { font-family:inherit }
pre.smalldisplay { font-family:inherit; font-size:smaller }
pre.smallformat { font-family:inherit; font-size:smaller }
pre.smallexample { font-size:smaller }
pre.smalllisp { font-size:smaller }
span.sc { font-variant:small-caps }
span.roman { font-family:serif; font-weight:normal; }
span.sansserif { font-family:sans-serif; font-weight:normal; }
--></style>
</head>
<body>
<div class="node">
<a name="Formatted-Input"></a>
<p>
Next: <a rel="next" accesskey="n" href="Input-Conversion-Syntax.html#Input-Conversion-Syntax">Input Conversion Syntax</a>,
Previous: <a rel="previous" accesskey="p" href="Other-Output-Conversions.html#Other-Output-Conversions">Other Output Conversions</a>,
Up: <a rel="up" accesskey="u" href="C_002dStyle-I_002fO-Functions.html#C_002dStyle-I_002fO-Functions">C-Style I/O Functions</a>
<hr>
</div>
<h4 class="subsection">14.2.11 Formatted Input</h4>
<p>Octave provides the <code>scanf</code>, <code>fscanf</code>, and <code>sscanf</code>
functions to read formatted input. There are two forms of each of these
functions. One can be used to extract vectors of data from a file, and
the other is more `C-like'.
<!-- fscanf src/file-io.cc -->
<p><a name="doc_002dfscanf"></a>
<div class="defun">
— Built-in Function: [<var>val</var>, <var>count</var>, <var>errmsg</var>] = <b>fscanf</b> (<var>fid, template, size</var>)<var><a name="index-fscanf-996"></a></var><br>
— Built-in Function: [<var>v1</var>, <var>v2</var>, <small class="dots">...</small>, <var>count</var>, <var>errmsg</var>] = <b>fscanf</b> (<var>fid, template, "C"</var>)<var><a name="index-fscanf-997"></a></var><br>
<blockquote><p>In the first form, read from <var>fid</var> according to <var>template</var>,
returning the result in the matrix <var>val</var>.
<p>The optional argument <var>size</var> specifies the amount of data to read
and may be one of
<dl>
<dt><code>Inf</code><dd>Read as much as possible, returning a column vector.
<br><dt><var>nr</var><dd>Read up to <var>nr</var> elements, returning a column vector.
<br><dt><code>[</code><var>nr</var><code>, Inf]</code><dd>Read as much as possible, returning a matrix with <var>nr</var> rows. If the
number of elements read is not an exact multiple of <var>nr</var>, the last
column is padded with zeros.
<br><dt><code>[</code><var>nr</var><code>, </code><var>nc</var><code>]</code><dd>Read up to <var>nr</var><code> * </code><var>nc</var> elements, returning a matrix with
<var>nr</var> rows. If the number of elements read is not an exact multiple
of <var>nr</var>, the last column is padded with zeros.
</dl>
<p class="noindent">If <var>size</var> is omitted, a value of <code>Inf</code> is assumed.
<p>A string is returned if <var>template</var> specifies only character
conversions.
<p>The number of items successfully read is returned in <var>count</var>.
<p>If an error occurs, <var>errmsg</var> contains a system-dependent error message.
<p>In the second form, read from <var>fid</var> according to <var>template</var>,
with each conversion specifier in <var>template</var> corresponding to a
single scalar return value. This form is more `C-like', and also
compatible with previous versions of Octave. The number of successful
conversions is returned in <var>count</var>
<p>See the Formatted Input section of the GNU Octave manual for a
complete description of the syntax of the template string.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dscanf.html#doc_002dscanf">scanf</a>, <a href="doc_002dsscanf.html#doc_002dsscanf">sscanf</a>, <a href="doc_002dfread.html#doc_002dfread">fread</a>, <a href="doc_002dfprintf.html#doc_002dfprintf">fprintf</a>, <a href="doc_002dfgets.html#doc_002dfgets">fgets</a>, <a href="doc_002dfputs.html#doc_002dfputs">fputs</a>.
</p></blockquote></div>
<!-- scanf src/file-io.cc -->
<p><a name="doc_002dscanf"></a>
<div class="defun">
— Built-in Function: [<var>val</var>, <var>count</var>, <var>errmsg</var>] = <b>scanf</b> (<var>template, size</var>)<var><a name="index-scanf-998"></a></var><br>
— Built-in Function: [<var>v1</var>, <var>v2</var>, <small class="dots">...</small>, <var>count</var>, <var>errmsg</var>]] = <b>scanf</b> (<var>template, "C"</var>)<var><a name="index-scanf-999"></a></var><br>
<blockquote><p>This is equivalent to calling <code>fscanf</code> with <var>fid</var> = <code>stdin</code>.
<p>It is currently not useful to call <code>scanf</code> in interactive
programs.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dfscanf.html#doc_002dfscanf">fscanf</a>, <a href="doc_002dsscanf.html#doc_002dsscanf">sscanf</a>, <a href="doc_002dprintf.html#doc_002dprintf">printf</a>.
</p></blockquote></div>
<!-- sscanf src/file-io.cc -->
<p><a name="doc_002dsscanf"></a>
<div class="defun">
— Built-in Function: [<var>val</var>, <var>count</var>, <var>errmsg</var>, <var>pos</var>] = <b>sscanf</b> (<var>string, template, size</var>)<var><a name="index-sscanf-1000"></a></var><br>
— Built-in Function: [<var>v1</var>, <var>v2</var>, <small class="dots">...</small>, <var>count</var>, <var>errmsg</var>] = <b>sscanf</b> (<var>string, template, "C"</var>)<var><a name="index-sscanf-1001"></a></var><br>
<blockquote><p>This is like <code>fscanf</code>, except that the characters are taken from the
string <var>string</var> instead of from a stream. Reaching the end of the
string is treated as an end-of-file condition. In addition to the values
returned by <code>fscanf</code>, the index of the next character to be read
is returned in <var>pos</var>.
<!-- Texinfo @sp should work but in practice produces ugly results for HTML. -->
<!-- A simple blank line produces the correct behavior. -->
<!-- @sp 1 -->
<p class="noindent"><strong>See also:</strong> <a href="doc_002dfscanf.html#doc_002dfscanf">fscanf</a>, <a href="doc_002dscanf.html#doc_002dscanf">scanf</a>, <a href="doc_002dsprintf.html#doc_002dsprintf">sprintf</a>.
</p></blockquote></div>
<p>Calls to <code>scanf</code> are superficially similar to calls to
<code>printf</code> in that arbitrary arguments are read under the control of
a template string. While the syntax of the conversion specifications in
the template is very similar to that for <code>printf</code>, the
interpretation of the template is oriented more towards free-format
input and simple pattern matching, rather than fixed-field formatting.
For example, most <code>scanf</code> conversions skip over any amount of
“white space” (including spaces, tabs, and newlines) in the input
file, and there is no concept of precision for the numeric input
conversions as there is for the corresponding output conversions.
Ordinarily, non-whitespace characters in the template are expected to
match characters in the input stream exactly.
<a name="index-conversion-specifications-_0028_0040code_007bscanf_007d_0029-1002"></a>
When a <dfn>matching failure</dfn> occurs, <code>scanf</code> returns immediately,
leaving the first non-matching character as the next character to be
read from the stream, and <code>scanf</code> returns all the items that were
successfully converted.
<a name="index-matching-failure_002c-in-_0040code_007bscanf_007d-1003"></a>
The formatted input functions are not used as frequently as the
formatted output functions. Partly, this is because it takes some care
to use them properly. Another reason is that it is difficult to recover
from a matching error.
</body></html>
