<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * ...
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2021 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
          xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns5="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="mfprintf" xml:lang="en">
    <refnamediv>
        <refname>mfprintf</refname>
        <refpurpose>converts, formats, and writes data to a file</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>mfprintf(fd, format, a1, ..., an)</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>fd</term>
                <listitem>
                    <para>
                        scalar positive index identifying the file, as provided by <literal>mopen</literal>.
                    </para>
                    <para>
                        If <varname>fd</varname> equals 0: redirection to stderr.
                    </para>
                    <para>
                        If <varname>fd</varname> equals 6: redirection to stdout (console).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>format</term>
                <listitem>
                    <para>
                        a string providing the format to use to write all next arguments.
                        The <varname>format</varname> follows -- as close as possible -- the C printf
                        format operand syntax, as described in the
                        <link linkend="printf_conversion">printf_conversion</link> page.
                        UTF-8 extended characters are supported.
                        <warning>
                            Numbered placeholders "%n$.." are not supported.
                        </warning>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>a1, ..., an</term>
                <listitem>
                    <para>
                        Data to be converted and written according to the <varname>format</varname>
                        argument. Supported types: all numbers, booleans, strings. Only the real part
                        of complex numbers is considered (current Scilab limitation).
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            <literal>mfprintf(fd, format, a1, a2, ..)</literal> replaces placeholders provided
            in the <varname>format</varname> string with values of <varname>a1</varname>,
            <varname>a2</varname>, .. converted according to each respective placeholder directive,
            and writes the result to the file specified by its index <varname>fd</varname>.
        </para>
        <para>
            If <varname>a1</varname>, <varname>a2</varname>, .. are arrays with multiple rows,
            they feed the format row by row: the format is used iteratively for every row of the
            (horizontally "concatenated") arrays, until the bottom
            of the least tall array is reached. Remaining rows of taller arrays (if any) are ignored.
            See examples.
        </para>
        <para>
            If the total number of columns of <varname>a1</varname>, <varname>a2</varname>, ..
            is bigger than the number of placeholders in the <varname>format</varname>,
            then extra columns are ignored. If it is smaller, an error is yielded.
        </para>
        <para>
            The <literal>mfprintf</literal> function is a interface for C-coded
            <literal>fprintf</literal> function.
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
fd = mopen(TMPDIR+'/text.txt','wt');
mfprintf(fd,'hello %s %d.\n','world',1);
mfprintf(fd,'hello %s %d.\n','scilab',2);
mfprintf(fd,'This line is built with a column vector (26:28) %d.\n',[26:28].');
mfprintf(fd,'This line is built with a row vector (26:28) %d.\n',[26:28]);
A = rand(3,6);
mfprintf(fd,'This line is built with a matrix %.3f.\n',A);
mclose(fd);
editor(TMPDIR+'/text.txt')

mfprintf(0,'stderr output.\n');
mfprintf(6,'stdout output.\n');
     ]]></programlisting>
        <para/>
        <programlisting role="example"><![CDATA[
I = (1:4)';
A = [26.93 ; 63.25 ; 40.51 ; 91.84];
B = [ 3.62 ; 15.04 ; 25.3  ; 48.19];
C = [ 4.37   28.06
     48.18   %inf
     41.48   %nan
     26.39   77.83];
Status = ["NOK" "NOK" "NOK" "OK"]';
Format = "Iteration %d: Results: A= %f   B= %2d%%  Status= %3s   C(1)= %g  C(2)= %e\n";
File = TMPDIR + "/mfprintf.txt";
fd = mopen(File, 'wt');
mfprintf(fd, Format, I, A, B, Status, C);
mclose
editor(File)
     ]]></programlisting>
        <screen><![CDATA[
Iteration 1: Results: A= 26.930000   B=  3%  Status= NOK   C(1)= 4.37  C(2)= 2.806000e+01
Iteration 2: Results: A= 63.250000   B= 15%  Status= NOK   C(1)= 48.18  C(2)= Inf
Iteration 3: Results: A= 40.510000   B= 25%  Status= NOK   C(1)= 41.48  C(2)= Nan
Iteration 4: Results: A= 91.840000   B= 48%  Status=  OK   C(1)= 26.39  C(2)= 7.783000e+01
]]></screen>
        <para/>
        <para>
            Supernumerary columns or rows are ignored:
        </para>
        <programlisting role="example"><![CDATA[
A = [%T  %F  %T  %T  %F]';
B = [ 4.37   28.06
     48.18   %inf
     41.48   %nan ];
File = TMPDIR + "/mfprintf.txt";
fd = mopen(File, 'wt');
mfprintf(fd, "OK? %s  Value: %4.1f\n", A, B)
mclose
editor(File)
     ]]></programlisting>
        <screen><![CDATA[
OK? T  Value:  4.4
OK? F  Value: 48.2
OK? T  Value: 41.5
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="printf_conversion">printf_conversion</link>
            </member>
            <member>
                <link linkend="csvWrite">csvWrite</link>
            </member>
            <member>
                <link linkend="fprintfMat">fprintfMat</link>
            </member>
            <member>
                <link linkend="write">write</link>
            </member>
            <member>
                <link linkend="mputl">mputl</link>
            </member>
            <member>
                <link linkend="mputstr">mputstr</link>
            </member>
            <member>
                <link linkend="mopen">mopen</link>
            </member>
            <member>
                <link linkend="mclose">mclose</link>
            </member>
            <member>
                <link linkend="mprintf">msprintf</link>
            </member>
            <member>
                <link linkend="mfscanf">mfscanf</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.1.1</revnumber>
                <revdescription>
                    Input data can be boolean.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
