<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://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:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="read">
    <refnamediv>
        <refname>read</refname>
        <refpurpose>matrices read</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>[x] = read(file-desc,m,n,[format])
            [x]=read(file-desc,m,n,k,format)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>file-desc</term>
                <listitem>
                    <para>
                        character string specifying the file name or integer value specifying logical unit (fortran, see <link linkend="file">file</link>).
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>m, n</term>
                <listitem>
                    <para>integers (dimensions of the matrix x). Set m=-1 if you do not know the numbers of rows, so the whole file is read.</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>format</term>
                <listitem>
                    <para>character string specifying a "Fortran" format. It must begin with a right parenthesis and end with a left parenthesis.Formats cannot mix floating point or character edition modes.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>k</term>
                <listitem>
                    <para>integer or vector of integer</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            reads row after row
            the <literal>mxn</literal> matrix <literal>x</literal> (<literal>n=1</literal> for character chain) in the
            file <literal>file-desc</literal> (string or integer).  Each row of the matrix <literal>x</literal>
            begin in a new line of <literal>file-desc</literal> file. Depending on <literal>format</literal>, a
            given row of the <literal>x</literal> matrix may be read from more than one line
            of <literal>file-desc</literal> file.
        </para>
        <para>
            The type of the result will depend on the specified format.
            If format contains only <literal>(d,e,f,g)</literal>  descriptors the function
            tries to read numerical data (the result is matrix of real numbers).
        </para>
        <para>
            If format contains only  <literal>a</literal> descriptors the function tries to
            read character strings (the result is a character string column
            vector). In this case n must be equal to 1.
        </para>
        <warning>
          The character strings are truncated when they are longuer than 4093.
        </warning>
        <para>
            Examples for <literal>format</literal>:
        </para>
        <programlisting role=""><![CDATA[
(1x,e10.3,5x,3(f3.0))
(10x,a20)
 ]]></programlisting>
        <para>
            When format is omitted data are read using numerical free format:
            blank, comma and slash may be used as data separators, n*v may be use
            to represent n occurrences of value n.
        </para>
        <para>
            A direct access file can be used if using the parameter <literal>k</literal> which is
            is the vector of record numbers to be read (one record per row),
            thus <literal>m</literal> must be <literal>m=prod(size(k))</literal>.
        </para>
        <para>
            To read on the keyboard use <literal>read(%io(1),...)</literal>.
        </para>
        <note>
            Last line of data files must be terminated by a newline to be taken into account.
        </note>
    </refsection>
    <refsection>
        <title>Examples</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)')  // waits for user's input
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="write">write</link>
            </member>
            <member>
                <link linkend="load">load</link>
            </member>
            <member>
                <link linkend="file">file</link>
            </member>
            <member>
                <link linkend="readb">readb</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>
