<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) XXXX-2008 - INRIA
 * Copyright (C) 2010 - DIGITEO - Allan CORNET
 *
 * 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: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="read" xml:lang="pt">
    <refnamediv>
        <refname>read</refname>
        <refpurpose>Leitura de matrizes</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Seqüência de Chamamento</title>
        <synopsis>[x]=read(file-desc,m,n,[format])
            [x]=read(file-desc,m,n,k,format)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Parâmetros</title>
        <variablelist>
            <varlistentry>
                <term>file-desc</term>
                <listitem>
                    <para>string especificando o nome do arquivo ou valor inteiro
                        especificando uma unidade lógica (fortran)(ver  <link linkend="file">file</link>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>m, n</term>
                <listitem>
                    <para>inteiros (dimensões da matriz x). Ajuste m=-1 se você
                        desconhece o número de linhas, para que todo o arquivo seja
                        lido.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>format</term>
                <listitem>
                    <para>string, especifica um formato "Fortran". Este string deve
                        começar com um parêntese direito e terminar com um parêntese
                        esquerdo. Formatos não podem misturar pontos flutuantes, inteiros ou
                        modo de edição de caractere
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>k</term>
                <listitem>
                    <para>inteiro ou vetor de inteiros</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Descrição</title>
        <para>
            Lê linha após linha a matriz x <literal>mxn</literal>
            (<literal>n=1</literal> para cadeia de caracteres) no arquivo
            <literal>file-desc</literal> (string ou inteiro). Cada linha da matriz
            <literal>x</literal> começa em uma nova linha do arquivo
            <literal>file-desc</literal>. Dependendo de <literal>format</literal>, uma
            dada linha da matriz <literal>x</literal> pode ser lida de mais de uma
            linha do arquivo <literal>file-desc</literal>.
        </para>
        <para>O tipo do resultado dependerá do formato especificado. Se format
            contém apenas os descritores <literal>(d,e,f,g)</literal> a função tenta
            ler dados numéricos (o resultado é uma matriz de números reais).
        </para>
        <para>
            Se format contém apenas o descritor <literal>a</literal> a função
            tenta ler strings (o resultado é um vetor coluna de strings). Neste caso,
            n deve ser igual a 1. Aviso: Os strings serão truncados se tiverem tamanho
            maior que 4093.
        </para>
        <para>
            Exemplos para <literal>format</literal>:
        </para>
        <programlisting role=""><![CDATA[
(1x,e10.3,5x,3(f3.0))
(10x,a20)
 ]]></programlisting>
        <para>Quando format é o omitido, os dados são lidos utilizando-se o
            formato numérico livre: espaços em branco, vírgulas e barras podem ser
            utilizados como separadores de dados, n*v pode ser utilizado para
            representar n ocorrências do valor n.
        </para>
        <para>Um arquivo de acesso direto pode ser utilzado na presença de um
            parâmetro <literal>k</literal> que é um vetor de números de gravações a
            serem lidas (uma gravação por linha), logo <literal>m</literal> deve ser
            <literal>m=prod(size(k))</literal>.
        </para>
        <para>
            Para ler no teclado use <literal>read(%io(1),...)</literal>.
        </para>
        <note>
            A última linha de cada arquivo de dados devemser terminada por uma
            nova linha (newline) a ser levada em conta.
        </note>
    </refsection>
    <refsection>
        <title>Exemplos</title>
        <programlisting role="example"><![CDATA[
mdelete(TMPDIR + '/foo');
A = rand(3,5);
write(TMPDIR + '/foo', A);
B = read(TMPDIR + '/foo', 3, 5);
B = read(TMPDIR + '/foo', -1, 5);
read(%io(1), 1, 1, '(a)')  // espera por entrada do usuário
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Ver Também</title>
        <simplelist type="inline">
            <member>
                <link linkend="file">file</link>
            </member>
            <member>
                <link linkend="write">write</link>
            </member>
            <member>
                <link linkend="x_dialog">x_dialog</link>
            </member>
            <member>
                <link linkend="mscanf">mscanf</link>
            </member>
            <member>
                <link linkend="mfscanf">mfscanf</link>
            </member>
            <member>
                <link linkend="msscanf">msscanf</link>
            </member>
            <member>
                <link linkend="fscanfMat">fscanfMat</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
