aa3cd2706d19d687a8da408e057b02984ead53e6
[scilab.git] / scilab / modules / elementary_functions / help / en_US / floating_point / format.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!--
3  * Scilab ( http://www.scilab.org/ ) - This file is part of Scilab
4  * Copyright (C) 2016 - Samuel GOUGEON
5  * Copyright (C) 2012 - 2016 - Scilab Enterprises
6  *
7  * This file is hereby licensed under the terms of the GNU GPL v2.0,
8  * pursuant to article 5.3.4 of the CeCILL v.2.1.
9  * This file was originally licensed under the terms of the CeCILL v2.1,
10  * and continues to be available under such terms.
11  * For more information, see the COPYING file which you should have received
12  * along with this program.
13  *
14  -->
15 <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="en">
16     <refnamediv>
17         <refname>format</refname>
18         <refpurpose>set the default output format of decimal numbers</refpurpose>
19     </refnamediv>
20     <refsynopsisdiv>
21         <title>Syntax</title>
22         <synopsis>
23             format(mode)
24             format(width)
25             format(mode, width)
26             format(wm)
27             v = format()
28         </synopsis>
29     </refsynopsisdiv>
30     <refsection role="parameters">
31         <title>Arguments</title>
32         <variablelist>
33             <varlistentry>
34                 <term>mode</term>
35                 <listitem>
36                     <para>formatting mode:
37                         <itemizedlist>
38                           <listitem>1 or "v": <emphasis role="bold">v</emphasis>ariable adaptative
39                             formatting. Scilab chooses either the direct representation
40                             (e.g. -143.8757) or
41                             the exponential/engineering/scientific notation (e.g. -1.438E+02),
42                             in order to cope with each processed value as well as with the
43                             required width, with a maximal number of output digits.
44                           </listitem>
45                           <listitem>0 or "e": The <emphasis role="bold">e</emphasis>xponential
46                             /<emphasis role="bold">e</emphasis>ngineering notation is forced
47                             and used for all numbers.
48                           </listitem>
49                       </itemizedlist>
50                   </para>
51                 </listitem>
52             </varlistentry>
53             <varlistentry>
54                 <term>width</term>
55                 <listitem>
56                     <para>width of numbers = number of output characters used, all included: sign of
57                       the mantissa, its digits, decimal separator, exponent symbol, sign and digits
58                       of the exponent. (default width = 10)</para>
59                 </listitem>
60             </varlistentry>
61             <varlistentry>
62                 <term>wm</term>
63                 <listitem>
64                     <para>a vector to set new format </para>
65                     <para><literal>wm(1)</literal> is the width</para>
66                     <para><literal>wm(2)</literal> is the formatting mode: 0 for
67                       <literal>'e'</literal> and 1 for <literal>'v'</literal>
68                     </para>
69                 </listitem>
70             </varlistentry>
71             <varlistentry>
72                 <term>v</term>
73                 <listitem>
74                     <para>vector returning the current formatting parameters:
75                         <itemizedlist>
76                           <listitem><literal>v(1)</literal> is the formatting mode:
77                             0 for <literal>'e'</literal> and 1 for <literal>'v'</literal>
78                           </listitem>
79                           <listitem><literal>v(2)</literal> is the width: Number of characters used
80                             to output each number.
81                           </listitem>
82                          </itemizedlist>
83                      </para>
84                  </listitem>
85             </varlistentry>
86         </variablelist>
87     </refsection>
88     <refsection role="description">
89         <title>Description</title>
90             <note>For complex numbers, each real and imaginary decimal part is output according to
91              format(..). The total width of a complex number is therefore roughly twice greater (+ 1
92               character for "i" symbol).
93             </note>
94             <note>Encoded integers are never output according to the "e"xponential mode, even when
95                 this formatting is the default mode set for decimal numbers. For them, the decimal
96                 separator "." is skipped. This allows to distinguish them from decimal integers
97                 that have a dot.
98             </note>
99             <note>For wide format(), digits that may be displayed beyond the
100                 relative accuracy <literal>%eps</literal> are set to 0.
101             </note>
102             <warning>The default decimal format set with
103                 <function>format(..)</function> is a global parameter:
104                 Wherever you set it, it then applies everywhere in Scilab and Xcos.
105             </warning>
106         <para>In the old Scilab versions, in "variable format" mode, vector
107             entries which are less than <literal>%eps</literal> times the maximum absolute value of the
108             entries were displayed as "0". It is no more the case, the clean function
109             can be used to set negligible entries to zeros.
110         </para>
111     </refsection>
112     <refsection role="examples">
113         <title>Examples</title>
114         <programlisting role="example"><![CDATA[
115 // format() is not taken into account for encoded integers
116 // -------------------------------------------------------
117 format("e",6)
118 int32(2.^grand(3,5,"uin",0,30))
119
120 // format() impacts console's output, disp(), string(), sci2exp(),...
121 // --------------------------------------------------------------
122 a = %pi; p = %pi + %z - %e*%z^2;
123 format("v",10);
124 a, p
125 disp(a,p)
126 string(a), string(p)
127 [sci2exp(a) sci2exp(p)]
128
129 format("e",15);
130 a, p
131 disp(a,p)
132 string(a), string(p)
133 [sci2exp(a) sci2exp(p)]
134 format("v",10); // reset
135
136 // format() set the width, not a fixed number of digits:
137 // ----------------------------------------------------
138 format("v",10)
139 %pi*1e-217, s = string(%pi*1e-217)
140 length(s) // the missing char is the implicit "+" sign
141
142 // This is usefull to get aligned and fully informative display of matrices
143 [ -1.234 %pi*1e-10 %nan ; %e*1e137 -%inf 54312]
144
145 // Since Scilab 6.0, unrelevant digits displayed with wide format() are set to 0:
146 format(22)
147 %pi
148
149 // format() has a global impact
150 // ----------------------------
151 function myfun()
152     format("e",20)
153 endfunction
154 format("v", 10)
155 disp(%pi)
156 myfun()
157 // it remains everywhere, wherever it has been set:
158 disp(%pi)
159 format("v",10) // reset
160  ]]></programlisting>
161     </refsection>
162     <refsection role="see also">
163         <title>See Also</title>
164         <simplelist type="inline">
165             <member>
166                 <link linkend="number_properties">numbers properties</link>
167             </member>
168             <member>
169                 <link linkend="string">string</link>
170             </member>
171             <member>
172                 <link linkend="sci2exp">sci2exp</link>
173             </member>
174             <member>
175                 <link linkend="disp">disp</link>
176             </member>
177             <member>
178                 <link linkend="print">print</link>
179             </member>
180             <member>
181                 <link linkend="printf_conversion">C-like format</link>
182             </member>
183             <member>
184                 <link linkend="mprintf">mprintf</link>
185             </member>
186             <member>
187                 <link linkend="msprintf">msprintf</link>
188             </member>
189             <member>
190                 <link linkend="mfprintf">mfprintf</link>
191             </member>
192       </simplelist>
193     </refsection>
194     <refsection role="history">
195         <title>History</title>
196         <revhistory>
197             <revision>
198                 <revnumber>6.0</revnumber>
199                 <revdescription>For wide format(), digits that may be displayed
200                     beyond the relative accuracy %eps are now set to 0.
201                 </revdescription>
202             </revision>
203         </revhistory>
204     </refsection>
205 </refentry>