<?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="String_management_reading_API" xml:lang="en">
    <refnamediv>
        <refname>String reading (Scilab gateway)</refname>
        <refpurpose>
            How to read matrices of strings in a gateway.
        </refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <para>Input argument profile:</para>
        <synopsis>SciErr getMatrixOfString(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piLength, char** _pstStrings)</synopsis>
        <synopsis>SciErr getMatrixOfWideString(void* _pvCtx, int* _piAddress, int* _piRows, int* _piCols, int* _piLength, wchar_t** _pwstStrings)</synopsis>
        <para>Named variable profile:</para>
        <synopsis>SciErr createNamedMatrixOfString(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, char** _pstStrings)</synopsis>
        <synopsis>SciErr createNamedMatrixOfWideString(void* _pvCtx, const char* _pstName, int _iRows, int _iCols, wchar_t** _pwstStrings)</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 Scilab variable.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_pstName</term>
                <listitem>
                    <para>
                        Name of the variable for "named" functions.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_piRows</term>
                <listitem>
                    <para>
                        Return number of rows.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_piCols</term>
                <listitem>
                    <para>
                        Return number of columns.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_piLength</term>
                <listitem>
                    <para>
                        Address of array of strings length (must be allocated size: _piRows * _piCols)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_pstStrings</term>
                <listitem>
                    <para>
                        Address of array of char* (must be allocated size: _piRows * _piCols)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>_pwstStrings</term>
                <listitem>
                    <para>
                        Address of array of wchar_t* (must be allocated size: _piRows * _piCols)
                    </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 matrix of strings can be handled through the Scilab API.</para>
    </refsection>
    <refsection>
        <!--File_gateway: SCI/modules/api_scilab/tests/unit_tests/string_reading_api.c-->
        <!--File_scilab: SCI/modules/api_scilab/tests/unit_tests/string_reading_api.tst-->
        <!--Lib_name: string_reading-->
        <!--Func_list: read_string-->
        <title>Gateway Source</title>
        <programlisting role="code_gateway"><![CDATA[
#include "api_scilab.h"
int read_string(char *fname,void* pvApiCtx)
{
	SciErr sciErr;
	int i,j;
	int iLen		= 0;
	//variable info
	int iRows		= 0;
	int iCols		= 0;
	int* piAddr		= NULL;
	int* piLen		= NULL;
	char** pstData	= NULL;
	//output variable
	int iRowsOut	= 1;
	int iColsOut	= 1;
	char* pstOut	= NULL;
	//check input and output arguments

    CheckInputArgument(pvApiCtx, 1, 1);
    CheckOutputArgument(pvApiCtx, 0, 1);

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

	//first call to retrieve dimensions
	sciErr = getMatrixOfString(pvApiCtx, piAddr, &iRows, &iCols, NULL, NULL);
	if(sciErr.iErr)
	{
		printError(&sciErr, 0);
		return 0;
	}

	piLen = (int*)malloc(sizeof(int) * iRows * iCols);

	//second call to retrieve length of each string
	sciErr = getMatrixOfString(pvApiCtx, piAddr, &iRows, &iCols, piLen, NULL);
	if(sciErr.iErr)
	{
		printError(&sciErr, 0);
		return 0;
	}

	pstData = (char**)malloc(sizeof(char*) * iRows * iCols);
	for(i = 0 ; i < iRows * iCols ; i++)
	{
		pstData[i] = (char*)malloc(sizeof(char) * (piLen[i] + 1));//+ 1 for null termination
	}

	//third call to retrieve data
	sciErr = getMatrixOfString(pvApiCtx, piAddr, &iRows, &iCols, piLen, pstData);
	if(sciErr.iErr)
	{
		printError(&sciErr, 0);
		return 0;
	}

	//computer length of all strings
	for(i = 0 ; i < iRows * iCols ; i++)
	{
		iLen += piLen[i];
	}

	//alloc output variable
	pstOut = (char*)malloc(sizeof(char) * (iLen + iRows * iCols));
	//initialize string to 0x00
	memset(pstOut, 0x00, sizeof(char) * (iLen + iRows * iCols));

	//concat input strings in output string
	for(i = 0 ; i < iRows ; i++)
	{
		for(j = 0 ; j < iCols ; j++)
		{
			int iCurLen = strlen(pstOut);
			if(iCurLen)
			{
				strcat(pstOut, " ");
			}
			strcpy(pstOut + strlen(pstOut), pstData[j * iRows + i]);
		}
	}

	//create new variable
	sciErr = createMatrixOfString(pvApiCtx, nbInputArgument(pvApiCtx) + 1, iRowsOut, iColsOut, &pstOut);
	if(sciErr.iErr)
	{
		printError(&sciErr, 0);
		return 0;
	}

	//free memory
	free(piLen);

	for(i = 0 ; i < iRows * iCols ; i++)
	{
		free(pstData[i]);
	}

	free(pstData);
	free(pstOut);
	AssignOutputVariable(pvApiCtx, 1) = nbInputArgument(pvApiCtx) + 1;
	return 0;
}
 ]]></programlisting>
    </refsection>
    <refsection>
        <title>Scilab test script</title>
        <programlisting role="code_scilab"><![CDATA[
a_ref = ["may the puffin be with you"];
a = ["may", "the", "puffin"; "be","with","you"];
b = read_string(a);
if a_ref <> b then error("failed"), end
 ]]></programlisting>
    </refsection>
</refentry>
