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