...one of the most highly
regarded and expertly designed C++ library projects in the
world.
— Herb Sutter and Andrei
Alexandrescu, C++
Coding Standards
The functions and statistical distributions in this library can be used with
any type RealType that meets the conceptual requirements
given below. All the builtin floatingpoint types like double
will meet these requirements. (Builtin types are also called fundamental
(builtin) types).
Userdefined types that meet the conceptual requirements can also be used. For example, with a thin wrapper class one of the types provided with NTL (RR) can be used. But now that Boost.Multiprecision library is available, this has become the preferred realnumber type, typically cpp_dec_float or cpp_bin_float.
Submissions of binding to other extended precision types would also still be welcome.
The guiding principal behind these requirements is that a RealType behaves just like a builtin floatingpoint 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 const RealType
,
and ca is an object of type const
arithmetictype
(arithmetic types include all the built
in integers and floating point types).
Expression 
Result Type 
Notes 


RealType 
RealType is copy constructible. 

RealType 
RealType is copy constructible from the arithmetic types. 

RealType& 
Assignment operator. 

RealType& 
Assignment operator from the arithmetic types. 

RealType& 
Adds cr to r. 

RealType& 
Adds ar to r. 

RealType& 
Subtracts cr from r. 

RealType& 
Subtracts ca from r. 

RealType& 
Multiplies r by cr. 

RealType& 
Multiplies r by ca. 

RealType& 
Divides r by cr. 

RealType& 
Divides r by ca. 

RealType 
Unary Negation. 

RealType& 
Identity Operation. 

RealType 
Binary Addition 

RealType 
Binary Addition 

RealType 
Binary Addition 

RealType 
Binary Subtraction 

RealType 
Binary Subtraction 

RealType 
Binary Subtraction 

RealType 
Binary Multiplication 

RealType 
Binary Multiplication 

RealType 
Binary Multiplication 

RealType 
Binary Subtraction 

RealType 
Binary Subtraction 

RealType 
Binary Subtraction 

bool 
Equality Comparison 

bool 
Equality Comparison 

bool 
Equality Comparison 

bool 
Inequality Comparison 

bool 
Inequality Comparison 

bool 
Inequality Comparison 

bool 
Less than equal to. 

bool 
Less than equal to. 

bool 
Less than equal to. 

bool 
Greater than equal to. 

bool 
Greater than equal to. 

bool 
Greater than equal to. 

bool 
Less than comparison. 

bool 
Less than comparison. 

bool 
Less than comparison. 

bool 
Greater than comparison. 

bool 
Greater than comparison. 

bool 
Greater than comparison. 

int 
The number of digits in the significand of RealType. 

RealType 
The largest representable number by type RealType. 

RealType 
The smallest representable number by type RealType. 

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

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

RealType 
The machine epsilon of RealType. 
Note that:
log_max_value
and log_min_value
can be
synthesised from the others, and so no explicit specialisation is required.
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).
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 Boost.Test: giving misleading error messages like "difference between {9.79796} and {9.79796} exceeds 5.42101e19%". 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 
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 userdefined 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 const RealType
,
and i is an object of type int
.
Expression 
Result Type 


RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

RealType 

int 

RealType 

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 argumentdependentlookup 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 somewhat compromised
in any function that makes use of the gamma/beta/erf family of functions.