78e9e883d1041aee95b32d4337be3b05eb22afae
[scilab.git] / scilab / modules / elementary_functions / help / en_US / floating_point / number_properties.xml
1 <?xml version="1.0" encoding="UTF-8"?>
2 <refentry version="5.0-subset Scilab" xml:id="number_properties" xml:lang="en"
3           xmlns="http://docbook.org/ns/docbook"
4           xmlns:xlink="http://www.w3.org/1999/xlink"
5           xmlns:svg="http://www.w3.org/2000/svg"
6           xmlns:ns5="http://www.w3.org/1999/xhtml"
7           xmlns:mml="http://www.w3.org/1998/Math/MathML"
8           xmlns:db="http://docbook.org/ns/docbook">
9   <info>
10     <pubdate>$LastChangedDate$</pubdate>
11   </info>
12
13   <refnamediv>
14     <refname>number_properties</refname>
15
16     <refpurpose>determine floating-point parameters</refpurpose>
17   </refnamediv>
18
19   <refsynopsisdiv>
20     <title>Calling Sequence</title>
21
22     <synopsis>pr = number_properties(prop)</synopsis>
23   </refsynopsisdiv>
24
25   <refsection>
26     <title>Arguments</title>
27
28     <variablelist>
29       <varlistentry>
30         <term>prop</term>
31
32         <listitem>
33           <para>string</para>
34         </listitem>
35       </varlistentry>
36
37       <varlistentry>
38         <term>pr</term>
39
40         <listitem>
41           <para>real or boolean scalar</para>
42         </listitem>
43       </varlistentry>
44     </variablelist>
45   </refsection>
46
47   <refsection>
48     <title>Description</title>
49
50     <para>This function may be used to get the characteristic
51     numbers/properties of the floating point set denoted here by
52     <literal>F(b,p,emin,emax)</literal> (usually the 64 bits float numbers set
53     prescribe by IEEE 754). Numbers of <literal>F</literal> are of the
54     form:</para>
55
56     <programlisting role = ""><![CDATA[ 
57 sign * m * b^e
58  ]]></programlisting>
59
60     <para><literal>e</literal> is the exponent and <literal>m</literal> the
61     mantissa:</para>
62
63     <programlisting role = ""><![CDATA[ 
64 m = d_1 b^(-1) + d_2 b^(-2) + .... + d_p b^(-p)
65  ]]></programlisting>
66
67     <para><literal>d_i</literal> the digits are in <literal>[0, b-1]</literal>
68     and <literal>e</literal> in <literal>[emin, emax]</literal>, the number is
69     said "normalised" if <literal>d_1 ~= 0</literal>. The following may be
70     gotten:</para>
71
72     <variablelist>
73       <varlistentry>
74         <term>prop = "radix"</term>
75
76         <listitem>
77           <para>then <literal>pr</literal> is the radix <literal>b</literal>
78           of the set <literal>F</literal></para>
79         </listitem>
80       </varlistentry>
81
82       <varlistentry>
83         <term>prop = "digits"</term>
84
85         <listitem>
86           <para>then <literal>pr</literal> is the number of digits
87           <literal>p</literal></para>
88         </listitem>
89       </varlistentry>
90
91       <varlistentry>
92         <term>prop = "huge"</term>
93
94         <listitem>
95           <para>then <literal>pr</literal> is the max positive float of
96           <literal>F</literal></para>
97         </listitem>
98       </varlistentry>
99
100       <varlistentry>
101         <term>prop = "tiny"</term>
102
103         <listitem>
104           <para>then <literal>pr</literal> is the min positive normalised
105           float of <literal>F</literal></para>
106         </listitem>
107       </varlistentry>
108
109       <varlistentry>
110         <term>prop = "denorm"</term>
111
112         <listitem>
113           <para>then <literal>pr</literal> is a boolean (%t if denormalised
114           numbers are used)</para>
115         </listitem>
116       </varlistentry>
117
118       <varlistentry>
119         <term>prop = "tiniest"</term>
120
121         <listitem>
122           <para>then if denorm = %t, <literal>pr</literal> is the min positive
123           denormalised number else <literal>pr</literal> = tiny</para>
124         </listitem>
125       </varlistentry>
126
127       <varlistentry>
128         <term>prop = "eps"</term>
129
130         <listitem>
131           <para>then <literal>pr</literal> is the epsilon machine ( generally
132           (<literal>b^(1-p))/2</literal> ) which is the relative max error
133           between a real <literal>x</literal> (such than
134           <literal>|x|</literal> in <literal>[tiny, huge]</literal>) and
135           <literal>fl(x)</literal>, its floating point approximation in
136           <literal>F</literal></para>
137         </listitem>
138       </varlistentry>
139
140       <varlistentry>
141         <term>prop = "minexp"</term>
142
143         <listitem>
144           <para>then <literal>pr</literal> is <literal>emin</literal></para>
145         </listitem>
146       </varlistentry>
147
148       <varlistentry>
149         <term>prop = "maxexp"</term>
150
151         <listitem>
152           <para>then <literal>pr</literal> is <literal>emax</literal></para>
153         </listitem>
154       </varlistentry>
155     </variablelist>
156   </refsection>
157
158   <refsection>
159     <title>Remarks</title>
160
161     <para>This function uses the lapack routine dlamch to get the machine
162     parameters (the names (radix, digit, huge, etc...) are those recommended
163     by the LIA 1 standard and are different from the corresponding lapack's
164     ones) ; CAUTION: sometimes you can see the following definition for the
165     epsilon machine : <literal>eps = b^(1-p)</literal> but in this function we
166     use the traditionnal one (see prop = "eps" before) and so <literal>eps =
167     (b^(1-p))/2</literal> if normal rounding occurs and <literal>eps =
168     b^(1-p)</literal> if not.</para>
169   </refsection>
170
171   <refsection>
172     <title>Examples</title>
173
174     <programlisting role="example"><![CDATA[ 
175 b = number_properties("radix")
176 eps = number_properties("eps")
177  ]]></programlisting>
178   </refsection>
179
180   <refsection role="see also">
181 <title>See Also</title>
182
183     <simplelist type="inline">
184       <member><link linkend="nearfloat">nearfloat</link></member>
185
186       <member><link linkend="frexp">frexp</link></member>
187     </simplelist>
188   </refsection>
189
190   <refsection>
191     <title>Authors</title>
192
193     <para>Bruno Pincon</para>
194   </refsection>
195 </refentry>