62974984e55052aa8461b7b258929d9fb7d6c2fb
[scilab.git] / scilab / modules / core / help / en_US / control_flow / while.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="while">
3     <refnamediv>
4         <refname>while</refname>
5         <refpurpose> while keyword</refpurpose>
6     </refnamediv>
7     <refsection>
8         <title>Description</title>
9         <para>
10             The <literal>while</literal> clause must be terminated by
11             <literal>"end"</literal>.
12         </para>
13         <para>
14             <literal>while expr ,instructions,...[,else instructions], end</literal>
15         </para>
16         <para>
17             <literal>while expr do instructions,...[,else instructions], end</literal>
18         </para>
19         <para>
20             <literal>while expr then instructions,...[,else instructions], end</literal>
21         </para>
22         <para>Notes:</para>
23         <itemizedlist>
24             <listitem>
25                 <para>
26                     The only constraint is that each <literal>then</literal> or
27                     <literal>do</literal> keyword must be on the same line line as
28                     <literal>while</literal> keyword.
29                 </para>
30             </listitem>
31             <listitem>
32                 <para>
33                     Keywords <literal>then</literal> or <literal>do</literal> can
34                     be replaced by a carriage return or a comma. For compatibility
35                     with Matlab it is also possible, but not recommended, to put a
36                     space between the end of the expression and the beginning of
37                     the first instruction. 
38                 </para>
39             </listitem>
40             <listitem>
41                 <para>
42                     The optional <literal>,else instructions</literal> construction
43                     allows to gives <literal>instructions</literal> which are executed when 
44                     <literal>expr</literal> expression becomes false.
45                 </para>
46             </listitem>
47         </itemizedlist>
48         <para>
49             According to the Code Conventions for the Scilab Programming Language it is recommended:
50         </para>
51         <itemizedlist>
52             <listitem>
53                 <para>
54                     Start each statement on a new line.
55                 </para>
56             </listitem>
57             <listitem>
58                 <para>
59                     Write no more than one simple statement per line.
60                 </para>
61             </listitem>
62             <listitem>
63                 <para>
64                     Break compound statements over multiple lines.
65                 </para>
66             </listitem>
67         </itemizedlist>
68         <para>
69             For example, use:
70         </para>
71         <programlisting role=""><![CDATA[
72       i = 0
73       while i<5 
74           disp("i");
75           i = i + 1; 
76       end
77 ]]></programlisting>
78         <para>
79             rather than
80         </para>
81         <programlisting role=""><![CDATA[
82       i = 0; while i<5 disp("i"); i = i + 1; end
83 ]]></programlisting>
84         <para>
85             Warning: the number of characters used to define the body of any
86             conditional instruction (if while for or select/case) must be
87             limited to 16k.
88         </para>
89     </refsection>
90     <refsection>
91         <title>Examples</title>
92         <programlisting role="example"><![CDATA[ 
93 e=1; a=1; k=1;
94 while norm(a-(a+e),1) > %eps, 
95     e=e/2; 
96     k=k+1; 
97 end
98 e,k
99  ]]></programlisting>
100     </refsection>
101     <refsection role="see also">
102         <title>See Also</title>
103         <simplelist type="inline">
104             <member>
105                 <link linkend="for">for</link>
106             </member>
107             <member>
108                 <link linkend="select">select</link>
109             </member>
110             <member>
111                 <link linkend="break">break</link>
112             </member>
113             <member>
114                 <link linkend="return">return</link>
115             </member>
116             <member>
117                 <link linkend="pause">pause</link>
118             </member>
119         </simplelist>
120     </refsection>
121 </refentry>