<?xml version="1.0" encoding="UTF-8"?>
<!--
 * Scilab ( https://www.scilab.org/ ) - This file is part of Scilab
 * Copyright (C) 2016 - 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: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="format" xml:lang="ru">
    <refnamediv>
        <refname>format</refname>
        <refpurpose>установка выходного формата десятичных чисел по умолчанию</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Синтаксис</title>
        <synopsis>
            format(mode)
            format(width)
            format(width, mode)
            format(wm)
            mw = format()
        </synopsis>
    </refsynopsisdiv>
    <refsection role="parameters">
        <title>Аргументы</title>
        <variablelist>
            <varlistentry>
                <term>mode</term>
                <listitem>
                    <para>режим форматирования:
                        <itemizedlist>
                          <listitem>1 или "v": форматирование адаптированное к переменной. 
			    Scilab выбирает либо прямое представление (например -143.8757) либо
                            экспоненциальную/инженерную/научную запись (например -1.438E+02),
                            для того, чтобы справиться с каждым обрабатываемым значением, а также
			    с требуемой шириной, с максимальным количеством символов на выходе.
                          </listitem>
                          <listitem>0 или "e": Устанавливается экспоненциальная или инженерная запись
                            и используется для всех чисел.
                          </listitem>
                      </itemizedlist>
                  </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>width</term>
                <listitem>
                    <para>
		      ширина чесел равна количеству используемых символов на выходе, 
		      сюда включается всё: знак мантиссы, её цифры, десятичный разделить, символ
		      экспоненты, знак и цифры экспоненты. По умолчанию <varname>width</varname> равно 10.
		      Минимальная ширина в режиме <literal>e</literal> равна 8.
		    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>wm</term>
                <listitem>
                    <para>вектор для установки нового формата</para>
                    <para><literal>wm(1)</literal> это ширина</para>
                    <para><literal>wm(2)</literal> это режим форматирования: 0 для
                      <literal>'e'</literal> и 1 для <literal>'v'</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>mw</term>
                <listitem>
                    <para>
		      вектор, возвращающий параметры текущего форматирования:
                        <itemizedlist>
                          <listitem>
			    <literal>mw(1)</literal> это режим форматирования:
                            0 для <literal>'e'</literal> и 1 для <literal>'v'</literal>
                          </listitem>
                          <listitem>
                            <literal>mw(2)</literal> это ширина:
                            Количество символов, используемых для выдачи каждого числа.
                          </listitem>
                         </itemizedlist>
                     </para>
                 </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection role="description">
        <title>Описание</title>
            <note>
	      Для комплексных чисел вещественная и мнимые десятичные части выдаются в
	      соответствии с <literal>format(..)</literal>. Общая ширина комплексного
	      числа, следовательно, грубо говоря в два раза больше
	      (плюс один символ для обозначения мнимой единицы "i").
            </note>
            <note>
	      Кодированные целые числа никогда не выдаются в экспоненциальном режиме,
	      даже когда это форматирование является режимом по умолчанию, установленным
	      для десятичных чисел. Для них десятичный разделитель "." пропущен. Это
	      позволяет отличить их от десятичных целых чисел, которые имеют точку.
            </note>
            <note>
	      Для широкого формата, символы, которые могут быть отображены ниже относительной точности
	      <literal>%eps</literal>, установлены в 0.
            </note>
            <warning>
	      Установка формата десятичных чисел по умолчанию с помощью <function>format(..)</function>
	      является глобальным параметром: где бы вы его ни установили, он будет
	      потом применяться везде в Scilab и Xcos.
            </warning>
	  <para>
	    В старых версиях Scilab в режиме "формат переменной", вектор, элементы которого
	    меньше, чем в <literal>%eps</literal> раз максимального абсолютного значения
	    элементов, отображались как "0". Теперь функцию <function>clean</function> не
	    нужно использовать для установки ничтожно малых элементов в ноль.
	  </para>
    </refsection>
    <refsection role="examples">
        <title>Примеры</title>
        <programlisting role="example"><![CDATA[
// format() не принимается в расчёт для кодированных целых чисел
// -------------------------------------------------------------
format("e",8)
int32(2.^grand(3,5,"uin",0,30))
// format() влияет на вывод в командном окне disp(), string(), sci2exp(),...
// -------------------------------------------------------------------------
a = %pi; p = %pi + %z - %e*%z^2;
format("v",10);
a, p
disp(a,p)
string(a), string(p)
[sci2exp(a) sci2exp(p)]
format("e",15);
a, p
disp(a,p)
string(a), string(p)
[sci2exp(a) sci2exp(p)]
format("v",10); // сброс
// format() устанавливает ширину, не фиксированное количество символов:
// --------------------------------------------------------------------
format("v",10)
%pi*1e-217, s = string(%pi*1e-217)
length(s) // отсутствующим символом является явный знак "+"
// Это полезно для получения выравненного и полностью информативного отображения матриц
[ -1.234 %pi*1e-10 %nan ; %e*1e137 -%inf 54312]
// Начиная с Scilab 6.0, не имеющие значения символы, отображаемые широким format(), устанавливаются в 0:
format(22)
%pi
// format() имеет глобальное влияние
// ----------------------------
function myfun()
    format("e",20)
endfunction
format("v", 10)
disp(%pi)
myfun()
// он остаётся везде, где бы ни был установлен:
disp(%pi)
format("v",10) // сброс
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="number_properties">свойства чисел</link>
            </member>
            <member>
                <link linkend="string">string</link>
            </member>
            <member>
                <link linkend="sci2exp">sci2exp</link>
            </member>
            <member>
                <link linkend="disp">disp</link>
            </member>
            <member>
                <link linkend="print">print</link>
            </member>
            <member>
                <link linkend="clean">clean</link>
            </member>
            <member>
                <link linkend="printf_conversion">C-подобный формат</link>
            </member>
            <member>
                <link linkend="mprintf">mprintf</link>
            </member>
            <member>
                <link linkend="msprintf">msprintf</link>
            </member>
            <member>
                <link linkend="mfprintf">mfprintf</link>
            </member>
      </simplelist>
    </refsection>
    <refsection role="history">
        <title>История</title>
        <revhistory>
            <revision>
                <revnumber>6.0</revnumber>
                <revdescription>
		  Для широкого format(), символы, которые могут быть отображены
		  ниже относительной точности %eps, теперь устанавливаются в 0.
                </revdescription>
            </revision>
        </revhistory>
    </refsection>
</refentry>
