<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2018 - 2023 - Samuel GOUGEON
 *
 * This file is hereby licensed under the terms of the GNU GPL v2.0,
 * pursuant to article 5.3.4 of the CeCILL v.2.1.
 * This file was originally licensed under the terms of the CeCILL v2.1,
 * and continues to be available under such terms.
 * For more information, see the COPYING file which you should have received
 * along with this program.
 *
 -->
<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="ru" xml:id="for">
    <refnamediv>
        <refname>for</refname>
        <refpurpose>ключевое слово для циклов</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
            for variable = expression, instruction ; .. ; instruction; end

            for variable = expression
                instruction
                ..
                instruction
            end

            for variable = expression do
                instruction
                ..
                instruction
            end
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>variable</term>
                <listitem>
                    <para>
                        переменная, по которой ведётся цикл;
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>expression</term>
                <listitem>
                    <para>
                        выражение, описывающее закон изменения переменной <literal>variable</literal>
                        в заданных пределах; может быть вектором, матрицей, списком;
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>instruction</term>
                <listitem>
                    <para>
                        любые корректные инструкции Scilab.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>do</term>
                <listitem>
                    <para>
                        ключевое слово, отделяющее блок определения переменной цикла <literal>variable</literal>
                        от блока инструкций <literal>instruction</literal>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
            Если <literal>источник</literal> является массивом (однородным или нет), то
            <literal>элемент</literal> устанавливается в каждый из его столбцов (для гиперматрицы,
            как <literal>matrix(expression, size(expression,1), -1))</literal>), один за другим.
        </para>
        <para>
            Оператор двоеточие <link linkend="colon">colon</link> используется для создания вектор-столбцов с регулярным
            шагом между элементами и похож на традиционные циклы <literal>for</literal>:
            <literal>for variable = n1:step:n2, ..., end</literal>
        </para>
        <para>
            Если <literal>expression</literal> является списком, то <literal>variable</literal>
            принимает значения списка одно за другим.
        </para>
        <para>
            В соответствии с договорённостями по написанию кода  в Scilab рекомендуется:
        </para>
        <itemizedlist>
            <listitem>
                <para>
                    начинать новую инструкцию на новой строке;
                </para>
            </listitem>
            <listitem>
                <para>
                    писать не более одной простой инструкции на одной строке;
                </para>
            </listitem>
            <listitem>
                <para>
                    разбивать составные инструкции на множество строк.
                </para>
            </listitem>
        </itemizedlist>
        <para>
            Например, используйте:
        </para>
        <programlisting><![CDATA[
for i = 1:5
    disp(i);
end
]]></programlisting>
        <para>а не:</para>
        <programlisting><![CDATA[
for i = 1:5, disp(i); end
]]></programlisting>
    </refsection>

    <refsection>
        <title>Примеры</title>
        <para>Тривиальные итерации (над столбцами вектора строк) :</para>
        <programlisting role="example"><![CDATA[
for i = [2 4 5]
    factorial(i)
end

// По убыванию стоимости :
for j = 4:-1:1
    j
end
 ]]></programlisting>

        <para>цикл по столбцам матрицы :</para>
        <programlisting role="example"><![CDATA[
M = [1 2 ; 3 4 ; 5 6]'
for  c = M, c, end
 ]]></programlisting>
    <screen><![CDATA[
-> M = [1 2 ; 3 4 ; 5 6]'
 M  =
   1.   3.   5.
   2.   4.   6.

--> for  c = M, c, end
 c  =
   1.
   2.

 c  =
   3.
   4.

 c  =
   5.
   6.
]]></screen>

        <para>Iterate on the columns of a cells array:</para>
        <programlisting role="example"><![CDATA[
C = {%pi, "This is πι" ; %z^2, %t}
for  c = C, c, end
 ]]></programlisting>
    <screen><![CDATA[
--> C = {%pi, "This is πι" ; %z^2, %t}
 C  =
  [1x1 constant  ]  [1x1 string ]
  [1x1 polynomial]  [1x1 boolean]


--> for  c = C, c, end
 c  =
  [1x1 constant  ]
  [1x1 polynomial]

 c  =
  [1x1 string ]
  [1x1 boolean]
]]></screen>

        <para>цикл по элементам списка :</para>
        <programlisting role="example"><![CDATA[
for l = list([1 2;3 4], (1+%z)^3, 'example', [%F %T]); l, end
 ]]></programlisting>
    <screen><![CDATA[
--> for l = list([1 2;3 4], (1+%z)^3, 'example', [%F %T]); l, end
 l  =
   1.   2.
   3.   4.

 l  =
            2   3
   1 +3z +3z  +z

 l  =
 example

 l  =
  F T
]]></screen>

        <para>Общие и вложенные итерированные циклы :</para>
        <programlisting role="example"><![CDATA[
n=5;
for i = 1:n
    for j = 1:n
        a(i,j) = 1/(i+j-1);
    end;
end
for j = 2:n-1
    a(j,j) = j;
end;
a

for v = a, write(%io(2),v), end
for j = 1:n, v = a(:,j), write(%io(2),v), end
     ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="while">while</link>
            </member>
            <member>
                <link linkend="end">end</link>
            </member>
            <member>
                <link linkend="do">do</link>
            </member>
        </simplelist>
    </refsection>
    <refsection role="history">
        <title>История</title>
        <revhistory>
            <revision>
                <revnumber>6.0.0</revnumber>
                <revdescription>
                    Теперь for <literal>expression</literal> может быть вектором указателей на графические окна.
                    <literal>for</literal> is now protected:
                    Assignments like <literal>for=1</literal> are no longer possible.
                </revdescription>
            </revision>
            <revision>
                <revnumber>2023.0.0</revnumber>
                <revdescription>
                    The <literal>expression</literal> can be a hypermatrix. It is then processed
                    by column as <literal>matrix(expression, size(expression,1), -1)</literal>.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
