
% Copyright (c) 1991-2002, The Numerical ALgorithms Group Ltd.
% All rights reserved.
%
% Redistribution and use in source and binary forms, with or without
% modification, are permitted provided that the following conditions are
% met:
%
%     - Redistributions of source code must retain the above copyright
%       notice, this list of conditions and the following disclaimer.
%
%     - Redistributions in binary form must reproduce the above copyright
%       notice, this list of conditions and the following disclaimer in
%       the documentation and/or other materials provided with the
%       distribution.
%
%     - Neither the name of The Numerical ALgorithms Group Ltd. nor the
%       names of its contributors may be used to endorse or promote products
%       derived from this software without specific prior written permission.
%
% THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
% IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
% TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A
% PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER
% OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
% EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
% PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES-- LOSS OF USE, DATA, OR
% PROFITS-- OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
% LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
% NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
% SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.


%
% DFLOAT.htex

\Language{} provides two kinds of floating point numbers.
The domain \spadtype{Float} (abbreviation \spadtype{FLOAT})
implements a model of arbitrary
\index{floating point!arbitrary precision}
precision floating point numbers.
\exptypeindex{Float}
The domain \spadtype{DoubleFloat} (abbreviation \spadtype{DFLOAT})
is intended to make available
\index{floating point!hardware}
hardware floating point arithmetic in \Language{}.
The actual model of floating point \spadtype{DoubleFloat} that provides is
system-dependent.  In the past there were wide variety of
floating point formats.
For example, the IBM system 370 used hexadecimal format such that double
precision number had fourteen hexadecimal digits of precision or roughly
sixteen decimal digits.  All system currently supported by \Language{}
use IEEE binary format with 64-bit double having sign bit, 11 exponents
bits and 53 significant bits (that adds to 65, but most significant
bit is 1 and there is no need to store it).

Arbitrary precision floats allow the user to specify the
precision at which arithmetic operations are computed.
Although this is an attractive facility, it comes at a cost.
Arbitrary-precision floating-point arithmetic typically takes
twenty to two hundred times more time than hardware floating point.

The usual arithmetic and elementary functions are available for
\spadtype{DoubleFloat}.
Use \spadsys{)show DoubleFloat} to get a list of operations or
the \HyperName{} \Browse{} facility to get more extensive
documentation about \spadtype{DoubleFloat}.

\xtc{
By default, floating point numbers that you enter into \Language{}
are of type \spadtype{Float}.
}{
\spadcommand{2.71828}
}
You must therefore tell \Language{} that you want to use
\spadtype{DoubleFloat} values and operations.
The following are some conservative guidelines for getting
\Language{} to use \spadtype{DoubleFloat}.

\xtc{
To get a value of type \spadtype{DoubleFloat}, use a target with
\spadSyntax{@}, \ldots
}{
\spadcommand{2.71828@DoubleFloat}
}
\xtc{
a conversion, \ldots
}{
\spadcommand{2.71828 :: DoubleFloat}
}
\xtc{
or an assignment to a declared variable.
It is more efficient if you use a target rather than an explicit or
implicit conversion.
}{
\spadcommand{eApprox : DoubleFloat := 2.71828 \bound{eApprox}}
}

\xtc{
You also need to declare functions that work with
\spadtype{DoubleFloat}.
}{
\spadcommand{avg : List DoubleFloat -> DoubleFloat \bound{avgDec}}
}
\xtc{
}{
\begin{spadsrc}[\bound{avg}\free{avgDec}]
avg l ==
  empty? l => 0 :: DoubleFloat
  reduce(_+,l) / #l
\end{spadsrc}
}
\xtc{
}{
\spadcommand{avg [] \free{avg}}
}
\xtc{
}{
\spadcommand{avg [3.4,9.7,-6.8] \free{avg}}
}
\xtc{
Use package-calling for operations from \spadtype{DoubleFloat} unless
the arguments themselves are already of type \spadtype{DoubleFloat}.
}{
\spadcommand{cos(3.1415926)\$DoubleFloat}
}
\xtc{
}{
\spadcommand{cos(3.1415926 :: DoubleFloat)}
}

By far, the most common usage of \spadtype{DoubleFloat} is for functions
to be graphed.
For more information about \Language{}'s numerical and graphical
facilities, see
\spadref{ugGraph},
\spadref{ugProblemNumeric}, and
\xmpref{Float}.
