scanf/printf_conversion documentation corrected.
[scilab.git] / scilab / modules / output_stream / help / en_US / printf_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) XXXX-2008 - INRIA
5  *
6  * This file must be used under the terms of the CeCILL.
7  * This source file is licensed as described in the file COPYING, which
8  * you should have received as part of this distribution.  The terms
9  * are also available at
10  * http://www.cecill.info/licences/Licence_CeCILL_V2.1-en.txt
11  *
12  -->
13 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:id="printf_conversion" xml:lang="en">
14     <refnamediv>
15         <refname>printf_conversion</refname>
16         <refpurpose>mprintf, msprintf, mfprintf conversion
17             specifications
18         </refpurpose>
19     </refnamediv>
20     <refsection>
21         <title>Description</title>
22         <para>
23             Each conversion specification in the <literal>mprintf</literal> ,
24             <literal>msprintf</literal> , <literal>mfprintf</literal>
25             <literal>format</literal> parameter has the following syntax:
26         </para>
27         <itemizedlist>
28             <listitem>
29                 <para>A % (percent) sign.</para>
30             </listitem>
31             <listitem>
32                 <para>
33                     Zero or more <literal>options</literal>, which modify the
34                     meaning of the conversion specification. The following list contains
35                     the <literal>option</literal> characters and their meanings:
36                 </para>
37                 <itemizedlist>
38                     <listitem>
39                         <para>- : Left align, within the field, the result of the
40                             conversion.
41                         </para>
42                     </listitem>
43                     <listitem>
44                         <para>+ : Begin the result of a signed conversion with a sign (+
45                             or -).
46                         </para>
47                     </listitem>
48                     <listitem>
49                         <para>'space' : Prefix a space character to the result if the
50                             first character of a signed conversion is not a sign. If both the
51                             (space) and + options appear, the (space) option is ignored
52                         </para>
53                     </listitem>
54                     <listitem>
55                         <para># : Convert the value to an alternate form. For
56                             <literal>c</literal>, <literal>d</literal>, <literal>i</literal>,
57                             <literal>s</literal>, and <literal>u</literal> conversions, the
58                             <literal>#</literal> option has no effect. For
59                             <literal>o</literal> conversion, <literal>#</literal> increases
60                             the precision to force the first digit of the result to be a 0
61                             (zero). For <literal>x</literal> and <literal>X</literal>
62                             conversions, a nonzero result has 0x or 0X prefixed to it. For
63                             <literal>e, E, f, g,</literal> and <literal>G</literal>
64                             conversions, the result always contains a decimal point, even if
65                             no digits follow it. For <literal>g</literal> and
66                             <literal>G</literal> conversions, trailing zeros are not removed
67                             from the result.
68                         </para>
69                     </listitem>
70                     <listitem>
71                         <para>0 : Pad to the field width, using leading zeros (following
72                             any indication of sign or base) for <literal>d</literal>,
73                             <literal>i</literal>, <literal>o</literal>, <literal>u</literal>,
74                             <literal>x</literal>, <literal>X</literal>, <literal>e</literal>,
75                             <literal>E</literal>, <literal>f</literal>, <literal>g</literal>,
76                             and <literal>G</literal> conversions; no space padding is
77                             performed. If the <literal>0</literal> and <literal>\-</literal>
78                             (dash) flags both appear, the <literal>0</literal> flag is
79                             ignored. For <literal>d</literal>, <literal>i</literal>,
80                             <literal>o</literal> <literal>u</literal>, <literal>x</literal>,
81                             and <literal>X</literal> conversions, if a precision is specified,
82                             the <literal>0</literal> flag is also ignored.
83                         </para>
84                     </listitem>
85                 </itemizedlist>
86             </listitem>
87             <listitem>
88                 <para>An optional decimal digit string that specifies the minimum field
89                     width. If the converted value has fewer characters than the field width,
90                     the field is padded on the left to the length specified by the field
91                     width. If the left-adjustment option is specified, the field is padded on
92                     the right.
93                 </para>
94             </listitem>
95             <listitem>
96                 <para>
97                     An optional precision. The precision is given by a dot<literal>.</literal>
98                     followed by a decimal digit string. If no precision is given, the
99                     parameter is treated as 0 (zero). The precision specifies:
100                 </para>
101                 <itemizedlist>
102                     <listitem>
103                         <para>
104                             The minimum number of digits to appear for <literal>d</literal>,
105                             <literal>u</literal>, <literal>o</literal>, <literal>x</literal>, or
106                             <literal>X</literal> conversions
107                         </para>
108                     </listitem>
109                     <listitem>
110                         <para>The number of digits to appear after the decimal point for
111                             <literal>e</literal>, <literal>E</literal>, and <literal>f</literal>
112                             conversions
113                         </para>
114                     </listitem>
115                     <listitem>
116                         <para>The maximum number of significant digits for
117                             <literal>g</literal> and <literal>G</literal> conversions
118                         </para>
119                     </listitem>
120                     <listitem>
121                         <para>The maximum number of characters to be printed from a string in
122                             an <literal>s</literal> conversion
123                         </para>
124                     </listitem>
125                 </itemizedlist>
126             </listitem>
127             <listitem>
128                 <para>A character that indicates the type of conversion to be
129                     applied:
130                 </para>
131                 <itemizedlist>
132                     <listitem>
133                         <para>% : Performs no conversion. Displays %.</para>
134                     </listitem>
135                     <listitem>
136                         <para>
137                             d,i: Accepts an integer <literal>value</literal> and
138                             converts it to signed decimal notation. The precision specifies
139                             the minimum number of digits to appear. If the value being
140                             converted can be represented in fewer digits, it is expanded with
141                             leading zeros. The default precision is 1. The result of
142                             converting a zero value with a precision of zero is a null string.
143                             Specifying a field width with a zero as a leading character causes
144                             the field width value to be padded with leading zeros.
145                         </para>
146                     </listitem>
147                     <listitem>
148                         <para>
149                             u : Accepts an integer <literal>value</literal> and converts
150                             it to unsigned decimal notation. The precision specifies the
151                             minimum number of digits to appear. If the value being converted
152                             can be represented in fewer digits, it is expanded with leading
153                             zeros. The default precision is 1. The result of converting a zero
154                             value with a precision of zero is a null string. Specifying a
155                             field width with a zero as the leading character causes the field
156                             width value to be padded with leading zeros.
157                         </para>
158                     </listitem>
159                     <listitem>
160                         <para>
161                             o : Accepts an integer <literal>value</literal> and converts
162                             it to unsigned octal notation. The precision specifies the minimum
163                             number of digits to appear. If the value being converted can be
164                             represented in fewer digits, it is expanded with leading zeros.
165                             The default precision is 1. The result of converting a zero value
166                             with a precision of zero is a null string. Specifying a field
167                             width with a zero as the leading character causes the field width
168                             value to be padded with leading zeros. An octal value for field
169                             width is not implied.
170                         </para>
171                     </listitem>
172                     <listitem>
173                         <para>
174                             x, X : Accepts an integer <literal>value</literal> and
175                             converts it to unsigned hexadecimal notation. The letters
176                             ``abcdef'' are used for the <literal>x</literal> conversion; the
177                             letters ``ABCDEF'' are used for the <literal>X</literal>
178                             conversion. The precision specifies the minimum number of digits
179                             to appear. If the value being converted can be represented in
180                             fewer digits, it is expanded with leading zeros. The default
181                             precision is 1. The result of converting a zero value with a
182                             precision of zero is a null string. Specifying a field width with
183                             a zero as the leading character causes the field width value to be
184                             padded with leading zeros.
185                         </para>
186                     </listitem>
187                     <listitem>
188                         <para>
189                             f : Accepts a float or double <literal>value</literal> and
190                             converts it to decimal notation in the format
191                             %[\-]<literal>ddd.ddd</literal>. The number of digits after the
192                             decimal point is equal to the precision specification.
193                         </para>
194                         <itemizedlist>
195                             <listitem>
196                                 <para>If no precision is specified, six digits are
197                                     output.
198                                 </para>
199                             </listitem>
200                             <listitem>
201                                 <para>If the precision is zero, no decimal point appears and
202                                     the system outputs a number rounded to the integer nearest to
203                                     <literal>value</literal>.
204                                 </para>
205                             </listitem>
206                             <listitem>
207                                 <para>If a decimal point is output, at least one digit is
208                                     output before it.
209                                 </para>
210                             </listitem>
211                         </itemizedlist>
212                     </listitem>
213                     <listitem>
214                         <para>e, E : Accepts a real and converts it to the exponential
215                             form %[\-]<literal>d.ddde</literal>+/\-<literal>dd</literal>.
216                             There is one digit before the decimal point, and the number of
217                             digits after the decimal point is equal to the precision
218                             specification.
219                         </para>
220                         <itemizedlist>
221                             <listitem>
222                                 <para>If no precision is specified, six digits are
223                                     output.
224                                 </para>
225                             </listitem>
226                             <listitem>
227                                 <para>If the precision is zero, , no decimal point
228                                     appears.
229                                 </para>
230                             </listitem>
231                             <listitem>
232                                 <para>
233                                     The <literal>E</literal> conversion character produces a
234                                     number with E instead of e before the exponent. The exponent
235                                     always contains at least two digits. If the value is zero, the
236                                     exponent is zero.
237                                 </para>
238                             </listitem>
239                         </itemizedlist>
240                     </listitem>
241                     <listitem>
242                         <para>g, G : Accepts a real and converts it in the style of the
243                             <literal>e</literal>, <literal>E</literal>, or
244                             <literal>f</literal> conversion characters, with the precision
245                             specifying the number of significant digits. Trailing zeros are
246                             removed from the result. A decimal point appears only if it is
247                             followed by a digit. The style used depends on the value
248                             converted. Style <literal>e</literal> (<literal>E</literal>, if
249                             <literal>G</literal> is the flag used) results only if the
250                             exponent resulting from the conversion is less than -4, or if it
251                             is greater or equal to the precision.
252                         </para>
253                     </listitem>
254                     <listitem>
255                         <para>c : Accepts and displays an integer value converted to a
256                             character.
257                         </para>
258                     </listitem>
259                     <listitem>
260                         <para>
261                             s : Accepts a string <literal>value</literal> and displays
262                             characters from the string to the end or the number of characters
263                             indicated by the precision is reached. If no precision is
264                             specified, all characters up to the end are displayed.
265                         </para>
266                     </listitem>
267                 </itemizedlist>
268             </listitem>
269         </itemizedlist>
270         <para>A field width or precision can be indicated by an
271             <literal>*</literal> (asterisk) instead of a digit string. In this case,
272             an integer <literal>value</literal> parameter supplies the field width or
273             precision. The <literal>value</literal> parameter converted for output is
274             not fetched until the conversion letter is reached, so the parameters
275             specifying field width or precision must appear before the value to be
276             converted (if any).
277         </para>
278         <para>If the result of a conversion is wider than the field width, the
279             field is expanded to contain the converted result.
280         </para>
281         <para>The representation of the plus sign depends on whether the
282             <literal>+</literal> or (space) formatting option is specified.
283         </para>
284         <para>display of exponential form %e is platform dependent with a different number of digits in exponent.</para>
285         <informaltable border="1">
286             <tr>
287                 <td>Platform</td>
288                 <td>Example: msprintf("%e",1.23e4)</td>
289             </tr>
290             <tr>
291                 <td>Windows</td>
292                 <td>1.23000e+004</td>
293             </tr>
294             <tr>
295                 <td>Linux/Mac OS</td>
296                 <td>1.23000e+04</td>
297             </tr>
298         </informaltable>
299     </refsection>
300     <refsection>
301         <title>Examples</title>
302         <programlisting role="example"><![CDATA[
303 mprintf('a string: %s\n', 'Scilab');
304 mprintf('an integer: %d\n', 10);
305 mprintf('an integer: %4d\n', 10);
306 mprintf('a left justified integer: %-4d\n', 10);
307 mprintf('an integer converted to float: %#fd\n',10);
308 mprintf('an integer with a sign: %+4d\n', 10);
309 mprintf('an integer with a sign: %+4d\n', -10);
310 mprintf('an integer padded with zeros: %04d\n', 10);
311 mprintf('an unsigned integer: %u\n', 10);
312 mprintf('an unsigned integer: %4u\n', -10);
313 mprintf('an integer converted to hexadecimal: %x\n', 10);
314 mprintf('a float: %d\n', %pi);
315 mprintf('a float: %3.2d\n', %pi);
316 mprintf('a float (exponential form): %3.2e\n', %pi);
317 mprintf('a float (exponential form): %3.2g\n', %pi);
318 mprintf('a character: %c\n', 'a');
319 mprintf('a character: %c\n', 'aaa');
320  ]]></programlisting>
321     </refsection>
322     <refsection role="see also">
323         <title>See Also</title>
324         <simplelist type="inline">
325             <member>
326                 <link linkend="mprintf">mprintf</link>
327             </member>
328             <member>
329                 <link linkend="mfprintf">mfprintf</link>
330             </member>
331             <member>
332                 <link linkend="msprintf">msprintf</link>
333             </member>
334         </simplelist>
335     </refsection>
336 </refentry>