[doc] gettext printf_conversion mprintf msprintf mfprintf pages updated & fixed
[scilab.git] / 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>