<?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
 *
 * 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: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="mfscanf" xml:lang="ru">
    <refnamediv>
        <refname>mfscanf</refname>
        <refpurpose>
            считывает входные данные из потока, указанного указателем потока (интерфейс с C-функцией fscanf)
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="mscanf">
        <refname>mscanf</refname>
        <refpurpose>
            считывает входные данные с устройства стандартного ввода данных (интерфейс с C-функцией scanf)
        </refpurpose>
    </refnamediv>
    <refnamediv xml:id="msscanf">
        <refname>msscanf</refname>
        <refpurpose>
            считывает свои входные данные из символьной строки (интерфейс с C-функцией sscanf)
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
            [n, v_1,..., v_m] = mfscanf([niter,]fd, format)
            L = mfscanf([niter,] fd,format)

            [n, v_1,..., v_m] = mscanf([niter,] format)
            L = mscanf([niter,]format)

            [n, v_1,..., v_m] = msscanf([niter,]str, format)
            L = msscanf([niter,] str, format)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>format</term>
                <listitem>
                    <para>
                        Scilab-строка, описывающая формат, который нужно использовать для
                        записи оставшихся операндов. Операнд <varname>format</varname>
                        следует, как можно ближе синтаксису операндов формата C-функции
                        <function>printf</function>, как описано в
                        <link linkend="scanf_conversion">преобразовании в scanf</link>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>fd</term>
                <listitem>
                    <para>
                        положительное целое число: файловый дескриптор, возвращённый функцией <function>mopen</function>. Значение -1 относится к последнему открытому файлу.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>str</term>
                <listitem>
                    <para>Scilab-строка или вектор строк.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>niter</term>
                <listitem>
                    <para>
                        целое число: сколько раз использовать <varname>format</varname>.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>n</term>
                <listitem>
                    <para>
                        целое число: количество данных, которое необходимо прочитать или -1, если конец файла был достигнут прежде, чем что-либо из данных было прочитано.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>v_i</term>
                <listitem>
                    <para>
                        каждая из функций считывает символы, интерпретирует их в
                        соответствии с форматом <varname>format</varname> и сохраняет
                        результаты в своих выходных аргументах. Если выходных аргументов
                        указано больше, чем <varname>n</varname>, то последние аргументы
                        <varname>v_n+1, ..., v_m</varname> устанавливаются пустыми
                        матрицами.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>L</term>
                <listitem>
                    <para>
                        если все данные однородны, то они сохраняются в уникальном
                        векторе, который возвращается, в противном случае
                        последовательности одного типа данных сохраняются в матрицах, а
                        возвращается матричноориентированный типизированный список <literal>mlist</literal> (с типом <literal>cblock</literal>), содержащий все построенные матрицы.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
            Функция <function>mfscanf</function> считывает символы из потока
            <varname>fd</varname>.
        </para>
        <para>
            Функция <function>mscanf</function> считывает символы из окна Scilab.
        </para>
        <para>
            Функция <function>msscanf</function> считывает символы из Scilab-строки
            <varname>str</varname>.
        </para>
        <para>
            Необязательный аргумент <varname>niter</varname> определяет сколько раз
            использовать формат. Одна итерация формирует одну строку в выходной
            матрице. Если <code>niter==-1</code>, то функция выполняет итерации до
            конца файла. Значение <varname>niter</varname> по умолчанию равно 1.
        </para>
        <para>Комментарии о точности:</para>
        <para>
            <function>mfscanf</function> основана на C-функции
            <function>fscanf</function>. Если вы используете
            <literal>'%f'</literal>, <literal>'%g'</literal>,
            <literal>'%e'</literal> в качестве формата, то ваши данные будут
            приведены в тип плавающей запятой и возвращены в Scilab-переменную.
        </para>
        <para>
            Если эта Scilab-переменная является числом двойной точности, то вы
            можете получить некоторые ошибки по точности. В этом случае лучше
            использовать формат <literal>'%lg'</literal>.
        </para>
    </refsection>
    <refsection>
        <title>Примеры</title>
        <programlisting role="example"><![CDATA[
//----------------------------------------------------------
//--              Простое использование                   --
//----------------------------------------------------------
s='1 1.3'  // строка
[n,a,b]=msscanf(s,"%i %e")
L=msscanf(s,"%i %e")

//----------------------------------------------------------
//--               Примеры форматов                       --
//----------------------------------------------------------

msscanf(" 12\n",'%c%c%c%c') // сканирование символов

msscanf('0xabc','%x') // сканирование в шестнадцатеричном формате

msscanf('012345abczoo','%[0-9abc]%s')  //обозначение []

// считывание чисел типов float и double
msscanf('4345.988','%g')-4345.988 // сканирование числа float
msscanf('4345.988','%lg')-4345.988 // сканирование числа double

//----------------------------------------------------------
//--    сканирование файлов с многострочными данными
//----------------------------------------------------------
// создание файла с данными
u=mopen(TMPDIR+'/foo','w');
t=(0:0.1:%pi)';mfprintf(u,"%6.3f %6.3f\n",t,sin(t))
mclose(u);

// открытие файла на чтение
u=mopen(TMPDIR+'/foo','r');
// чтение файла строка за строкой
[n,a,b]=mfscanf(u,'%e %e') // первая строка, используя синтаксис множества данных с левой стороны
l=mfscanf(u,'%e %e')       // вторая строка, используя синтаксис одной переменной с левой стороны

//использование niter для чтения ещё пяти строк
l=mfscanf(5,u,'%e %e')

// использование niter=-1 для чтения до конца файла
l=mfscanf(-1,u,'%e %e')

// закрытие файла
mclose(u);

//------------------------------------------------------------------
//-- сканирование векторов с многострочными строковыми значениями --
//------------------------------------------------------------------
//использование niter для сканирования вектора строковых значений
[n,Names,Ages]=msscanf(-1,["Alain 19";"Pierre 15";"Tom 12"],'%s %d')
D=msscanf(-1,["Alain 19";"Pierre 15";"Tom 12"],'%s %d')
typeof(D)
Names=D(:,1) // строки
Age=D(:,2)   // числовые значения
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="mclose">mclose</link>
            </member>
            <member>
                <link linkend="meof">meof</link>
            </member>
            <member>
                <link linkend="mfprintf">mfprintf</link>
            </member>
            <member>
                <link linkend="fprintfMat">fprintfMat</link>
            </member>
            <member>
                <link linkend="fscanfMat">fscanfMat</link>
            </member>
            <member>
                <link linkend="mget">mget</link>
            </member>
            <member>
                <link linkend="mgetstr">mgetstr</link>
            </member>
            <member>
                <link linkend="mopen">mopen</link>
            </member>
            <member>
                <link linkend="mprintf">mprintf</link>
            </member>
            <member>
                <link linkend="mput">mput</link>
            </member>
            <member>
                <link linkend="mputstr">mputstr</link>
            </member>
            <member>
                <link linkend="mseek">mseek</link>
            </member>
            <member>
                <link linkend="mtell">mtell</link>
            </member>
            <member>
                <link linkend="mdelete">mdelete</link>
            </member>
            <member>
                <link linkend="scanf_conversion">преобразование в scanf</link>
            </member>
        </simplelist>
    </refsection>
</refentry>

