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>