4f86803e3f5d2db8eb3c460d40e5befa0b287db7
[scilab.git] / scilab / modules / string / help / en_US / evstr.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) 2017 - Samuel GOUGEON
6  *
7  * Copyright (C) 2012 - 2016 - Scilab Enterprises
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:ns5="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="evstr" xml:lang="en">
21     <refnamediv>
22         <refname>evstr</refname>
23         <refpurpose>evaluates Scilab expressions and concatenates their results</refpurpose>
24     </refnamediv>
25     <refsynopsisdiv>
26         <title>Syntax</title>
27         <synopsis>
28             H = evstr(M)
29             H = evstr(list(M, subExpr))
30             [H, ierr] = evstr(..)
31         </synopsis>
32     </refsynopsisdiv>
33     <refsection>
34         <title>Arguments</title>
35         <variablelist>
36             <varlistentry>
37                 <term>M</term>
38                 <listitem>
39                     <para>
40                         single or vector or matrix of character strings: Scilab expressions to be
41                         evaluated and results to be concatenated.
42                     </para>
43                 </listitem>
44             </varlistentry>
45             <varlistentry>
46                 <term>subExpr</term>
47                 <listitem>
48                     <para>
49                     vector of character strings: sub-expressions to be pre-evaluated, defining
50                     quantities used in <literal>M</literal> expressions.
51                     </para>
52                 </listitem>
53             </varlistentry>
54             <varlistentry>
55                 <term>H</term>
56                 <listitem>
57                     <para>
58                         single element, vector, or matrix of concatenated results.
59                     </para>
60                 </listitem>
61             </varlistentry>
62             <varlistentry>
63                 <term>ierr</term>
64                 <listitem>
65                     <para>an integer, error indicator.</para>
66                 </listitem>
67             </varlistentry>
68         </variablelist>
69     </refsection>
70     <refsection>
71         <title>Description</title>
72         <para>
73             Evaluates expressions set in <varname>M</varname>. Then, concatenates their results
74             to build <varname>H</varname>.
75         </para>
76         <para>
77             All expressions are assumed to yield results of compatible types and sizes with respect
78             to their concatenation.
79         </para>
80         <para>
81             If the evaluation of <varname>M</varname> expressions or the concatenation of their
82             results leads to an error, <literal>H = evstr(M)</literal> yields the error as usual.
83             To avoid stopping to run next Scilab instructions,
84             <literal>[H, ierr] = evstr(M)</literal> can be used to catch the error.
85             <varname>H</varname> is then set to <literal>[]</literal> and <varname>ierr</varname>
86             returns <literal>999</literal> or another non-null positive code.
87         </para>
88         <para>
89             If <varname>M</varname> is provided through a list, Scilab expressions set in
90             <varname>subExpr</varname> are evaluated before evaluating <varname>M</varname>.
91             The results of these subexpressions must be referred to as <literal>%(k)</literal>
92             in <varname>M</varname>, where <literal>k</literal> is the subexpression's index in
93             <varname>subExpr</varname>.
94         </para>
95         <warning>
96             <itemizedlist>
97                 <listitem>
98                     <para>
99                     Assignments like <literal>"a = 1"</literal> are not accepted as expressions,
100                     neither in <varname>M</varname> nor in <varname>subExpr</varname>.
101                     <function>execstr</function> must be used instead to evaluate such expressions.
102                     </para>
103                 </listitem>
104                 <listitem>
105                     <para>
106                     Continuation marks <literal>".."</literal> are forbidden in expressions
107                     in <varname>M</varname> as well as in <varname>subExpr</varname>.
108                     </para>
109                 </listitem>
110             </itemizedlist>
111         </warning>
112         <note>Special aliases:
113             <itemizedlist>
114                 <listitem>
115                         <literal>"Nan"</literal> and <literal>"NaN"</literal> are parsed as
116                         <constant>%nan</constant>.
117                 </listitem>
118                 <listitem>
119                         <literal>"Inf"</literal> and <literal>"INF"</literal> are parsed as
120                         <constant>%inf</constant>.
121                 </listitem>
122             </itemizedlist>
123         </note>
124     </refsection>
125     <refsection>
126         <title>Examples</title>
127         <programlisting role="example"><![CDATA[
128 a = 1; b = 2;
129 Z = ['a', 'b'] ;
130 evstr(Z)
131
132 Z = list(['%(1)','%(1)-%(2)'],['a+1','b+1']);
133 evstr(Z)
134
135 evstr('NaN'), evstr('Inf')
136
137 //The two return values version
138 [H, ierr] = evstr(Z) // no error
139 Z = ['a', 'b', 'c'] ;// the variable c is undefined
140 [H, ierr] = evstr(Z) // error 4: Undefined variable: c
141 ]]>    </programlisting>
142     </refsection>
143     <refsection role="see also">
144         <title>See also</title>
145         <simplelist type="inline">
146             <member>
147                 <link linkend="execstr">execstr</link>
148             </member>
149             <member>
150                 <link linkend="sci2exp">sci2exp</link>
151             </member>
152             <member>
153                 <link linkend="strtod">strtod</link>
154             </member>
155             <member>
156                 <link linkend="brackets">concatenation</link>
157             </member>
158         </simplelist>
159     </refsection>
160     <refsection role="history">
161         <title>History</title>
162         <revhistory>
163             <revision>
164                 <revnumber>5.3.0</revnumber>
165                 <revdescription>
166                 <literal>"Nan"</literal> and <literal>"NaN"</literal> are now parsed as <literal>%nan</literal>.
167                 <literal>"Inf"</literal> and <literal>"INF"</literal> are now parsed as <literal>%inf</literal>.
168                 </revdescription>
169             </revision>
170             <revision>
171                 <revnumber>6.0.1</revnumber>
172                 <revdescription>
173                   Simple comments are now supported in almost all possible input expressions,
174                   whatever is the shape of <literal>M</literal>.
175                 </revdescription>
176             </revision>
177         </revhistory>
178     </refsection>
179 </refentry>