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