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>