scilab/modules/output_stream/help/en_US/mprintf.xml

   1 <?xml version="1.0" encoding="windows-1251"?>
   2 <!--
   3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
   4  * Copyright (C) 2008 - INRIA
   5  * ...
   6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
   7  * Copyright (C) 2021 - Samuel GOUGEON
   8  *
   9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
  10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
  11  * This file was originally licensed under the terms of the CeCILL v2.1,
  12  * and continues to be available under such terms.
  13  * For more information, see the COPYING file which you should have received
  14  * along with this program.
  15  *
  16  -->
  17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
  18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="http://www.w3.org/1999/xhtml"
  19           xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org"
  20           xml:id="mprintf" xml:lang="en">
  21     <refnamediv>
  22         <refname>mprintf</refname>
  23         <refpurpose>converts, formats, and writes data to the main scilab window
  24         </refpurpose>
  25     </refnamediv>
  26     <refnamediv xml:id="printf">
  27         <refname>printf</refname>
  28         <refpurpose>converts, formats, and writes data to the main scilab window (obsolete)
  29         </refpurpose>
  30     </refnamediv>
  31     <refsynopsisdiv>
  32         <title>Syntax</title>
  33         <synopsis>mprintf(format,a1,...,an);</synopsis>
  34     </refsynopsisdiv>
  35     <refsection>
  36         <title>Arguments</title>
  37         <variablelist>
  38             <varlistentry>
  39                 <term>format</term>
  40                 <listitem>
  41                     <para>a string providing the format to use to write all next arguments.
  42                         The <varname>format</varname> follows -- as close as possible -- the C printf
  43                         format operand syntax, as described in the
  44                         <link linkend="printf_conversion">printf_conversion</link> page.
  45                         UTF-8 extended characters and numbered placeholders "%n$.." are supported.
  46                     </para>
  47                 </listitem>
  48             </varlistentry>
  49             <varlistentry>
  50                 <term>a1,...,an</term>
  51                 <listitem>
  52                     <para>
  53                         Data to be converted and printed according to the <varname>format</varname>
  54                         argument. Supported types: all numbers, booleans, strings. Only the real part
  55                         of complex numbers is considered (current Scilab limitation).
  56                     </para>
  57                 </listitem>
  58             </varlistentry>
  59         </variablelist>
  60     </refsection>
  61     <refsection>
  62         <title>Description</title>
  63         <para>
  64             <literal>mprintf(format, a1, a2, ..)</literal> replaces placeholders provided inside the
  65             <varname>format</varname> string with values of <varname>a1</varname>, <varname>a2</varname>, ..
  66             converted according to each respective placeholder directive, and writes the result to
  67             the Scilab console.
  68         </para>
  69         <para>
  70             If <varname>a1</varname>, <varname>a2</varname>, .. are arrays with multiple rows,
  71             they feed the format row by row: the format is used iteratively for every row of the
  72             (horizontally "concatenated") arrays, until the bottom
  73             of the least tall array is reached. Remaining rows of taller arrays (if any) are ignored.
  74             See examples.
  75         </para>
  76         <para>
  77             If the total number of columns of <varname>a1</varname>, <varname>a2</varname>, ..
  78             is bigger than the number of placeholders in the <varname>format</varname>,
  79             then extra columns are ignored. If it is smaller, an error is yielded.
  80         </para>
  81         <para>
  82             The <literal>mprintf</literal> function is an extended interface for C-coded
  83             <literal>printf</literal>.
  84         </para>
  85     </refsection>
  86     <refsection>
  87         <title>Examples</title>
  88         <programlisting role="example"><![CDATA[
  89 I = (1:4)';
  90 A = [26.93 ; 63.25 ; 40.51 ; 91.84];
  91 B = [ 3.62 ; 15.04 ; 25.3  ; 48.19];
  92 C = [ 4.37   28.06
  93      48.18   %inf
  94      41.48   %nan
  95      26.39   77.83];
  96 Status = ["NOK" "NOK" "NOK" "OK"]';
  97 Format = "Iteration %d: Results: A= %f   B= %2d%%  Status= %3s   C(1)= %g  C(2)= %e\n";
  98 mprintf(Format, I, A, B, Status, C);
  99      ]]></programlisting>
 100         <screen><![CDATA[
 101 --> mprintf(Format, I, A, B, Status, C);
 102 Iteration 1: Results: A= 26.930000   B=  3%  Status= NOK   C(1)= 4.37  C(2)= 2.806000e+01
 103 Iteration 2: Results: A= 63.250000   B= 15%  Status= NOK   C(1)= 48.18  C(2)= Inf
 104 Iteration 3: Results: A= 40.510000   B= 25%  Status= NOK   C(1)= 41.48  C(2)= Nan
 105 Iteration 4: Results: A= 91.840000   B= 48%  Status=  OK   C(1)= 26.39  C(2)= 7.783000e+01
 106 ]]></screen>
 107         <para/>
 108         <para>
 109             Supernumerary columns or rows are ignored:
 110         </para>
 111         <programlisting role="example"><![CDATA[
 112 A = [%T  %F  %T  %T  %F]';
 113 B = [ 4.37   28.06
 114      48.18   %inf
 115      41.48   %nan ];
 116 mprintf("OK? %s  Value: %4.1f\n", A, B);
 117      ]]></programlisting>
 118         <screen><![CDATA[
 119 --> mprintf("OK? %s  Value: %4.1f\n", A, B);
 120 OK? T  Value:  4.4
 121 OK? F  Value: 48.2
 122 OK? T  Value: 41.5
 123 ]]></screen>
 124         <para/>
 125         <para>
 126             Numbered placeholders "%n$.." allow reordering printed data with the format:
 127         </para>
 128         <programlisting role="example"><![CDATA[
 129 names = ["Peter", "Martha" "John"]';
 130 ages  = [32 25 8]';
 131 mprintf("%2$6s is %1$d-year old.\n", ages, names);
 132      ]]></programlisting>
 133         <screen><![CDATA[
 134 --> mprintf("%2$6s is %1$d-year old.\n", ages, names);
 135  Peter is 32-year old.
 136 Martha is 25-year old.
 137   John is 8-year old.
 138 ]]></screen>
 139     </refsection>
 140     <refsection role="see also">
 141         <title>See also</title>
 142         <simplelist type="inline">
 143             <member>
 144                 <link linkend="printf_conversion">printf_conversion</link>
 145             </member>
 146             <member>
 147                 <link linkend="disp">disp</link>
 148             </member>
 149             <member>
 150                 <link linkend="write">write</link>
 151             </member>
 152             <member>
 153                 <link linkend="percentio">percentio</link>
 154             </member>
 155             <member>
 156                 <link linkend="percentchars">percentchars</link>
 157             </member>
 158         </simplelist>
 159     </refsection>
 160     <refsection role="history">
 161         <title>History</title>
 162         <revhistory>
 163             <revision>
 164                 <revnumber>6.1.0</revnumber>
 165                 <revdescription>
 166                     Numbered placeholders "%n$.." are supported in the format.
 167                 </revdescription>
 168             </revision>
 169             <revision>
 170                 <revnumber>6.1.1</revnumber>
 171                 <revdescription>
 172                     Input data can be boolean.
 173                 </revdescription>
 174             </revision>
 175         </revhistory>
 176     </refsection>
 177 </refentry>