API help 3
antoine ELIAS [Tue, 7 Jul 2009 16:25:55 +0000 (18:25 +0200)]
scilab/modules/core/help/en_US/api/double_writing_api.xml
scilab/modules/core/help/en_US/api/string_reading_api.xml [new file with mode: 0644]
scilab/modules/core/help/en_US/api/string_writing_api.xml [new file with mode: 0644]

index 1cd42ea..b4a37f0 100644 (file)
 int write_double(char *fname,unsigned long fname_len)
 {
     int i,j;
-
+    int iRet            = 0;
     //first variable info : real matrix of double 3 x 4
     int iRows1          = 3;
     int iCols1          = 4;
@@ -190,7 +190,12 @@ int write_double(char *fname,unsigned long fname_len)
     //}
 
     //create a variable from a existing data array
-    createMatrixOfDouble(Rhs + 1, iRows1, iCols1, pdblReal1);
+    iRet = createMatrixOfDouble(Rhs + 1, iRows1, iCols1, pdblReal1);
+    if(iRet)
+    {
+        //Error
+        return 1;
+    }
 
     //after creation, we can free memory.
     free(pdblReal1);
@@ -199,7 +204,12 @@ int write_double(char *fname,unsigned long fname_len)
     *************************/
 
     //reserve space in scilab memory and fill it
-    allocComplexMatrixOfDouble(Rhs + 2, iRows2, iCols2, &pdblReal2, &pdblImg2);
+    iRet = allocComplexMatrixOfDouble(Rhs + 2, iRows2, iCols2, &pdblReal2, &pdblImg2);
+    if(iRet)
+    {
+        //Error
+        return 1;
+    }
 
     //fill array with incremental values for real part and decremental for imaginary part
     //[ 23i     1+22i       2+21i       3+20i       4+19i       5+18i
diff --git a/scilab/modules/core/help/en_US/api/string_reading_api.xml b/scilab/modules/core/help/en_US/api/string_reading_api.xml
new file mode 100644 (file)
index 0000000..103177c
--- /dev/null
@@ -0,0 +1,206 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2009  - DIGITEO - Antoine ELIAS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<refentry version="5.0-subset Scilab" xml:id="String management reading_API"
+          xml:lang="en" 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">
+
+    <refnamediv>
+        <refname>String reading</refname>
+        <refpurpose>
+            How to read matrices of strings in a gateway.
+        </refpurpose>
+    </refnamediv>
+    <refsection>
+        <title>Description</title>
+        <para>This help describes how matrix of strings can be handled through the Scilab API.</para>
+        <synopsis>int getMatrixOfString(int* _piAddress, int* _piRows, int* _piCols, int* _piLength, char** _pstStrings)</synopsis>
+    </refsection>
+    <refsection>
+        <title>Parameters</title>
+        <variablelist>
+            <varlistentry>
+                <term>_piAddress</term>
+                <listitem>
+                    <para>
+                        Address of the Scilab variable.
+                    </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 (need to be allocated size: _piRows * _piCols)
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>_pstStrings</term>
+                <listitem>
+                    <para>
+                        Address of array of char* (need to be allocated size: _piRows * _piCols)
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <!--File_gateway: SCI/modules/core/tests/unit_tests/string_reading_api.c-->
+        <!--File_scilab: SCI/modules/core/tests/unit_tests/string_reading_api.tst-->
+        <!--Lib_name: string_reading-->
+        <!--Func_list: read_string-->
+        <title>Gateway Source</title>
+        <programlisting role="code gateway">
+            <![CDATA[
+int read_string(char *fname,unsigned long fname_len)
+{
+    int i,j;
+    int iLen        = 0;
+       int iRet        = 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
+    CheckRhs(1,1);
+    CheckLhs(1,1);
+
+    //get variable address
+    iRet = getVarAddressFromPosition(1, &piAddr);
+    if(iRet)
+    {
+        return 1;
+    }
+
+    //check variable type
+    if(getVarType(piAddr) != sci_strings)
+    {
+        return 1;
+    }
+
+    //fisrt call to retrieve dimensions
+    iRet = getMatrixOfString(piAddr, &iRows, &iCols, NULL, NULL);
+    if(iRet)
+    {
+        return 1;
+    }
+
+    piLen = (int*)malloc(sizeof(int) * iRows * iCols);
+    //second call to retrieve length of each string
+    iRet = getMatrixOfString(piAddr, &iRows, &iCols, piLen, NULL);
+    if(iRet)
+    {
+        return 1;
+    }
+
+    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
+    iRet = getMatrixOfString(piAddr, &iRows, &iCols, piLen, pstData);
+    if(iRet)
+    {
+        return 1;
+    }
+
+    //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
+    iRet = createMatrixOfString(Rhs + 1, iRowsOut, iColsOut, &pstOut);
+    if(iRet)
+    {
+        return 1;
+    }
+
+    //free memory
+    free(piLen);
+    for(i = 0 ; i < iRows * iCols ; i++)
+    {
+        free(pstData[i]);
+    }
+    free(pstData);
+    free(pstOut);
+
+    LhsVar(1) = Rhs + 1;
+    PutLhsVar();
+    return 0;
+}
+            ]]>
+        </programlisting>
+    </refsection>
+
+    <refsection>
+        <title>Scilab test script</title>
+        <programlisting role="code_scilab">
+            <![CDATA[
+a_ref = ["sample strings manipulation with gateway API"];
+a = ["sample", "strings", "manipulation"; "with","gateway","API"];
+b = tonio(a);
+if a_ref <> b then error("failed"), end
+            ]]>
+        </programlisting>
+    </refsection>
+</refentry>
\ No newline at end of file
diff --git a/scilab/modules/core/help/en_US/api/string_writing_api.xml b/scilab/modules/core/help/en_US/api/string_writing_api.xml
new file mode 100644 (file)
index 0000000..8e1f276
--- /dev/null
@@ -0,0 +1,140 @@
+<?xml version="1.0" encoding="utf-8"?>
+<!--
+ * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
+ * Copyright (C) 2009  - DIGITEO - Antoine ELIAS
+ * 
+ * This file must be used under the terms of the CeCILL.
+ * This source file is licensed as described in the file COPYING, which
+ * you should have received as part of this distribution.  The terms
+ * are also available at    
+ * http://www.cecill.info/licences/Licence_CeCILL_V2-en.txt
+ *
+ -->
+<refentry version="5.0-subset Scilab" xml:id="String management writing_API"
+          xml:lang="en" 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">
+
+    <refnamediv>
+        <refname>String writing</refname>
+        <refpurpose>
+            How to write matrices of string in a gateway.
+        </refpurpose>
+    </refnamediv>
+    <refsection>
+        <title>Description</title>
+        <para>This help describes how matrix of strngs can be handled through the Scilab API.</para>
+    </refsection>
+    <refsection>
+        <title>Create from existing data</title>
+        <synopsis>int createMatrixOfString(int _iVar, int _iRows, int _iCols, char** _pstStrings)</synopsis>
+    </refsection>
+    <refsection>
+        <title>Parameters</title>
+        <variablelist>
+            <varlistentry>
+                <term>_iVar</term>
+                <listitem>
+                    <para>
+                        Position in the Scilab memory where you want to put the variable
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>_iRows</term>
+                <listitem>
+                    <para>
+                        Number of rows of the new variable
+                    </para>
+                </listitem>
+            </varlistentry>
+            <varlistentry>
+                <term>_iCols</term>
+                <listitem>
+                    <para>
+                        Numbers of columns of the new variable
+                    </para>
+                </listitem>
+            </varlistentry>
+
+            <varlistentry>
+                <term>_pstStrings</term>
+                <listitem>
+                    <para>
+                        Address of array of char* (size: _iCols * _iRows)
+                    </para>
+                </listitem>
+            </varlistentry>
+        </variablelist>
+    </refsection>
+    <refsection>
+        <!--File_gateway: SCI/modules/core/tests/unit_tests/string_writing_api.c-->
+        <!--File_scilab: SCI/modules/core/tests/unit_tests/string_writing_api.tst-->
+        <!--Lib_name: string_writing-->
+        <!--Func_list: write_string-->
+        <title>Gateway Source</title>
+        <programlisting role="code gateway">
+            <![CDATA[
+int write_string(char *fname,unsigned long fname_len)
+{
+    int iRet        = 0;
+
+    //variable info : matrix of string 2 x 3
+    int iRows       = 2;
+    int iCols       = 3;
+    char** pstData  = NULL;
+
+    //data to put in the new variable
+    char string0[]  = "sample";
+    char string1[]  = "with";
+    char string2[]  = "strings";
+    char string3[]  = "gateway";
+    char string4[]  = "manipulation";
+    char string5[]  = "API";
+
+    //alloc new array
+    pstData         = (char**)malloc(sizeof(char*) * iRows * iCols);
+
+    //copy data address to the "main" array
+    pstData[0]      = string0;
+    pstData[1]      = string1;
+    pstData[2]      = string2;
+    pstData[3]      = string3;
+    pstData[4]      = string4;
+    pstData[5]      = string5;
+
+    //create the variable
+    createMatrixOfString(Rhs + 1, iRows, iCols, pstData);
+
+    //free container
+    free(pstData);
+    
+    //assign allocated variables to Lhs position
+    LhsVar(1)       = Rhs + 1;
+    PutLhsVar();
+    return 0;
+}
+        ]]>
+        </programlisting>
+    </refsection>
+    <refsection>
+        <title>Scilab test script</title>
+        <programlisting role="code_scilab">
+            <![CDATA[
+a_ref = "sample strings manipulation with gateway API ";
+b = [];
+a = write_string();
+for i=1:size(a,"r")
+    for j=1:size(a,"c")
+        b = b + a(i,j);
+        b = b + " ";
+    end
+end
+if b <> a_ref then error("failed"), end
+            ]]>
+        </programlisting>
+    </refsection>
+</refentry>
\ No newline at end of file