Add also the examples in core help pages in the russian help page (port of modificati...
[scilab.git] / scilab / modules / core / help / en_US / control_flow / return.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:svg="http://www.w3.org/2000/svg" xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook" xmlns:scilab="http://www.scilab.org" xml:lang="en" xml:id="return">
3     <refnamediv>
4         <refname>return</refname>
5         <refpurpose>return or resume execution and copy some local variables</refpurpose>
6     </refnamediv>
7     <refsynopsisdiv>
8         <title>Calling Sequence</title>
9         <synopsis>return
10             [x1,..,xn]=return(a1,..,an)
11         </synopsis>
12     </refsynopsisdiv>
13     <refsection>
14         <title>Arguments</title>
15         <variablelist>
16             <varlistentry>
17                 <term>x1,..,xn</term>
18                 <listitem>
19                     <para>variables in calling environment</para>
20                 </listitem>
21             </varlistentry>
22             <varlistentry>
23                 <term>a1,..,an</term>
24                 <listitem>
25                     <para>local variables</para>
26                 </listitem>
27             </varlistentry>
28         </variablelist>
29     </refsection>
30     <refsection>
31         <title>Description</title>
32         <para>
33             In a function <code>return</code> stops the execution of the function,
34             <literal>[x1,..,xn]=return(a1,..,an)</literal> stops the execution of the function and put 
35             the local variables <varname>ai</varname> in calling environment under names
36             <varname>xi</varname>.
37         </para>
38         <para>
39             In <code>pause</code> mode, it allows to return to upper level.
40             <literal>[x1,..,xn]=return(a1,..,an)</literal> returns to upper level and put the local 
41             variables <varname>ai</varname> in calling environment under names <varname>xi</varname>.
42         </para>
43         <para>
44             In an <code>execstr</code> called by a function
45             <literal>[x1,..,xn]=return(a1,..,an)</literal> stops the execution of the function and put 
46             the local variables <varname>ai</varname> in calling environment under names
47             <varname>xi</varname>.
48         </para>
49         <para>
50             The statement <code>resume</code> is equivalent to <code>return</code>.
51         </para>
52         <para>
53             <note>
54                 Note: the usage of this feature can complexify the code. Instead, the syntax <code>function b = foo()</code> is recommended.
55             </note>
56         </para>
57     </refsection>
58     <refsection>
59         <title>Examples</title>
60         <programlisting role="example"><![CDATA[
61 function foo(a)
62          a=a+1
63          b=resume(a)
64          c=52
65 endfunction
66
67 foo(42);
68 assert_checkequal(b,43)
69 // c does not exist
70
71  ]]></programlisting>
72     </refsection>
73     
74     <refsection role="see also">
75         <title>See Also</title>
76         <simplelist type="inline">
77             <member>
78                 <link linkend="abort">abort</link>
79             </member>
80             <member>
81                 <link linkend="break">break</link>
82             </member>
83             <member>
84                 <link linkend="execstr">execstr</link>
85             </member>
86             <member>
87                 <link linkend="resume">resume</link>
88             </member>
89         </simplelist>
90     </refsection>
91 </refentry>