<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2008 - INRIA
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 * Copyright (C) 2016, 2018 - 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:ns5="http://www.w3.org/1999/xhtml"
          xmlns:mml="http://www.w3.org/1998/Math/MathML" xmlns:db="http://docbook.org/ns/docbook"
          xmlns:scilab="http://www.scilab.org" xml:id="linspace" xml:lang="ru">
    <refnamediv>
        <refname>linspace</refname>
        <refpurpose>генерирует линейно распределённые числа между двумя достижимыми границами</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
            row = linspace(x1, x2)
            row = linspace(x1, x2, n)
            Matrix = linspace(Col1, Col2)
            Matrix = linspace(Col1, Col2, n)
        </synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>x1, x2</term>
                <listitem>
                    <para>
                        Вещественные или комплексные скаляры, или кодированные целочисленные скаляры:
                        границы между которыми должны быть сгенерированы значения.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Col1, Col2</term>
                <listitem>
                    <para>
                        Вектор-столбцы одинаковой высоты, состоящие из вещественных или комплексных
                        чисел или кодированных целочисленных скаляров.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>n</term>
                <listitem>
                    <para>
                        целое количество запрошенных значений или столбцов.
                        Значение по умолчанию: 100.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>row</term>
                <listitem>
                    <para>
                        вектор-строка из <varname>n</varname> чисел.
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>Matrix</term>
                <listitem>
                    <para>
                        Матрица, в которой <varname>n</varname> столбцов чисел.
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
            <code>linspace(x1, x2)</code> генерирует   вектор-строку из
            <varname>n</varname> равномерно распределённых значений в диапазоне
            точно от <varname>x1</varname> до <varname>x2</varname>.
        </para>
        <note>
            <para>
                Синтаксис <code>y1:y2</code> или <code>y1:step:y2</code>
                наподобие <code>1:0.1:%pi</code> делает то же самое, но фиксирует
                начальную границу <varname>y1</varname> и
                <emphasis role="bold">шаг</emphasis> <varname>step</varname>.
                Переменная <varname>y2</varname> используется в качестве границы
                остановки, через которую нельзя переступить. Последнее значение,
                которое фактически будет сгенерировано, может не достичь её. В
                этом случае <varname>y2</varname> не включено в результат.
            </para>
            <para>
                Вместо фиксированного шага указанным значением, функция
                <function>linspace</function> фиксирует конечную границу
                <varname>x2</varname>, которая точно <emphasis role="bold">будет достигнута</emphasis>
                и вычисляет соответствующий шаг.
            </para>
        </note>
        <para>
            Если <varname>x1</varname> или <varname>x2</varname> являются комплексными
            числами, то <code>linspace(x1,x2)</code> интерполирует отдельно вещественную
            и мнимую части <varname>x1</varname> и <varname>x2</varname>.
        </para>
        <para>
            Если указаны вектор-столбцы <varname>Col1</varname> и <varname>Col2</varname>,
            то функция <function>linspace</function> работает по строкам: результирующая
            матрица <varname>Matrix</varname> имеет то же количество строк и
            <varname>n</varname> столбцов, которое мы получим <code>Matrix(i,:) = linspace(Col1(i), Col2(i), n)</code>.
        </para>
        <warning>
            В случае, когда указанные границы являются кодированными целыми числами, то фактический шаг
            может колебаться на единицу в последовательности.
        </warning>
    </refsection>
    <refsection>
        <title>Примеры</title>
        <programlisting role="example"><![CDATA[
linspace(1, %pi, 0)         // n = 0
linspace(1, 2, 10)          // x2 > x1 : значения увеличиваются
linspace(2, 1, 10)          // x2 < x1 : значения уменьшаются
linspace(1+%i, 2-2*%i, 5)      // с комплексными числами
linspace([1:4]', [5:8]', 10)   // со столбцами на входе
 ]]></programlisting>
        <screen><![CDATA[--> linspace(1, %pi, 0)    // n = 0
 ans  =
    []

--> linspace(1, 2, 10)    // x2 > x1 : значения увеличиваются
 ans  =
   1.   1.111   1.222   1.333   1.444   1.556   1.667   1.778   1.889   2.

--> linspace(2, 1, 10)    // x2 &lt; x1 : значения уменьшаются
 ans  =
   2.   1.889   1.778   1.667   1.556   1.444   1.333   1.222   1.111   1.

--> linspace(1+%i, 2-2*%i, 5)      // с комплексными числами
 ans  =
   1. +i     1.25 +0.25i   1.5 -0.5i   1.75 -1.25i   2. -2.i

--> linspace([1:4]', [5:8]', 10)   // со столбцами на входе
 ans  =
   1.   1.444   1.889   2.333   2.778   3.222   3.667   4.111   4.556   5.
   2.   2.444   2.889   3.333   3.778   4.222   4.667   5.111   5.556   6.
   3.   3.444   3.889   4.333   4.778   5.222   5.667   6.111   6.556   7.
   4.   4.444   4.889   5.333   5.778   6.222   6.667   7.111   7.556   8.
]]></screen>
    <para/>
    <para>
        <emphasis role="bold">С кодированными целыми числами:</emphasis>
        Шаг может колебаться на единицу в последовательности:
    </para>
        <programlisting role="example"><![CDATA[
x = linspace(int8([5;127]), int8([127;5]), 10)
x(:,1:$-1) - x(:,2:$)
 ]]></programlisting>
        <screen><![CDATA[
--> x = linspace(int8([5;127]), int8([127;5]), 10)
 ans  =
    5   18   32  45  59  72  86  99  113  127
  127  114  100  87  73  60  46  33   19    5

--> x(:,1:$-1) - x(:,2:$)
 ans  =
 -13 -14 -13 -14 -13 -14 -13 -14 -14
  13  14  13  14  13  14  13  14  14
]]></screen>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="colon">colon</link>
            </member>
            <member>
                <link linkend="logspace">logspace</link>
            </member>
            <member>
                <link linkend="grand">grand</link>
            </member>
        </simplelist>
    </refsection>
    <refsection>
        <title>История</title>
        <revhistory>
            <revision>
                <revnumber>5.4.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>Могут быть указаны вектор-столбцы.
                        </listitem>
                        <listitem>Третьим входным аргументом (n) должно быть целое значение.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>6.0</revnumber>
                <revremark>
                    <itemizedlist>
                        <listitem>linspace(a, b, n&lt;=0) теперь возвращает [] вместо b.
                        </listitem>
                        <listitem>Границы теперь проверяются на значения %inf или %nan.
                        </listitem>
                    </itemizedlist>
                </revremark>
            </revision>
            <revision>
                <revnumber>6.0.2</revnumber>
                <revremark>
                    Теперь linspace() может быть надёжно использован для последовательностей кодированных целых чисел.
                </revremark>
            </revision>
        </revhistory>
    </refsection>
</refentry>
