<?xml version="1.0" encoding="UTF-8"?>
<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="number_properties" xml:lang="en">
    <refnamediv>
        <refname>number_properties</refname>
        <refpurpose>determine floating-point parameters</refpurpose>
    </refnamediv>
    <refsynopsisdiv>
        <title>Syntax</title>
        <synopsis>pr = number_properties(prop)</synopsis>
    </refsynopsisdiv>
    <refsection>
        <title>Arguments</title>
        <variablelist>
            <varlistentry>
                <term>prop</term>
                <listitem>
                    <para>string</para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>pr</term>
                <listitem>
                    <para>real or boolean scalar</para>
                </listitem>
            </varlistentry>
        </variablelist>
    </refsection>
    <refsection>
        <title>Description</title>
        <para>This function may be used to get the characteristic
            numbers/properties of the floating point set denoted here by
            <literal>F(b,p,emin,emax)</literal> (usually the 64 bits float numbers set
            prescribe by IEEE 754). Numbers of <literal>F</literal> are of the
            form:
        </para>
        <para>
            <code>sign * m * b^e</code>
        </para>
        <para>
            <literal>e</literal> is the exponent and <literal>m</literal> the
            mantissa:
        </para>
        <latex>
            $$
            m = d_1 \cdot b^{-1} + d_2 \cdot b^{-2} + \ldots + d_p \cdot b^{-p}
            $$
        </latex>
        <para>
            <latex>$d_i$</latex> the digits are in <literal>[0, b-1]</literal>
            and <literal>e</literal> in <literal>[emin, emax]</literal>, the number is
            said "normalized" if <latex>$d_1 \neq 0$</latex>. The following queries may be used:
        <variablelist>
            <varlistentry>
                <term>prop = "radix"</term>
                <listitem>
                    <para>
                        then <literal>pr</literal> is the radix <literal>b</literal>
                        of the set <literal>F</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop = "digits"</term>
                <listitem>
                    <para>
                        then <literal>pr</literal> is the number of digits
                        <literal>p</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop = "huge"</term>
                <listitem>
                    <para>
                        then <literal>pr</literal> is the max positive float of
                        <literal>F</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop = "tiny"</term>
                <listitem>
                    <para>
                        then <literal>pr</literal> is the min positive normalized
                        float of <literal>F</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop = "denorm"</term>
                <listitem>
                    <para>
                        then <literal>pr</literal> is a boolean (%t if denormalized
                        numbers are used)
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop = "tiniest"</term>
                <listitem>
                    <para>
                        then if denorm = %t, <literal>pr</literal> is the min positive
                        denormalized number else <literal>pr</literal> = tiny
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop = "eps"</term>
                <listitem>
                    <para>
                        then <literal>pr</literal> is the epsilon machine ( generally
                        (<latex>$\dfrac{b^{1-p}}{2}$</latex>) which is the relative max error
                        between a real <literal>x</literal> (such than
                        <literal>|x|</literal> in <literal>[tiny, huge]</literal>) and
                        <literal>fl(x)</literal>, its floating point approximation in
                        <literal>F</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop = "minexp"</term>
                <listitem>
                    <para>
                        then <literal>pr</literal> is <literal>emin</literal>
                    </para>
                </listitem>
            </varlistentry>
            <varlistentry>
                <term>prop = "maxexp"</term>
                <listitem>
                    <para>
                        then <literal>pr</literal> is <literal>emax</literal>
                    </para>
                </listitem>
            </varlistentry>
        </variablelist>
      </para>
        <note>
            This function uses the lapack routine <literal>dlamch</literal> to get the machine
            parameters (the names (radix, digit, huge, etc...) are those recommended by the LIA 1
            standard and are different from the corresponding lapack's ones).
        </note>
        <warning>
          Sometimes you can see the following definition for the epsilon machine :
          <latex>$eps = b^{1-p}$</latex> but in this function we use the traditional one
          (see prop = "eps" before) and so <latex>$eps = \dfrac{b^{1-p}}{2}$</latex>
          if normal rounding occurs, and <latex>$eps = b^{1-p}$</latex> otherwise.
        </warning>
    </refsection>
    <refsection>
        <title>Examples</title>
        <programlisting role="example"><![CDATA[
b = number_properties("radix")
eps = number_properties("eps")
 ]]></programlisting>
    </refsection>
    <refsection role="see also">
        <title>See also</title>
        <simplelist type="inline">
            <member>
                <link linkend="nearfloat">nearfloat</link>
            </member>
            <member>
                <link linkend="log2">log2</link>
            </member>
            <member>
                <link linkend="signed_zero">-0</link>
            </member>
        </simplelist>
    </refsection>
</refentry>
