<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) INRIA -
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - 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: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="listvarinfile">
    <refnamediv>
        <refname>listvarinfile</refname>
        <refpurpose>lists variables stored in a binary archive (names, types, sizes..)</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>
            listvarinfile(filename);
            [names, typs, dims, vols] = listvarinfile(filename)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>filename</term>
                <listitem>
                    <para>
                        a character string, the pathname of the file to be inspected.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>nams</term>
                <listitem>
                    <para>
                        a matrix of strings, names of the variables saved in the file.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>dims</term>
                <listitem>
                    <para>
                        a list, dimensions of the variables saved in the file.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>typs</term>
                <listitem>
                    <para>
                        a numeric matrix, types of the variables saved in the file.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>vols</term>
                <listitem>
                    <para>
                        a numeric matrix, size in bytes of the variables saved in the file.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>
            This utility function lists "a la <link linkend="whos">whos</link>" the variables
            stored in a Scilab data file created with <link linkend="save">save</link>.
        </para>
        <para>
            <note>
                Rationals and state-space linear systems are reported as plain tlists
            </note>
        </para>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
// Preparing some data of various types:
b = rand(2,3) < 0.5;                    // booleans
i = uint64(grand(3,4,2,"uin",0,100));   // hypermatrix of encoded integers
c = grand(3,3,"uin",-10,10); c=c+c'*%i; // complex numbers
p = (1-%z).^(0:3);                      // polynomials
r = p/(1+%z);                           // rationals
sp = sprand(10,15,0.1);                 // sparse numbers
spb = sp<0.5;                           // sparse booleans
t = ["This" "software" ; "is" "Scilab"];// Texts
g = [gdf() gda()];                      // Graphics
function Test()                         // macro
    disp("listvarinfile() test for macros")
end
M = linspace;                           // macro
L = list(%f, int8(-23),, %i-%z, list("abc",%e)); // simple list
C = {"abc" %t ; %z list(1/%z, 4)};      // array of cells
S(4,2).r = %pi;                         // array of structures
vars = list("b","i","c","p","r","sp","spb","t","g","Test","M","L","C","S");

// Archiving data in a binary file:
File = TMPDIR + "\listvarinfile.sod";
save(File, vars(:))

// Listing the file content:
[names,types,dims,vols] = listvarinfile(File);
types(find(names=="Test"))
dims(find(names=="i"))
 ]]></programlisting>
    <screen><![CDATA[
--> [names,types,dims,vols] = listvarinfile(File);
Name                     Type           Size            Bytes
-------------------------------------------------------------
C                        cell           2 by 2          76
L                        list           4               51
M                        macro          1 by 1          0
S                        struct         4 by 2          8
Test                     macro          1 by 1          0
b                        boolean        2 by 3          24
c                        double         3 by 3          144
g                        handle         1 by 2          0
i                        integer        3 by 4 by 2     192
p                        polynomial     1 by 4          80
r                        tlist          4               162
sp                       sparse         10 by 15        232
spb                      boolean sparse 10 by 15        624
t                        string         2 by 2          40

--> types(find(names=="Test"))
 ans  =
   13.

--> dims(find(names=="i"))
 ans  =
   3.   4.   2.
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="save">save</link>
            </member>
            <member>
                <link linkend="load">load</link>
            </member>
            <member>
                <link linkend="save_format">save_format</link>
            </member>
            <member>
                <link linkend="type">type</link>
            </member>
            <member>
                <link linkend="whos">whos</link>
            </member>
            <member>
                <link linkend="who">who</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>History</title>
        <revhistory>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
                    <itemizedlist>
                        <listitem>
                            Hypermatrices are now listed with the type of their content, instead of
                            "mlist" and type 17. Their sizes are now the actual ones, instead of 3.
                        </listitem>
                        <listitem>
                            Cells and Structures arrays now appear as "cell" and "struct" instead
                            of "mlist". Their sizes are now the actual ones, instead of 3.
                        </listitem>
                        <listitem>
                            Arrays of graphic handles now appear as "handle" and type 9,
                            instead of "tlist" and type 16.
                            Their sizes are now the actual ones, instead of 3.
                        </listitem>
                        <listitem>
                            Macros now appear as "macro" and type 13, instead of "tlist" and type 16.
                        </listitem>
                        <listitem>
                            Real and complex numbers now appear as "double" instead of "constant".
                        </listitem>
                    </itemizedlist>
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
