<?xml version="1.0" encoding="utf-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2009  - DIGITEO - Antoine ELIAS
 *
 * 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="list_getlistitemaddress_API" xml:lang="en">
    <refnamediv>
        <refname>Get child item (Scilab gateway)</refname>
        <refpurpose>
            How to get the address of a list child.
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>SciErr getListItemAddress(void* _pvCtx, int* _piAddress, int _iItemNum, int** _piItemAddress)</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>_pvCtx</term>
                <listitem>
                    <para>
                        Scilab environment pointer, pass in "pvApiCtx" provided by api_scilab.h.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_piAddress</term>
                <listitem>
                    <para>
                        Address of the list.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_iItemNum</term>
                <listitem>
                    <para>
                        Item number.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_piItemAddress</term>
                <listitem>
                    <para>
                        Return address of the item.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>SciErr</term>
                <listitem>
                    <para>
                        Error structure where is stored errors messages history and first error number.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>This help describes how to get the address of a list child.</para>
    </refsection>
    <refsection>
        <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/common_list_api.c-->
        <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/common_list_api.tst-->
        <!--Lib_name: common_list-->
        <!--Func_list: common_list-->
        <title>Gateway Source</title>
        <programlisting role="code_gateway"><![CDATA[
#include "api_scilab.h"

int get_list_info(int* _piAddress);
void insert_indent(void);

static int iLocalTab = 0;

int common_list(char *fname,void* pvApiCtx)
{
    SciErr sciErr;
    int *piAddr = NULL;

    CheckInputArgument(pvApiCtx, 1, 1);

    sciErr = getVarAddressFromPosition(pvApiCtx, 1, &piAddr);
    if(sciErr.iErr)
    {
        printError(&sciErr, 0);
        return 0;
    }

    get_list_info(piAddr);
    AssignOutputVariable(pvApiCtx, 1) = 0;
    return 0;
}
int get_list_info(int* _piAddress)
{
    SciErr sciErr;
    int i       = 0;
    int iRet    = 0;
    int iItem   = 0;

    //get list item number, failed if variable is not a kind of list
    sciErr = getListItemNumber(pvApiCtx, _piAddress, &iItem);
    if(sciErr.iErr)
    {
        printError(&sciErr, 0);
        sciprint("This variable is not a list");
        return 0;
    }

    sciprint("List (%d items) -> address : 0x%08X) : \n", iItem, _piAddress);

    for(i = 0 ; i < iItem ; i++)
    {
        int iType           = 0;
        int* piAddrChild    = NULL;

        sciErr = getListItemAddress(pvApiCtx, _piAddress, i + 1, &piAddrChild);
        if(sciErr.iErr)
        {
            printError(&sciErr, 0);
            return 0;
        }

        sciErr = getVarType(pvApiCtx, piAddrChild, &iType);
        if(sciErr.iErr)
        {
            printError(&sciErr, 0);
            return 0;
        }

        if(iType == sci_list || iType == sci_tlist || iType == sci_mlist)
        {
            insert_indent();
            sciprint("Child %d -> ", i + 1);
            iLocalTab++;
            iRet = get_list_info(piAddrChild);
            iLocalTab--;

            if(iRet)
            {
                return 1;
            }
        }
        else
        {
            insert_indent();
            sciprint("Child %d -> address : 0x%08X\n", i + 1, piAddrChild);
        }
    }

    return 0;
}
void insert_indent(void)
{
    int i = 0;
    for(i = 0 ; i < iLocalTab ; i++)
    {
        sciprint("\t");
    }
}
 ]]></programlisting>
    </refsection>
    <refsection>
        <title>Scilab test script</title>
        <programlisting role="code_scilab"><![CDATA[
l1 = [1,2*%i,3;%i,2,3*%i];
l2 = ["may","the";"puffin","be";"with","you"];
l3 = int8([1,2,3]);
l5 = list(l1,l2,l3);
l4 = list(l5, list(l5,l5));
l6 = uint16([1000,2000,3000]);
l = list(l1,l2,l3,l6,l4,l5);
common_list(l)
 ]]></programlisting>
    </refsection>
</refentry>
