1 <?xml version="1.0" encoding="UTF-8"?>
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
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.
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">
21 <refname>printf_conversion</refname>
22 <refpurpose>mprintf, msprintf, mfprintf C-format specifications
26 <title>Description</title>
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:
34 <para>A % (percent) sign.</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
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:
55 Left align, within the field, the result of the conversion.
61 Begin the result of a signed conversion with a sign (+ or -).
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.
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
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.
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
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:
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.
130 The number of digits to appear after the decimal point for
131 <literal>e</literal>, <literal>E</literal>, and <literal>f</literal>
135 The maximum number of significant digits for
136 <literal>g</literal> and <literal>G</literal> conversions.
139 The maximum number of characters to be printed from a string in
140 an <literal>s</literal> conversion.
145 <para>A character that indicates the type of conversion to be applied:
151 Performs no conversion. Prints %.
153 This may be useful for instance to print percentages, or
154 to process some LaTeX expression including LaTeX comments
155 starting with "%", etc.
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'.
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
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.
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.
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.
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.
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
252 If no precision is specified, six digits are output.
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>.
260 If a decimal point is output, at least one digit is output before it.
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
275 If no precision is specified, six digits are output.
278 If the precision is zero, no decimal point appears.
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
290 <td style="white-space:nowrap"><emphasis role="bold">g, G :</emphasis></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.
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
316 <para>If the result of a conversion is wider than the field width, the
317 field is expanded to contain the converted result.
319 <para>The representation of the plus sign depends on whether the
320 <literal>+</literal> or (space) formatting option is specified.
323 The display of exponential form %e is platform dependent with a different
324 number of digits in exponent.
325 <informaltable border="1">
328 <td>Example: msprintf("%e",1.23e4)</td>
332 <td>1.23000e+004</td>
335 <td>Linux/Mac OS</td>
341 <emphasis role="bold">Special escaped sequences</emphasis> are supported in Scilab
346 <td>Go to Next line (line feed)</td>
350 <td>Return: go to the head of current line (for overprinting)</td>
354 <td>horizontal Tab</td>
358 <td>print a backslash \</td>
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');
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);
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
399 With numbered placeholders:
401 <programlisting role="example"><![CDATA[
402 mprintf("%2$s is %1$d-year old.\n", 32, "Peter");
405 Peter is 32-year old.
409 With escaped sequences and UTF-8 extended characters:
411 <programlisting role="example"><![CDATA[
412 mprintf("The path T:\\abc does not exist.\n");
413 mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
416 --> mprintf("The path T:\\abc does not exist.\n");
417 The path T:\abc does not exist
419 --> mprintf("abcdefghijk\tαβδ\tεϵ\tζηθικλ\rABCDE\n");
420 ABCDEfghijk αβδ εϵ ζηθικλ
423 <refsection role="see also">
424 <title>See also</title>
425 <simplelist type="inline">
427 <link linkend="mprintf">mprintf</link>
430 <link linkend="mfprintf">mfprintf</link>
433 <link linkend="msprintf">msprintf</link>
437 <refsection role="history">
438 <title>History</title>
441 <revnumber>6.1.0</revnumber>
443 Numbered placeholders "%n$.." are supported.
447 <revnumber>6.1.1</revnumber>
449 Input boolean data can be converted.