* Bug 15431 fixed [doc]: empty [] better documented
[scilab.git] / scilab / modules / string / help / en_US / string.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) INRIA -
5  * Copyright (C) DIGITEO - 2012 - Allan CORNET
6  * Copyright (C) 2012 - 2016 - Scilab Enterprises
7  * Copyright (C) 2019 - Samuel GOUGEON
8  *
9  * This file is hereby licensed under the terms of the GNU GPL v2.0,
10  * pursuant to article 5.3.4 of the CeCILL v.2.1.
11  * This file was originally licensed under the terms of the CeCILL v2.1,
12  * and continues to be available under such terms.
13  * For more information, see the COPYING file which you should have received
14  * along with this program.
15  *
16  -->
17 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink"
18           xmlns:svg="http://www.w3.org/2000/svg" xmlns:ns4="http://www.w3.org/1999/xhtml"
19           xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
20           xmlns:scilab="http://www.scilab.org" xml:id="string" xml:lang="en">
21     <refnamediv>
22         <refname>string</refname>
23         <refpurpose>conversion to string</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             text = string(x)
29             [out, in, text] = string(SciFun)
30         </synopsis>
31     </refsynopsisdiv>
32     <refsection>
33         <title>Arguments</title>
34         <variablelist>
35             <varlistentry>
36                 <term>x</term>
37                 <listitem>
38                     <para>
39                         a boolean, complex, real, integer, polynomial matrix,
40                         an implicitlist (like 1:$), a library of functions in Scilab language.
41                     </para>
42                 </listitem>
43             </varlistentry>
44             <varlistentry>
45                 <term>SciFun</term>
46                 <listitem>
47                     <para>
48                         a function in Scilab language (type 13, not its name as a string).
49                     </para>
50                 </listitem>
51             </varlistentry>
52         </variablelist>
53     </refsection>
54     <refsection>
55         <title>Description</title>
56         <para>
57             The <function>string</function> function converts a matrix <varname>x</varname> into a matrix of strings.
58         </para>
59         <para>
60             If <varname>SciFun</varname> is a function, <literal>[out,in,text] = string(SciFun)</literal>
61             returns three vectors of strings:
62             <itemizedlist>
63                 <listitem>
64                     <varname>out</varname> is the row vector of names of its output variables,
65                 </listitem>
66                 <listitem>
67                     <varname>in</varname> is the row vector of names of its input variables, and
68                 </listitem>
69                 <listitem>
70                     <varname>text</varname> is the column vector of the source code of the function.
71                 </listitem>
72             </itemizedlist>
73         </para>
74         <para>
75             If <varname>x</varname> is a <literal>lib</literal> variable
76             (library), <varname>text</varname> is a character string column vector. The first element
77             contains the path of library file and the other the name of functions it defines.
78         </para>
79         <warning>
80             For any complex, real, integer, polynomial or rational input, the format of literal
81             numbers output from <function>string(..)</function> is managed by the
82             <link linkend="format">format</link> function (see examples).
83         </warning>
84         <para>
85             Note that string([]) returns [] (unchanged).
86         </para>
87     </refsection>
88     <refsection>
89         <title>Examples</title>
90         <programlisting role="example">
91             string(rand(2, 2))
92
93             deff("y = mymacro(x)", "y = x + 1")
94             [out, in, text] = string(mymacro)
95             x = 123.356;
96             disp("Result is " + string(x));
97
98             disp("/" + string(~%t) + "/");
99             disp("/" + string(%i+1) + "/");
100             disp("/" + string(int16(-123)) + "/");
101             disp("/" + string(1 + %s + %s^3) + "/");
102
103             string(corelib)
104
105             v = format();
106             disp(string(%pi))
107             format(24);
108             disp(string(%pi))
109             format(v(2))
110
111             string(1:4:$)
112         </programlisting>
113     </refsection>
114     <refsection role="see also">
115         <title>See also</title>
116         <simplelist type="inline">
117             <member>
118                 <link linkend="format">format</link>
119             </member>
120             <member>
121                 <link linkend="sci2exp">sci2exp</link>
122             </member>
123             <member>
124                 <link linkend="msprintf">msprintf</link>
125             </member>
126             <member>
127                 <link linkend="tree2code">tree2code</link>
128             </member>
129             <member>
130                 <link linkend="pol2str">pol2str</link>
131             </member>
132             <member>
133                 <link linkend="execstr">execstr</link>
134             </member>
135             <member>
136                 <link linkend="evstr">evstr</link>
137             </member>
138             <member>
139                 <link linkend="strtod">strtod</link>
140             </member>
141             <member>
142                 <link linkend="csvTextScan">csvTextScan</link>
143             </member>
144         </simplelist>
145     </refsection>
146     <refsection>
147         <title>History</title>
148         <revhistory>
149             <revision>
150                 <revnumber>5.4.0</revnumber>
151                 <revremark>
152                     Input of implicitlist typeof accepted.
153                 </revremark>
154             </revision>
155         </revhistory>
156     </refsection>
157 </refentry>