scanf/printf_conversion documentation corrected.
[scilab.git] / scilab / modules / fileio / help / en_US / scanf_conversion.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2008 - INRIA
5  * ...
6  *
7  * This file must be used under the terms of the CeCILL.
8  * This source file is licensed as described in the file COPYING, which
9  * you should have received as part of this distribution.  The terms
10  * are also available at
11  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
12  *
13  -->
14 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="scanf_conversion">
15     <refnamediv>
16         <refname>scanf_conversion</refname>
17         <refpurpose>mscanf, msscanf, mfscanf conversion specifications</refpurpose>
18     </refnamediv>
19     <refsection>
20         <title>Description</title>
21         <para>
22             Each conversion specification in the <varname>format</varname> parameter contains the following elements:
23         </para>
24         <itemizedlist>
25             <listitem>
26                 <para>
27                     the character <literal>%</literal> (percent sign);
28                 </para>
29             </listitem>
30             <listitem>
31                 <para>
32                     the optional assignment suppression character <literal>*</literal> (asterisk);
33                 </para>
34             </listitem>
35             <listitem>
36                 <para>
37                     an optional numeric maximum field width;
38                 </para>
39             </listitem>
40             <listitem>
41                 <para>
42                     a conversion code.
43                 </para>
44             </listitem>
45         </itemizedlist>
46         <para>
47             The conversion specification has the following syntax:
48         </para>
49         <para>
50             <literal>[*][width][size]convcode</literal>.
51         </para>
52         <para>
53             The results from the conversion are placed in <varname>v_i</varname> arguments unless you specify assignment suppression with <literal>*</literal> (asterisk). Assignment suppression provides a way to describe an input field that is to be skipped. The input field is a string of nonwhite-space characters. It extends to the next inappropriate character or until the field width, if specified, is exhausted.
54         </para>
55         <para>
56             The conversion code indicates how to interpret the input field.
57             You should not specify the <varname>v_i</varname> parameter for a
58             suppressed field. You can use the following conversion codes:
59         </para>
60         <variablelist>
61             <varlistentry>
62                 <term>%</term>
63                 <listitem>
64                     <para>
65                         accepts a single <literal>%</literal> (percent sign) input at this point; no assignment is done.
66                     </para>
67                 </listitem>
68             </varlistentry>
69             <varlistentry>
70                 <term>d, i</term>
71                 <listitem>
72                     <para>accepts a decimal integer.</para>
73                 </listitem>
74             </varlistentry>
75             <varlistentry>
76                 <term>u</term>
77                 <listitem>
78                     <para>accepts an unsigned decimal integer.</para>
79                 </listitem>
80             </varlistentry>
81             <varlistentry>
82                 <term>o</term>
83                 <listitem>
84                     <para>accepts an octal integer.</para>
85                 </listitem>
86             </varlistentry>
87             <varlistentry>
88                 <term>x</term>
89                 <listitem>
90                     <para>accepts a hexadecimal integer.</para>
91                 </listitem>
92             </varlistentry>
93             <varlistentry>
94                 <term>e, f, g</term>
95                 <listitem>
96                     <para>
97                         accepts a floating-point number. The next field is converted accordingly and stored through the corresponding parameter, which should be a pointer to a float. The input format for floating-point numbers is a string of digits, with the following optional characteristics:
98                     </para>
99                     <itemizedlist>
100                         <listitem>
101                             <para>
102                                 it can be a signed value;
103                             </para>
104                         </listitem>
105                         <listitem>
106                             <para>
107                                 it can be an exponential value, containing a decimal point followed by an exponent field, which consists of an <literal>E</literal> or an <literal>e</literal> followed by an (optionally signed) integer;
108                             </para>
109                         </listitem>
110                         <listitem>
111                             <para>
112                                 it can be one of the special values <constant>%inf</constant>, <constant>%nan</constant>;
113                             </para>
114                         </listitem>
115                     </itemizedlist>
116                 </listitem>
117             </varlistentry>
118             <varlistentry>
119                 <term>s</term>
120                 <listitem>
121                     <para>accepts a string of characters.</para>
122                 </listitem>
123             </varlistentry>
124             <varlistentry>
125                 <term>c</term>
126                 <listitem>
127                     <para>
128                         character value is expected. The normal skip over white-space is suppressed.
129                     </para>
130                 </listitem>
131             </varlistentry>
132             <varlistentry>
133                 <term>%lg</term>
134                 <listitem>
135                     <para>gets value as a double.</para>
136                 </listitem>
137             </varlistentry>
138         </variablelist>
139     </refsection>
140     <refsection role="see also">
141         <title>See Also</title>
142         <simplelist type="inline">
143             <member>
144                 <link linkend="msscanf">msscanf</link>
145             </member>
146             <member>
147                 <link linkend="mfscanf">mfscanf</link>
148             </member>
149             <member>
150                 <link linkend="mscanf">mscanf</link>
151             </member>
152             <member>
153                 <link linkend="printf_conversion">printf_conversion</link>
154             </member>
155         </simplelist>
156     </refsection>
157 </refentry>