[doc] gettext printf_conversion mprintf msprintf mfprintf pages updated & fixed
[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  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  * Copyright (C) 2021 - Samuel GOUGEON
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"
17           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
18           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
19           xmlns:scilab="http://www.scilab.org" xml:id="printf_conversion" xml:lang="en">
20     <refnamediv>
21         <refname>printf_conversion</refname>
22         <refpurpose>mprintf, msprintf, mfprintf C-format specifications
23         </refpurpose>
24     </refnamediv>
25     <refsection>
26         <title>Description</title>
27         <para>
28             Each conversion specification in the <literal>mprintf</literal> ,
29             <literal>msprintf</literal> , <literal>mfprintf</literal>
30             <literal>format</literal> string has the following syntax:
31         </para>
32         <itemizedlist>
33             <listitem>
34                 <para>A % (percent) sign.</para>
35             </listitem>
36             <listitem>
37                 <para>
38                     An optional integer n ≥ 1 followed by "$". n is the index of the input data
39                     to substitute to the placeholder, in the msprintf, mprintf .. list of input data.
40                     In a format string, placeholders are either all numbered or all non-numbered.
41                     A given numbered placeholder can be used only once in its C-format string
42                     (Scilab limitation).
43                 </para>
44             </listitem>
45             <listitem>
46                 <para>
47                     Zero or more <literal>options</literal>, which modify the
48                     meaning of the conversion specification. The following list contains
49                     the <literal>option</literal> characters and their meanings:
50                 </para>
51                 <table>
52                     <tr>
53                         <th>- :</th>
54                         <td>
55                             Left align, within the field, the result of the conversion.
56                         </td>
57                     </tr>
58                     <tr>
59                         <th>+ :</th>
60                         <td>
61                             Begin the result of a signed conversion with a sign (+ or -).
62                         </td>
63                     </tr>
64                     <tr>
65                         <td style="white-space:nowrap"><emphasis role="bold">' ' :</emphasis></td>
66                         <td>(space) Prefix a space character to the result if the
67                             first character of a signed conversion is not a sign. If both the
68                             (space) and + options appear, the (space) option is ignored.
69                         </td>
70                     </tr>
71                     <tr>
72                         <th># :</th>
73                         <td>
74                             Convert the value to an alternate form. For
75                             <literal>c</literal>, <literal>d</literal>, <literal>i</literal>,
76                             <literal>s</literal>, and <literal>u</literal> conversions, the
77                             <literal>#</literal> option has no effect. For
78                             <literal>o</literal> conversion, <literal>#</literal> increases
79                             the precision to force the first digit of the result to be a 0
80                             (zero). For <literal>x</literal> and <literal>X</literal>
81                             conversions, a nonzero result has 0x or 0X prefixed to it. For
82                             <literal>e, E, f, g,</literal> and <literal>G</literal>
83                             conversions, the result always contains a decimal point, even if
84                             no digits follow it. For <literal>g</literal> and
85                             <literal>G</literal> conversions, trailing zeros are not removed
86                             from the result.
87                         </td>
88                     </tr>
89                     <tr>
90                         <th>0 :</th>
91                         <td>
92                             Pad to the field width, using leading zeros (following
93                             any indication of sign or base) for <literal>d</literal>,
94                             <literal>i</literal>, <literal>o</literal>, <literal>u</literal>,
95                             <literal>x</literal>, <literal>X</literal>, <literal>e</literal>,
96                             <literal>E</literal>, <literal>f</literal>, <literal>g</literal>,
97                             and <literal>G</literal> conversions; no space padding is
98                             performed. If the <literal>0</literal> and <literal>\-</literal>
99                             (dash) flags both appear, the <literal>0</literal> flag is
100                             ignored. For <literal>d</literal>, <literal>i</literal>,
101                             <literal>o</literal> <literal>u</literal>, <literal>x</literal>,
102                             and <literal>X</literal> conversions, if a precision is specified,
103                             the <literal>0</literal> flag is also ignored.
104                         </td>
105                     </tr>
106                 </table>
107             </listitem>
108             <listitem>
109                 <para>
110                     An optional decimal digit string that specifies the minimum field
111                     width. If the converted value has fewer characters than the field width,
112                     the field is padded on the left to the length specified by the field
113                     width. If the left-adjustment option is specified, the field is padded on
114                     the right.
115                 </para>
116             </listitem>
117             <listitem>
118                 <para>
119                     An optional precision. The precision is given by a dot<literal>.</literal>
120                     followed by a decimal digit string. If no precision is given, the
121                     parameter is treated as 0 (zero). The precision specifies:
122                 </para>
123                 <itemizedlist>
124                     <listitem>
125                         The minimum number of digits to appear for <literal>d</literal>,
126                         <literal>u</literal>, <literal>o</literal>, <literal>x</literal>, or
127                         <literal>X</literal> conversions.
128                     </listitem>
129                     <listitem>
130                         The number of digits to appear after the decimal point for
131                         <literal>e</literal>, <literal>E</literal>, and <literal>f</literal>
132                         conversions.
133                     </listitem>
134                     <listitem>
135                         The maximum number of significant digits for
136                         <literal>g</literal> and <literal>G</literal> conversions.
137                     </listitem>
138                     <listitem>
139                         The maximum number of characters to be printed from a string in
140                         an <literal>s</literal> conversion.
141                     </listitem>
142                 </itemizedlist>
143             </listitem>
144             <listitem>
145                 <para>A character that indicates the type of conversion to be applied:
146                 </para>
147                 <table>
148                     <tr>
149                         <th>% :</th>
150                         <td>
151                             Performs no conversion. Prints %.
152                             <note>
153                                 This may be useful for instance to print percentages, or
154                                 to process some LaTeX expression including LaTeX comments
155                                 starting with "%", etc.
156                             </note>
157                         </td>
158                     </tr>
159                     <tr>
160                         <th>s :</th>
161                         <td>
162                             Accepts a string or boolean <literal>value</literal> and displays
163                             characters from the string to the end or the number of characters
164                             indicated by the precision is reached. If no precision is
165                             specified, all characters up to the end are displayed.
166                             UTF-8 extended characters are supported in input strings.
167                             Booleans are converted into 'T' or 'F'.
168                         </td>
169                     </tr>
170                     <tr>
171                         <th>c :</th>
172                         <td>
173                             Not supported.
174                         </td>
175                     </tr>
176                     <tr>
177                         <td colspan="2">
178                             All following conversions accept any decimal numerical or boolean
179                             input <literal>value</literal>. Only the real part of any input
180                             complex number is considered. Booleans are implicitly converted
181                             into 0 and 1.
182                         </td>
183                     </tr>
184                     <tr>
185                         <th>d,i :</th>
186                         <td>
187                             Converts the input <literal>value</literal> to a signed integer int32
188                             notation. Conversions for input |Numbers| ≥ 2^31 are not reliable.
189                             The precision specifies
190                             the minimum number of digits to appear. If the value being
191                             converted can be represented in fewer digits, it is expanded with
192                             leading zeros. The default precision is 1. The result of
193                             converting a zero value with a precision of zero is a null string.
194                             Specifying a field width with a zero as a leading character causes
195                             the field width value to be padded with leading zeros.
196                         </td>
197                     </tr>
198                     <tr>
199                         <th>u :</th>
200                         <td>
201                             Converts the input <literal>value</literal> to an unsigned integer
202                             uint32 notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
203                             The precision specifies the
204                             minimum number of digits to appear. If the value being converted
205                             can be represented in fewer digits, it is expanded with leading
206                             zeros. The default precision is 1. The result of converting a zero
207                             value with a precision of zero is a null string. Specifying a
208                             field width with a zero as the leading character causes the field
209                             width value to be padded with leading zeros.
210                         </td>
211                     </tr>
212                     <tr>
213                         <th>o :</th>
214                         <td>
215                             Converts the input <literal>value</literal> to an unsigned octal notation.
216                             Conversions for input |Numbers| ≥ 2^32 are not reliable.
217                             The precision specifies the minimum
218                             number of digits to appear. If the value being converted can be
219                             represented in fewer digits, it is expanded with leading zeros.
220                             The default precision is 1. The result of converting a zero value
221                             with a precision of zero is a null string. Specifying a field
222                             width with a zero as the leading character causes the field width
223                             value to be padded with leading zeros. An octal value for field
224                             width is not implied.
225                         </td>
226                     </tr>
227                     <tr>
228                         <th>x, X :</th>
229                         <td>
230                             Converts the input <literal>value</literal> to an unsigned hexadecimal
231                             notation. Conversions for input |Numbers| ≥ 2^32 are not reliable.
232                             The letters ``abcdef'' are used for the <literal>x</literal> conversion;
233                             the letters ``ABCDEF'' are used for the <literal>X</literal>
234                             conversion. The precision specifies the minimum number of digits
235                             to appear. If the value being converted can be represented in
236                             fewer digits, it is expanded with leading zeros. The default
237                             precision is 1. The result of converting a zero value with a
238                             precision of zero is a null string. Specifying a field width with
239                             a zero as the leading character causes the field width value to be
240                             padded with leading zeros.
241                         </td>
242                     </tr>
243                     <tr>
244                         <th>f :</th>
245                         <td>
246                             Converts the input <literal>value</literal> to a decimal notation in
247                             the format %[\-]<literal>ddd.ddd</literal>.
248                             The number of digits after the decimal point is equal to the precision
249                             specification.
250                             <itemizedlist>
251                                 <listitem>
252                                     If no precision is specified, six digits are output.
253                                 </listitem>
254                                 <listitem>
255                                     If the precision is zero, no decimal point appears and
256                                     the system outputs a number rounded to the integer nearest to
257                                     <literal>value</literal>.
258                                 </listitem>
259                                 <listitem>
260                                     If a decimal point is output, at least one digit is output before it.
261                                 </listitem>
262                             </itemizedlist>
263                         </td>
264                     </tr>
265                     <tr>
266                         <th>e, E :</th>
267                         <td>
268                             Converts the input <literal>value</literal> to the exponential
269                             form %[\-]<literal>d.ddde</literal>+/\-<literal>dd</literal>.
270                             There is one digit before the decimal point, and the number of
271                             digits after the decimal point is equal to the precision
272                             specification.
273                             <itemizedlist>
274                                 <listitem>
275                                     If no precision is specified, six digits are output.
276                                 </listitem>
277                                 <listitem>
278                                     If the precision is zero, no decimal point appears.
279                                 </listitem>
280                                 <listitem>
281                                     The <literal>E</literal> conversion character produces a
282                                     number with E instead of e before the exponent. The exponent
283                                     always contains at least two digits. If the value is zero, the
284                                     exponent is zero.
285                                 </listitem>
286                             </itemizedlist>
287                         </td>
288                     </tr>
289                     <tr>
290                         <td style="white-space:nowrap"><emphasis role="bold">g, G :</emphasis></td>
291                         <td>
292                             Converts the input <literal>value</literal> in the style of the
293                             <literal>e</literal>, <literal>E</literal>, or
294                             <literal>f</literal> conversion characters, with the precision
295                             specifying the number of significant digits.
296                             Trailing zeros are removed from the result.
297                             A decimal point appears only if it is followed by a digit.
298                             The style used depends on the value
299                             converted. Style <literal>e</literal> (<literal>E</literal>, if
300                             <literal>G</literal> is the flag used) results only if the
301                             exponent resulting from the conversion is less than -4, or if it
302                             is greater or equal to the precision.
303                         </td>
304                     </tr>
305                 </table>
306             </listitem>
307         </itemizedlist>
308         <para>A field width or precision can be indicated by an
309             <literal>*</literal> (asterisk) instead of a digit string. In this case,
310             an integer <literal>value</literal> parameter supplies the field width or
311             precision. The <literal>value</literal> parameter converted for output is
312             not fetched until the conversion letter is reached, so the parameters
313             specifying field width or precision must appear before the value to be
314             converted (if any).
315         </para>
316         <para>If the result of a conversion is wider than the field width, the
317             field is expanded to contain the converted result.
318         </para>
319         <para>The representation of the plus sign depends on whether the
320             <literal>+</literal> or (space) formatting option is specified.
321         </para>
322         <para>
323             The display of exponential form %e is platform dependent with a different
324             number of digits in exponent.
325             <informaltable border="1">
326                 <tr>
327                     <td>Platform</td>
328                     <td>Example: msprintf("%e",1.23e4)</td>
329                 </tr>
330                 <tr>
331                     <td>Windows</td>
332                     <td>1.23000e+004</td>
333                 </tr>
334                 <tr>
335                     <td>Linux/Mac OS</td>
336                     <td>1.23000e+04</td>
337                 </tr>
338             </informaltable>
339         </para>
340         <para>
341             <emphasis role="bold">Special escaped sequences</emphasis> are supported in Scilab
342             C-format strings:
343             <table>
344                 <tr>
345                     <th>\n :</th>
346                     <td>Go to Next line (line feed)</td>
347                 </tr>
348                 <tr>
349                     <th>\r :</th>
350                     <td>Return: go to the head of current line (for overprinting)</td>
351                 </tr>
352                 <tr>
353                     <th>\t :</th>
354                     <td>horizontal Tab</td>
355                 </tr>
356                 <tr>
357                     <th>\\ :</th>
358                     <td>print a backslash \</td>
359                 </tr>
360             </table>
361         </para>
362     </refsection>
363     <refsection>
364         <title>Examples</title>
365         <programlisting role="example"><![CDATA[
366 mprintf('a string: %s\n', 'Scilab');
367 mprintf('an integer: %d\n', 10);
368 mprintf('an integer: %4d\n', 10);
369 mprintf('a left justified integer: %-4d\n', 10);
370 mprintf('an integer converted to float: %#fd\n',10);
371 mprintf('an integer with a sign: %+4d\n', 10);
372 mprintf('an integer with a sign: %+4d\n', -10);
373 mprintf('an integer padded with zeros: %04d\n', 10);
374 mprintf('an unsigned integer: %u\n', 10);
375 mprintf('an unsigned integer: %4u\n', -10);
376 mprintf('an integer converted to hexadecimal: %x\n', 10);
377 mprintf('a float: %d\n', %pi);
378 mprintf('a float: %3.2d\n', %pi);
379 mprintf('a float (exponential form): %3.2e\n', %pi);
380 mprintf('a float (exponential form): %3.2g\n', %pi);
381 mprintf('a character: %c\n', 'a');
382 mprintf('a character: %c\n', 'aaa');
383      ]]></programlisting>
384         <para/>
385         <para>
386             With input booleans:
387         </para>
388         <programlisting role="example"><![CDATA[
389 mprintf("\n%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n" + ..
390           "%%d: %d,  %%u: %u,  %%o: %o,  %%f: %f,  %%e: %e,  %%s: %s\n", ..
391         %T, %T, %T, %T, %T, %T, %F, %F, %F, %F, %F, %F);
392      ]]></programlisting>
393         <screen><![CDATA[
394 %d: 1,  %u: 1,  %o: 1,  %f: 1.000000,  %e: 1.000000e+00,  %s: T
395 %d: 0,  %u: 0,  %o: 0,  %f: 0.000000,  %e: 0.000000e+00,  %s: F
396 ]]></screen>
397         <para/>
398         <para>
399             With numbered placeholders:
400         </para>
401         <programlisting role="example"><![CDATA[
402 mprintf("%2$s is %1$d-year old.\n", 32, "Peter");
403      ]]></programlisting>
404         <screen><![CDATA[
405 Peter is 32-year old.
406 ]]></screen>
407         <para/>
408         <para>
409             With escaped sequences and UTF-8 extended characters:
410         </para>
411         <programlisting role="example"><![CDATA[
412 mprintf("The path T:\\abc does not exist.\n");
413 mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
414      ]]></programlisting>
415         <screen><![CDATA[
416 --> mprintf("The path T:\\abc does not exist.\n");
417 The path T:\abc does not exist
418
419 --> mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
420 ABCDEfghijk αβδ εϵ  ζηθικλ
421 ]]></screen>
422     </refsection>
423     <refsection role="see also">
424         <title>See also</title>
425         <simplelist type="inline">
426             <member>
427                 <link linkend="mprintf">mprintf</link>
428             </member>
429             <member>
430                 <link linkend="mfprintf">mfprintf</link>
431             </member>
432             <member>
433                 <link linkend="msprintf">msprintf</link>
434             </member>
435         </simplelist>
436     </refsection>
437     <refsection role="history">
438         <title>History</title>
439         <revhistory>
440             <revision>
441                 <revnumber>6.1.0</revnumber>
442                 <revdescription>
443                     Numbered placeholders "%n$.." are supported.
444                 </revdescription>
445             </revision>
446             <revision>
447                 <revnumber>6.1.1</revnumber>
448                 <revdescription>
449                     Input boolean data can be converted.
450                 </revdescription>
451             </revision>
452         </revhistory>
453     </refsection>
454 </refentry>