The functions, and statistical distributions in this library can be used
with any type RealType that meets the conceptual requirements
given below. All the built in floating point types will meet these requirements.
User defined types that meet the requirements can also be used. For example,
with a thin wrapper class
one of the types provided with NTL (RR)
can be used. Submissions of binding to other extended precision types would
also be most welcome!

The guiding principal behind these requirements, is that a RealType
behaves just like a built in floating point type.

These requirements are common to all of the functions in this library.

In the following table r is an object of type RealType, cr and
cr2 are objects of type constRealType, and ca
is an object of type constarithmetic-type (arithmetic types include all the
built in integers and floating point types).

Expression

Result Type

Notes

RealType(cr)

RealType

RealType is copy constructible.

RealType(ca)

RealType

RealType is copy constructible from the arithmetic types.

r=cr

RealType&

Assignment operator.

r=ca

RealType&

Assignment operator from the arithmetic types.

r+=cr

RealType&

Adds cr to r.

r+=ca

RealType&

Adds ar to r.

r-=cr

RealType&

Subtracts cr from r.

r-=ca

RealType&

Subtracts ca from r.

r*=cr

RealType&

Multiplies r by cr.

r*=ca

RealType&

Multiplies r by ca.

r/=cr

RealType&

Divides r by cr.

r/=ca

RealType&

Divides r by ca.

-r

RealType

Unary Negation.

+r

RealType&

Identity Operation.

cr+cr2

RealType

Binary Addition

cr+ca

RealType

Binary Addition

ca+cr

RealType

Binary Addition

cr-cr2

RealType

Binary Subtraction

cr-ca

RealType

Binary Subtraction

ca-cr

RealType

Binary Subtraction

cr*cr2

RealType

Binary Multiplication

cr*ca

RealType

Binary Multiplication

ca*cr

RealType

Binary Multiplication

cr/cr2

RealType

Binary Subtraction

cr/ca

RealType

Binary Subtraction

ca/cr

RealType

Binary Subtraction

cr==cr2

bool

Equality Comparison

cr==ca

bool

Equality Comparison

ca==cr

bool

Equality Comparison

cr!=cr2

bool

Inequality Comparison

cr!=ca

bool

Inequality Comparison

ca!=cr

bool

Inequality Comparison

cr<=cr2

bool

Less than equal to.

cr<=ca

bool

Less than equal to.

ca<=cr

bool

Less than equal to.

cr>=cr2

bool

Greater than equal to.

cr>=ca

bool

Greater than equal to.

ca>=cr

bool

Greater than equal to.

cr<cr2

bool

Less than comparison.

cr<ca

bool

Less than comparison.

ca<cr

bool

Less than comparison.

cr>cr2

bool

Greater than comparison.

cr>ca

bool

Greater than comparison.

ca>cr

bool

Greater than comparison.

boost::math::tools::digits<RealType>()

int

The number of digits in the significand of RealType.

boost::math::tools::max_value<RealType>()

RealType

The largest representable number by type RealType.

boost::math::tools::min_value<RealType>()

RealType

The smallest representable number by type RealType.

boost::math::tools::log_max_value<RealType>()

RealType

The natural logarithm of the largest representable number by type
RealType.

boost::math::tools::log_min_value<RealType>()

RealType

The natural logarithm of the smallest representable number by type
RealType.

boost::math::tools::epsilon<RealType>()

RealType

The machine epsilon of RealType.

Note that:

The functions log_max_value
and log_min_value can
be synthesised from the others, and so no explicit specialisation is
required.

The function epsilon
can be synthesised from the others, so no explicit specialisation is
required provided the precision of RealType does not vary at runtime
(see the header boost/math/bindings/rr.hpp
for an example where the precision does vary at runtime).

The functions digits,
max_value and min_value, all get synthesised automatically
from std::numeric_limits. However, if numeric_limits is not specialised for
type RealType, then you will get a compiler error when code tries to
use these functions, unless you explicitly specialise
them. For example if the precision of RealType varies at runtime, then
numeric_limits support
may not be appropriate, see boost/math/bindings/rr.hpp
for examples.

Warning

If std::numeric_limits<>
is not specialized for type RealType
then the default float precision of 6 decimal digits will be used by other
Boost programs including:

Boost.Test: giving misleading error messages like

"difference between {9.79796} and {9.79796} exceeds 5.42101e-19%".

Boost.LexicalCast and Boost.Serialization when converting the number to
a string, causing potentially serious loss of accuracy on output.

Although it might seem obvious that RealType should require std::numeric_limits to be specialized, this
is not sensible for NTL::RR
and similar classes where the number of digits is a runtime parameter (where
as for numeric_limits it
has to be fixed at compile time).

Many (though not all) of the functions in this library make calls to standard
library functions, the following table summarises the requirements. Note
that most of the functions in this library will only call a small subset
of the functions listed here, so if in doubt whether a user defined type
has enough standard library support to be useable the best advise is to try
it and see!

In the following table r is an object of type RealType, cr1 and
cr2 are objects of type constRealType, and i
is an object of type int.

Expression

Result Type

fabs(cr1)

RealType

abs(cr1)

RealType

ceil(cr1)

RealType

floor(cr1)

RealType

exp(cr1)

RealType

pow(cr1,cr2)

RealType

sqrt(cr1)

RealType

log(cr1)

RealType

frexp(cr1,&i)

RealType

ldexp(cr1,i)

RealType

cos(cr1)

RealType

sin(cr1)

RealType

asin(cr1)

RealType

tan(cr1)

RealType

atan(cr1)

RealType

fmod(cr1)

RealType

round(cr1)

RealType

iround(cr1)

int

trunc(cr1)

RealType

itrunc(cr1)

int

Note that the table above lists only those standard library functions known
to be used (or likely to be used in the near future) by this library. The
following functions: acos,
atan2, fmod,
cosh, sinh,
tanh, log10,
lround, llround,
ltrunc, lltrunc
and modf are not currently
used, but may be if further special functions are added.

Note that the round, trunc and modf
functions are not part of the current C++ standard: they are part of the
additions added to C99 which will likely be in the next C++ standard. There
are Boost versions of these provided as a backup, and the functions are always
called unqualified so that argument-dependent-lookup can take place.

In addition, for efficient and accurate results, a Lanczos
approximation is highly desirable. You may be able to adapt an existing
approximation from boost/math/special_functions/lanczos.hpp
or boost/math/bindings/detail/big_lanczos.hpp:
in the former case you will need change static_cast's to lexical_cast's,
and the constants to strings (in order to ensure the
coefficients aren't truncated to long double) and then specialise lanczos_traits for type T. Otherwise you
may have to hack libs/math/tools/lanczos_generator.cpp
to find a suitable approximation for your RealType. The code will still compile
if you don't do this, but both accuracy and efficiency will be greatly compromised
in any function that makes use of the gamma/beta/erf family of functions.