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>