<?xml version="1.0" encoding="utf-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2015  - Scilab Enterprises - 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="api_string" xml:lang="en">
    <refnamediv>
        <refname>API string functions</refname>
        <para>This page lists all the functions to manipulate Scilab native objects containing strings</para>
        <para></para>
    </refnamediv>
    <refsynopsisdiv>
        <refsection id="api_string_scilab_createStringMatrix">
            <literal>
                <link linkend="api_types_scilabVar">
                    <command>scilabVar</command>
                </link>
                <varname>scilab_createStringMatrix</varname>(
                <link linkend="api_types_scilabEnv">
                    <command>scilabEnv</command>
                </link>
                env, int dim, const int* dims)
            </literal>
            <para>
                Create a string matrix with <varname>dim</varname> dimensions (<varname>dims</varname>[0], <varname>dims</varname>[1], ..., <varname>dims</varname>[<varname>dim</varname>-1]).
            </para>
        </refsection>
        <refsection id="api_string_scilab_createStringMatrix2d">
            <literal>
                <link linkend="api_types_scilabVar">
                    <command>scilabVar</command>
                </link>
                <varname>scilab_createStringMatrix2d</varname>(
                <link linkend="api_types_scilabEnv">
                    <command>scilabEnv</command>
                </link>
                env, int row, int col)
            </literal>
            <para>
                Create an string matrix with 2 dimensions (<varname>row</varname>, <varname>col</varname>).
            </para>
        </refsection>
        <refsection id="api_string_scilab_createString">
            <literal>
                <link linkend="api_types_scilabVar">
                    <command>scilabVar</command>
                </link>
                <varname>scilab_createString</varname>(
                <link linkend="api_types_scilabEnv">
                    <command>scilabEnv</command>
                </link>
                env, const wchar_t* val)
            </literal>
            <para>Create a scalar string.</para>
        </refsection>
        <refsection id="api_string_scilab_getStringArray">
            <literal>
                <link linkend="api_types_scilabStatus">
                    <command>scilabStatus</command>
                </link>
                <varname>scilab_getStringArray</varname>(
                <link linkend="api_types_scilabEnv">
                    <command>scilabEnv</command>
                </link>
                env,
                <link linkend="api_types_scilabVar">
                    <command>scilabVar</command>
                </link>
                var, wchar_t*** strs)
            </literal>
            <para>
                Get pointer on internal array of string of <varname>var</varname>.
            </para>
        </refsection>
        <refsection id="api_string_scilab_getString">
            <literal>
                <link linkend="api_types_scilabStatus">
                    <command>scilabStatus</command>
                </link>
                <varname>scilab_getString</varname>(
                <link linkend="api_types_scilabEnv">
                    <command>scilabEnv</command>
                </link>
                env,
                <link linkend="api_types_scilabVar">
                    <command>scilabVar</command>
                </link>
                var, wchar_t** str)
            </literal>
            <para>Get string value from an scalar string variable.</para>
        </refsection>
        <refsection id="api_string_scilab_setStringArray">
            <literal>
                <link linkend="api_types_scilabStatus">
                    <command>scilabStatus</command>
                </link>
                <varname>scilab_setStringArray</varname>(
                <link linkend="api_types_scilabEnv">
                    <command>scilabEnv</command>
                </link>
                env,
                <link linkend="api_types_scilabVar">
                    <command>scilabVar</command>
                </link>
                var, const wchar_t* const* strs)
            </literal>
            <para>
                Set values of string variable <literal>var</literal>.
            </para>
        </refsection>
        <refsection id="api_string_scilab_setString">
            <literal>
                <link linkend="api_types_scilabStatus">
                    <command>scilabStatus</command>
                </link>
                <varname>scilab_setString</varname>(
                <link linkend="api_types_scilabEnv">
                    <command>scilabEnv</command>
                </link>
                env,
                <link linkend="api_types_scilabVar">
                    <command>scilabVar</command>
                </link>
                var, const wchar_t* str)
            </literal>
            <para>
                Set value of a scalar string variable <literal>var</literal>.
            </para>
        </refsection>
    </refsynopsisdiv>
    <refsection>
        <title>Examples</title>
        <programlisting role="code_gateway">
            <![CDATA[
#include <ctype.h>
#include "api_scilab.h"
#include "Scierror.h"
#include "localization.h"
#include "sciprint.h"
#include "sci_malloc.h"
#include "os_string.h"

const char fname[] = "string_test";

int sci_string_test(scilabEnv env, int nin, scilabVar* in, int nopt, scilabOpt opt, int nout, scilabVar* out)
{
    int i = 0;
    int inr1 = 0;
    int inc1 = 0;
    int size1 = 0;
    wchar_t** in1 = NULL;

    wchar_t* in2 = 0;

    int dim1 = 3;
    int dims1[] = {0, 0, 2};
    wchar_t** out1 = NULL;

    wchar_t* out2;
    int len2 = 0;
    int diff = L'a' - L'A';

    if (nin != 2)
    {
        Scierror(999, _("%s: Wrong number of input arguments: %d expected.\n"), fname, 2);
        return STATUS_ERROR;
    }

    if (nout != 2)
    {
        Scierror(999, _("%s: Wrong number of output arguments: %d expected.\n"), fname, 3);
        return STATUS_ERROR;
    }

    //in[0] : matrix 2d of string
    if (scilab_isString(env, in[0]) == 0 || scilab_isMatrix(env, in[0]) == 0)
    {
        Scierror(999, _("%s: Wrong type for input argument #%d: A string matrix expected.\n"), fname, 1);
        return STATUS_ERROR;
    }

    size1 = scilab_getDim2d(env, in[0], &inr1, &inc1);
    scilab_getStringArray(env, in[0], &in1);

    //in[1] : string
    if (scilab_isString(env, in[1]) == 0 || scilab_isScalar(env, in[1]) == 0)
    {
        Scierror(999, _("%s: Wrong type for input argument #%d: A double expected.\n"), fname, 2);
        return STATUS_ERROR;
    }

    scilab_getString(env, in[1], &in2);

    //out1 : matrix 2d of string with same size of in[0]
    dims1[0] = inr1;
    dims1[1] = inc1;
    out[0] = scilab_createStringMatrix(env, dim1, dims1);
    scilab_getStringArray(env, out[0], &out1);

    for (i = 0; i < size1; ++i)
    {
        wchar_t temp[128];
        wcscpy(temp, in1[i]);
        wcscat(temp, L".one");
        out1[i] = os_wcsdup(temp);

        wcscpy(temp, in1[i]);
        wcscat(temp, L".two");
        out1[i + size1] = os_wcsdup(temp);
    }

    //out2 : string
    out2 = os_wcsdup(in2);
    len2 = wcslen(out2);
    for (i = 0; i < len2; ++i)
    {
        if (out2[i] >= L'a' && out2[i] <= L'z')
        {
            out2[i] = (out2[i] - 'a' + 26 - 1) % 26) + 'a';
        }
        else if (out2[i] >= L'A' && out2[i] <= L'Z')
        {
            out2[i] = (out2[i] - 'A' + 26 - 1) % 26) + 'A';
        }
        else
        {
            //no change
        }
    }

    out[1] = scilab_createString(env, out2);
    FREE(out2);
    return STATUS_OK;
}
            ]]>
        </programlisting>
    </refsection>
    <refsection>
        <title>Scilab test script</title>
        <programlisting role="code_scilab">
            <![CDATA[
mkdir(pathconvert(TMPDIR+"/api_c/"));
cd(pathconvert(TMPDIR+"/api_c/"));
copyfile(SCI+"/modules/api_scilab/tests/unit_tests/api_c/string_test.c",pathconvert(TMPDIR+"/api_c/string_test.c",%F));

ilib_build("libstring",["string_test","sci_string_test", "csci6"],"string_test.c",[],"","","");
exec("loader.sce");

in1 = ["one.one", "one.two", "one.three", "one.four"; "two.one", "two.two", "two.three", "two.four"; "three.one", "three.two", "three.three", "three.four"];
in2 = "IBM™";

[out1, out2] = string_test(in1, in2);
ref(:,:,1) = in1 + ".one";
ref(:,:,2) = in1 + ".two";
assert_checkequal(out1, ref);
assert_checkequal(out2, "HAL™");
            ]]>
        </programlisting>
    </refsection>
</refentry>
