<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) ????-2008 - INRIA
 * Copyright (C) 2018 - Samuel GOUGEON
 *
 * Copyright (C) 2012 - 2016 - Scilab Enterprises
 *
 * 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="argn">
    <refnamediv>
        <refname>argn</refname>
        <refpurpose>Возвращает количество входных/выходных аргументов в вызове функции</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
           [lhs, rhs] = argn()
            lhs = argn(1)
            rhs = argn(2)
        </synopsis>
    </refsynopsisdiv>
    <refsection role="arguments">
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>lhs</term>
                <listitem>
                <para>
                  Количество ожидаемых выходных аргументов с левой стороны. Устанавливается в 1, когда
                  выходных аргументов не ожидается.
                </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>rhs</term>
                <listitem>
                <para>
                  Количество входных аргументов с правой стороны, указываемых при вызове функции.
                </para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Описание</title>
        <para>
            Эта функция используется внутри определения функции. Она даёт количество фактических входных
            аргументов (<literal>rhs</literal>) и выходных аргументов (<literal>lhs</literal>),
            переданных в функцию при её вызове. Она обычно используется в определениях функции для работы
            с необязательными аргументами.
        </para>
        <warning>
            Проверка существования именного входного аргумента с помощью <literal>isdef(..,"l")</literal>
            более надёжна, чем с помощью <literal>argn()</literal>. Пожалуйста, смотрите примеры.
        </warning>
    </refsection>
    <refsection>
        <title>Примеры</title>
        <para>Простые примеры:</para>
        <programlisting role="example"><![CDATA[
function [res, res2] = test(a, b)
  [lhs, rhs] = argn()
  [res, res2] = ("abc", %pi);
  disp([lhs rhs])  // <<<<<<<<<<<
endfunction

test();
test(4.321);
test(3, -1);
test(3, -1, a=0);
test(3, -1, c=8);

out1 = test();
[o1, o2] = test(%pi);
 ]]></programlisting>
    <screen><![CDATA[
--> test();
   1.   0.

--> test(4.321);
   1.   1.

--> test(3, -1);
   1.   2.

--> test(3, -1, a=0);
Неверное число аргументов.

--> test(3, -1, c=8);
Неверное число аргументов.

--> out1 = test();
   1.   0.

--> [o1, o2] = test(%pi);
   2.   1.
]]></screen>
    <para/>
    <para>С использованием varargin и varargout:</para>
        <programlisting role="example"><![CDATA[
function [res, varargout] = test(a, varargin)
  res = "abc";
  varargout = list(%i);
  [lhs, rhs] = argn()
  disp([lhs rhs])  // <<<<<<<<<<<
endfunction

test();
test(4.321);
test(3, -1);
test(3, -1, a=0);
test(3, -1, 8);

out1 = test();
[o1, o2] = test(%pi);
[o1, o2, o3] = test(%pi);
 ]]></programlisting>
    <screen><![CDATA[
--> test();
   1.   0.

--> test(4.321);
   1.   1.

--> test(3, -1);
   1.   2.

--> test(3, -1, a=0);
   1.   3.

--> test(3, -1, 8);
   1.   3.

--> out1 = test();
   1.   0.

--> [o1, o2] = test(%pi);
   2.   1.

--> [o1, o2, o3] = test(%pi);
   3.   1.
]]></screen>
    <para/>
    <para>Надёжная проверка существования входных аргументов:</para>
        <programlisting role="example"><![CDATA[
function res = test(a, b, varargin)
    res = ""
    if isdef("a","l")
        res = "a передана."
    end
    if isdef("b","l")
        res = res + " b передана."
    end
    if isdef("c","l")
        res = res + " c передана."
    end
endfunction
clc
test()
test(4.321)
test(4.321, %z)
test(b=3)
test(c=3)
test(-1, c=3)
test(-1, a=2, c=3)
test(b=-1, a=2, c=3)
 ]]></programlisting>
    <screen><![CDATA[
--> test()
 ans  =

--> test(4.321)
 ans  =
 a передана.

--> test(4.321, %z)
 ans  =
 a передана. b передана.

--> test(b=3)
 ans  =
  b передана.

--> test(c=3)
 ans  =
  c передана.

--> test(-1, c=3)
 ans  =
 a передана. c передана.

--> test(-1, a=2, c=3) // входные аргументы в varargin являются/становятся всегда безымянными
 ans  =
 a передана.

--> test(b=-1, a=2, c=3)
 ans  =
 a передана. b передана.
]]></screen>
    <para/>
    <para>Другое использование:</para>
        <programlisting role="example"><![CDATA[
function concat = myOwnFunction(name,optional)
  [lhs,rhs] = argn()
  if rhs <= 1 then
     optional="моё Необязательное значение"
  end
  if rhs == 0 then
     error("Ожидался по меньшей мере один аргумент")
  end
  concat = name+" "+optional
endfunction
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>Смотрите также</title>
        <simplelist type="inline">
            <member>
                <link linkend="isdef">isdef</link>
            </member>
            <member>
                <link linkend="varargin">varargin</link>
            </member>
            <member>
                <link linkend="varargout">varargout</link>
            </member>
            <member>
                <link linkend="macrovar">macrovar</link>
            </member>
            <member>
                <link linkend="function">function</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
