2 [mathpart policy Policies: Controlling Precision, Error Handling etc]
4 [section:pol_overview Policy Overview]
6 [endsect] [/section:pol_overview Policy Overview]
8 [include policy_tutorial.qbk]
10 [section:pol_ref Policy Reference]
12 [section:error_handling_policies Error Handling Policies]
14 There are two orthogonal aspects to error handling:
16 * What to do (if anything) with the error.
17 * What kind of error is being raised.
19 [h4 Available Actions When an Error is Raised]
21 What to do with the error is encapsulated by an enumerated type:
23 namespace boost { namespace math { namespace policies {
25 enum error_policy_type
27 throw_on_error = 0, // throw an exception.
28 errno_on_error = 1, // set ::errno & return 0, NaN, infinity or best guess.
29 ignore_error = 2, // return 0, NaN, infinity or best guess.
30 user_error = 3 // call a user-defined error handler.
35 The various enumerated values have the following meanings:
39 Will throw one of the following exceptions, depending upon the
42 [[Error Type][Exception]]
43 [[Domain Error][std::domain_error]]
44 [[Pole Error][std::domain_error]]
45 [[Overflow Error][std::overflow_error]]
46 [[Underflow Error][std::underflow_error]]
47 [[Denorm Error][std::underflow_error]]
48 [[Evaluation Error][boost::math::evaluation_error]]
49 [[Indeterminate Result Error][std::domain_error]]
54 Will set global __errno `::errno` to one of the following values depending
55 upon the error type (often EDOM = 33 and ERANGE = 34),
56 and then return the same value as if the error
59 [[Error Type][errno value]]
60 [[Domain Error][EDOM]]
62 [[Overflow Error][ERANGE]]
63 [[Underflow Error][ERANGE]]
64 [[Denorm Error][ERANGE]]
65 [[Evaluation Error][EDOM]]
66 [[Indeterminate Result Error][EDOM]]
71 Will return one of the values below depending on the error type (`::errno` is NOT changed)::
73 [[Error Type][Returned Value]]
74 [[Domain Error][std::numeric_limits<T>::quiet_NaN()]]
75 [[Pole Error][std::numeric_limits<T>::quiet_NaN()]]
76 [[Overflow Error][std::numeric_limits<T>::infinity()]]
77 [[Underflow Error][0]]
78 [[Denorm Error][The denormalised value.]]
79 [[Evaluation Error][The best guess (perhaps NaN) as to the result: which
80 may be significantly in error.]]
81 [[Indeterminate Result Error][Depends on the function where the error occurred]]
86 Will call a user defined error handler: these are forward declared
87 in boost/math/policies/error_handling.hpp, but the actual definitions
88 must be provided by the user:
90 namespace boost{ namespace math{ namespace policies{
93 T user_domain_error(const char* function, const char* message, const T& val);
96 T user_pole_error(const char* function, const char* message, const T& val);
99 T user_overflow_error(const char* function, const char* message, const T& val);
102 T user_underflow_error(const char* function, const char* message, const T& val);
105 T user_denorm_error(const char* function, const char* message, const T& val);
108 T user_rounding_error(const char* function, const char* message, const T& val);
111 T user_evaluation_error(const char* function, const char* message, const T& val);
114 T user_indeterminate_result_error(const char* function, const char* message, const T& val);
118 Note that the strings ['function] and ['message] may contain "%1%" format specifiers
119 designed to be used in conjunction with Boost.Format.
120 If these strings are to be presented to the program's end-user then
121 the "%1%" format specifier
122 should be replaced with the name of type T in the ['function] string, and
123 if there is a %1% specifier in the ['message] string then it
124 should be replaced with the value of ['val].
126 There is more information on user-defined error handlers in
127 the [link math_toolkit.pol_tutorial.user_def_err_pol
130 [h4 Kinds of Error Raised]
132 There are six kinds of error reported by this library,
133 which are summarised in the following table:
140 [boost::math::policies::domain_error<['action]>]
141 [Raised when more or more arguments are outside the
142 defined range of the function.
144 Defaults to `boost::math::policies::domain_error<throw_on_error>`
146 When the action is set to ['throw_on_error]
147 then throws `std::domain_error`]]
149 [boost::math::policies::pole_error<['action]>]
150 [Raised when more or more arguments would cause the function
151 to be evaluated at a pole.
153 Defaults to `boost::math::policies::pole_error<throw_on_error>`
155 When the action is ['throw_on_error] then
156 throw a `std::domain_error`]]
158 [boost::math::policies::overflow_error<['action]>]
159 [Raised when the result of the function is outside
160 the representable range of the floating point type used.
162 Defaults to `boost::math::policies::overflow_error<throw_on_error>`.
164 When the action is ['throw_on_error] then throws a `std::overflow_error`.]]
166 [boost::math::policies::underflow_error<['action]>]
167 [Raised when the result of the function is too small
168 to be represented in the floating point type used.
170 Defaults to `boost::math::policies::underflow_error<ignore_error>`
172 When the specified action is ['throw_on_error] then
173 throws a `std::underflow_error`]]
175 [boost::math::policies::denorm_error<['action]>]
176 [Raised when the result of the function is a
179 Defaults to `boost::math::policies::denorm_error<ignore_error>`
181 When the action is ['throw_on_error] then throws a `std::underflow_error`]]
183 [boost::math::policies::rounding_error<['action]>]
184 [Raised When one of the rounding functions __round, __trunc or __modf is
185 called with an argument that has no integer representation, or
186 is too large to be represented in the result type
188 Defaults to `boost::math::policies::rounding_error<throw_on_error>`
190 When the action is ['throw_on_error] then throws `boost::math::rounding_error`]]
192 [boost::math::policies::evaluation_error<['action]>]
193 [Raised when the result of the function is well defined and
194 finite, but we were unable to compute it. Typically
195 this occurs when an iterative method fails to converge.
196 Of course ideally this error should never be raised: feel free
197 to report it as a bug if it is!
199 Defaults to `boost::math::policies::evaluation_error<throw_on_error>`
201 When the action is ['throw_on_error] then throws `boost::math::evaluation_error`]]
202 [[Indeterminate Result Error]
203 [boost::math::policies::indeterminate_result_error<['action]>]
204 [Raised when the result of a function is not defined for the values that
207 Defaults to `boost::math::policies::indeterminate_result_error<ignore_error>`
209 When the action is ['throw_on_error] then throws `std::domain_error`]]
214 Suppose we want a call to `tgamma` to behave in a C-compatible way and set global
215 `::errno` rather than throw an exception, we can achieve this at the call site
218 [import ../../example/policy_ref_snip1.cpp]
222 Suppose we want a statistical distribution to return infinities,
223 rather than throw exceptions, then we can use:
225 [import ../../example/policy_ref_snip2.cpp]
229 [endsect] [/section:error_handling_policies Error Handling Policies]
231 [section:internal_promotion Internal Floating-point Promotion Policies]
233 Normally when evaluating a function at say `float` precision, maximal
234 accuracy is assured by conducting the calculation at `double` precision
235 internally, and then rounding the result. There are two policies that
236 control whether internal promotion to a higher precision floating-point type takes place, or not:
240 [[`boost::math::policies::promote_float<B>`]
241 [Indicates whether `float` arguments should be promoted to `double`
242 precision internally: defaults to `boost::math::policies::promote_float<true>`]]
243 [[`boost::math::policies::promote_double<B>`]
244 [Indicates whether `double` arguments should be promoted to `long double`
245 precision internally: defaults to `boost::math::policies::promote_double<true>`]]
250 Suppose we want `tgamma` to be evaluated without internal promotion to
251 `long double`, then we could use:
253 [import ../../example/policy_ref_snip3.cpp]
256 Alternatively, suppose we want a distribution to perform calculations
257 without promoting `float` to `double`, then we could use:
259 [import ../../example/policy_ref_snip4.cpp]
262 [endsect] [/section:internal_promotion Internal Promotion Policies]
264 [section:assert_undefined Mathematically Undefined Function Policies]
266 There are some functions that are generic
267 (they are present for all the statistical distributions supported)
268 but which may be mathematically undefined for certain distributions, but defined for others.
270 For example, the Cauchy distribution does not have a meaningful mean,
275 return, and should such an expression even compile at all?
277 The default behaviour is for all such functions to not compile at all
278 - in fact they will raise a
279 [@http://www.boost.org/libs/static_assert/index.html static assertion]
280 - but by changing the policy
281 we can have them return the result of a domain error instead
282 (which may well throw an exception, depending on the error handling policy).
284 This behaviour is controlled by the `assert_undefined<>` policy:
286 namespace boost{ namespace math{ namespace policies {
289 class assert_undefined;
295 #include <boost/math/distributions/cauchy.hpp>
297 using namespace boost::math::policies;
298 using namespace boost::math;
300 // This will not compile, cauchy has no mean!
301 double m1 = mean(cauchy());
303 // This will compile, but raises a domain error!
304 double m2 = mean(cauchy_distribution<double, policy<assert_undefined<false> > >());
306 `policy<assert_undefined<false>` behaviour can also be obtained by defining the macro
308 #define BOOST_MATH_ASSERT_UNDEFINED_POLICY false
310 at the head of the file - see __policy_macros.
312 [endsect][/section:assert_undefined Mathematically Undefined Function Policies]
314 [section:discrete_quant_ref Discrete Quantile Policies]
316 If a statistical distribution is ['discrete] then the random variable
317 can only have integer values - this leaves us with a problem when calculating
318 quantiles - we can either ignore the discreteness of the distribution and return
319 a real value, or we can round to an integer. As it happens, computing integer
320 values can be substantially faster than calculating a real value, so there are
321 definite advantages to returning an integer, but we do then need to decide
322 how best to round the result. The `discrete_quantile` policy defines how
323 discrete quantiles work, and how integer results are rounded:
325 enum discrete_quantile_policy_type
328 integer_round_outwards, // default
329 integer_round_inwards,
332 integer_round_nearest
335 template <discrete_quantile_policy_type>
336 struct discrete_quantile;
338 The values that `discrete_quantile` can take have the following meanings:
342 Ignores the discreteness of the distribution, and returns a real-valued
345 [import ../../example/policy_ref_snip5.cpp]
348 Results in `x = 27.3898` and `y = 68.1584`.
350 [h5 integer_round_outwards]
352 This is the default policy: an integer value is returned so that:
354 * Lower quantiles (where the probability is less than 0.5) are rounded
356 * Upper quantiles (where the probability is greater than 0.5) are rounded up.
358 This is normally the safest rounding policy, since it ensures that both
359 one and two sided intervals are guaranteed to have ['at least]
360 the requested coverage. For example:
362 [import ../../example/policy_ref_snip6.cpp]
365 Results in `x = 27` (rounded down from 27.3898) and `y = 69` (rounded up from 68.1584).
367 The variables x and y are now defined so that:
369 cdf(negative_binomial(20), x) <= 0.05
370 cdf(negative_binomial(20), y) >= 0.95
372 In other words we guarantee ['at least 90% coverage in the central region overall],
373 and also ['no more than 5% coverage in each tail].
375 [h5 integer_round_inwards]
377 This is the opposite of ['integer_round_outwards]: an integer value is returned so that:
379 * Lower quantiles (where the probability is less than 0.5) are rounded
381 * Upper quantiles (where the probability is greater than 0.5) are rounded ['down].
385 [import ../../example/policy_ref_snip7.cpp]
389 Results in `x = 28` (rounded up from 27.3898) and `y = 68` (rounded down from 68.1584).
391 The variables x and y are now defined so that:
393 cdf(negative_binomial(20), x) >= 0.05
394 cdf(negative_binomial(20), y) <= 0.95
396 In other words we guarantee ['at no more than 90% coverage in the central region overall],
397 and also ['at least 5% coverage in each tail].
399 [h5 integer_round_down]
401 Always rounds down to an integer value, no matter whether it's an upper
404 [h5 integer_round_up]
406 Always rounds up to an integer value, no matter whether it's an upper
409 [h5 integer_round_nearest]
411 Always rounds to the nearest integer value, no matter whether it's an upper
412 or a lower quantile. This will produce the requested coverage
413 ['in the average case], but for any specific example may results in
414 either significantly more or less coverage than the requested amount.
419 [import ../../example/policy_ref_snip8.cpp]
423 Results in `x = 27` (rounded from 27.3898) and `y = 68` (rounded from 68.1584).
425 [endsect][/section:discrete_quant_ref Discrete Quantile Policies]
427 [section:precision_pol Precision Policies]
429 There are two equivalent policies that effect the ['working precision]
430 used to calculate results, these policies both default to 0 - meaning
431 calculate to the maximum precision available in the type being used
432 - but can be set to other values to cause lower levels of precision
433 to be used. One might want to trade precision for evaluation speed.
435 namespace boost{ namespace math{ namespace policies{
445 As you would expect, ['digits10] specifies the number of decimal digits
446 to use, and ['digits2] the number of binary digits. Internally, whichever
447 is used, the precision is always converted to ['binary digits].
449 These policies are specified at compile-time, because many of the special
450 functions use compile-time-dispatch to select which approximation to use
451 based on the precision requested and the numeric type being used.
453 For example we could calculate `tgamma` to approximately 5 decimal digits using:
455 [import ../../example/policy_ref_snip9.cpp]
459 Or again using helper function `make_policy`:
461 [import ../../example/policy_ref_snip10.cpp]
465 And for a quantile of a distribution to approximately 25-bit precision:
467 [import ../../example/policy_ref_snip11.cpp]
471 [endsect][/section:precision_pol Precision Policies]
473 [section:iteration_pol Iteration Limits Policies]
475 There are two policies that effect the iterative algorithms
476 used to implement the special functions in this library:
478 template <unsigned long limit = BOOST_MATH_MAX_SERIES_ITERATION_POLICY>
479 class max_series_iterations;
481 template <unsigned long limit = BOOST_MATH_MAX_ROOT_ITERATION_POLICY>
482 class max_root_iterations;
484 The class `max_series_iterations` determines the maximum number of
485 iterations permitted in a series evaluation, before the special
486 function gives up and returns the result of __evaluation_error.
488 The class `max_root_iterations` determines the maximum number
489 of iterations permitted in a root-finding algorithm before the special
490 function gives up and returns the result of __evaluation_error.
492 [endsect] [/section:iteration_pol Iteration Limits Policies]
494 [section:policy_defaults Using Macros to Change the Policy Defaults]
496 You can use the various macros below to change any (or all) of the policies.
498 You can make a local change by placing a macro definition *before*
499 a function or distribution #include.
501 [caution There is a danger of One-Definition-Rule violations if you
502 add ad-hoc macros to more than one source files: these must be set the same in *every
505 [caution If you place it after the #include it will have no effect,
506 (and it will affect only any other following #includes).
507 This is probably not what you intend!]
509 If you want to alter the defaults for any or all of
510 the policies for *all* functions and distributions, installation-wide,
511 then you can do so by defining various macros in
512 [@../../../../boost/math/tools/user.hpp boost/math/tools/user.hpp].
514 [h5 BOOST_MATH_DOMAIN_ERROR_POLICY]
516 Defines what happens when a domain error occurs, if not defined then
517 defaults to `throw_on_error`, but can be set to any of the enumerated
518 actions for error handing: `throw_on_error`, `errno_on_error`,
519 `ignore_error` or `user_error`.
521 [h5 BOOST_MATH_POLE_ERROR_POLICY]
523 Defines what happens when a pole error occurs, if not defined then
524 defaults to `throw_on_error`, but can be set to any of the enumerated
525 actions for error handing: `throw_on_error`, `errno_on_error`,
526 `ignore_error` or `user_error`.
528 [h5 BOOST_MATH_OVERFLOW_ERROR_POLICY]
530 Defines what happens when an overflow error occurs, if not defined then
531 defaults to `throw_on_error`, but can be set to any of the enumerated
532 actions for error handing: `throw_on_error`, `errno_on_error`,
533 `ignore_error` or `user_error`.
535 [h5 BOOST_MATH_ROUNDING_ERROR_POLICY]
537 Defines what happens when a rounding error occurs, if not defined then
538 defaults to `throw_on_error`, but can be set to any of the enumerated
539 actions for error handing: `throw_on_error`, `errno_on_error`,
540 `ignore_error` or `user_error`.
542 [h5 BOOST_MATH_EVALUATION_ERROR_POLICY]
544 Defines what happens when an internal evaluation error occurs, if not defined then
545 defaults to `throw_on_error`, but can be set to any of the enumerated
546 actions for error handing: `throw_on_error`, `errno_on_error`,
547 `ignore_error` or `user_error`.
549 [h5 BOOST_MATH_UNDERFLOW_ERROR_POLICY]
551 Defines what happens when an overflow error occurs, if not defined then
552 defaults to `ignore_error`, but can be set to any of the enumerated
553 actions for error handing: `throw_on_error`, `errno_on_error`,
554 `ignore_error` or `user_error`.
556 [h5 BOOST_MATH_DENORM_ERROR_POLICY]
558 Defines what happens when a denormalisation error occurs, if not defined then
559 defaults to `ignore_error`, but can be set to any of the enumerated
560 actions for error handing: `throw_on_error`, `errno_on_error`,
561 `ignore_error` or `user_error`.
563 [h5 BOOST_MATH_INDETERMINATE_RESULT_ERROR_POLICY]
565 Defines what happens when the result is indeterminate, but where there
566 is none the less a convention for the result. If not defined then
567 defaults to `ignore_error`, but can be set to any of the enumerated
568 actions for error handing: `throw_on_error`, `errno_on_error`,
569 `ignore_error` or `user_error`.
571 [h5 BOOST_MATH_DIGITS10_POLICY]
573 Defines how many decimal digits to use in internal computations:
574 defaults to `0` - meaning use all available digits - but can be set
575 to some other decimal value. Since setting this is likely to have
576 a substantial impact on accuracy, it's not generally recommended
577 that you change this from the default.
579 [h5 BOOST_MATH_PROMOTE_FLOAT_POLICY]
581 Determines whether `float` types get promoted to `double`
582 internally to ensure maximum precision in the result, defaults
583 to `true`, but can be set to `false` to turn promotion of
586 [h5 BOOST_MATH_PROMOTE_DOUBLE_POLICY]
588 Determines whether `double` types get promoted to `long double`
589 internally to ensure maximum precision in the result, defaults
590 to `true`, but can be set to `false` to turn promotion of
593 [h5 BOOST_MATH_DISCRETE_QUANTILE_POLICY]
595 Determines how discrete quantiles return their results: either
596 as an integer, or as a real value, can be set to one of the
597 enumerated values: `real`, `integer_round_outwards`, `integer_round_inwards`,
598 `integer_round_down`, `integer_round_up`, `integer_round_nearest`. Defaults to
599 `integer_round_outwards`.
601 [h5 BOOST_MATH_ASSERT_UNDEFINED_POLICY]
603 Determines whether functions that are mathematically undefined
604 for a specific distribution compile or raise a static (i.e. compile-time)
605 assertion. Defaults to `true`: meaning that any mathematically
606 undefined function will not compile. When set to `false` then the function
607 will compile but return the result of a domain error: this can be useful
608 for some generic code, that needs to work with all distributions and determine
609 at runtime whether or not a particular property is well defined.
611 [h5 BOOST_MATH_MAX_SERIES_ITERATION_POLICY]
613 Determines how many series iterations a special function is permitted
614 to perform before it gives up and returns an __evaluation_error:
617 [h5 BOOST_MATH_MAX_ROOT_ITERATION_POLICY]
619 Determines how many root-finding iterations a special function is permitted
620 to perform before it gives up and returns an __evaluation_error:
625 Suppose we want overflow errors to set `::errno` and return an infinity,
626 discrete quantiles to return a real-valued result (rather than round to
627 integer), and for mathematically undefined functions to compile, but return
628 a domain error. Then we could add the following to boost/math/tools/user.hpp:
630 #define BOOST_MATH_OVERFLOW_ERROR_POLICY errno_on_error
631 #define BOOST_MATH_DISCRETE_QUANTILE_POLICY real
632 #define BOOST_MATH_ASSERT_UNDEFINED_POLICY false
634 or we could place these definitions *before*
636 #include <boost/math/distributions/normal.hpp>
637 using boost::math::normal_distribution;
639 in a source .cpp file.
641 [endsect][/section:policy_defaults Changing the Policy Defaults]
643 [section:namespace_pol Setting Polices at Namespace Scope]
645 Sometimes what you really want to do is bring all the special functions,
646 or all the distributions into a specific namespace-scope, along with
647 a specific policy to use with them. There are two macros defined to
650 BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(Policy)
654 BOOST_MATH_DECLARE_DISTRIBUTIONS(Type, Policy)
656 You can use either of these macros after including any special function
657 or distribution header. For example:
659 [import ../../example/policy_ref_snip12.cpp]
663 In this example, using BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS results in
664 a set of thin inline forwarding functions being defined:
667 inline T tgamma(T a){ return ::boost::math::tgamma(a, mypolicy()); }
670 inline T lgamma(T a) ( return ::boost::math::lgamma(a, mypolicy()); }
672 and so on. Note that while a forwarding function is defined for all the special
673 functions, however, unless you include the specific header for the special
674 function you use (or boost/math/special_functions.hpp to include everything),
675 you will get linker errors from functions that are forward declared, but not
678 We can do the same thing with the distributions, but this time we need to
679 specify the floating-point type to use:
681 [import ../../example/policy_ref_snip13.cpp]
685 In this example the result of BOOST_MATH_DECLARE_DISTRIBUTIONS is to
686 declare a typedef for each distribution like this:
688 typedef boost::math::cauchy_distribution<double, my_policy> cauchy;
689 tyepdef boost::math::gamma_distribution<double, my_policy> gamma;
691 and so on. The name given to each typedef is the name of the distribution
692 with the "_distribution" suffix removed.
694 [endsect][/section Changing the Policy Defaults]
696 [section:pol_ref_ref Policy Class Reference]
698 There's very little to say here, the `policy` class is just a rag-bag
699 compile-time container for a collection of policies:
701 ```#include <boost/math/policies/policy.hpp>```
708 template <class A1 = default_policy,
709 class A2 = default_policy,
710 class A3 = default_policy,
711 class A4 = default_policy,
712 class A5 = default_policy,
713 class A6 = default_policy,
714 class A7 = default_policy,
715 class A8 = default_policy,
716 class A9 = default_policy,
717 class A10 = default_policy,
718 class A11 = default_policy,
719 class A12 = default_policy,
720 class A13 = default_policy>
724 typedef ``['computed-from-template-arguments]`` domain_error_type;
725 typedef ``['computed-from-template-arguments]`` pole_error_type;
726 typedef ``['computed-from-template-arguments]`` overflow_error_type;
727 typedef ``['computed-from-template-arguments]`` underflow_error_type;
728 typedef ``['computed-from-template-arguments]`` denorm_error_type;
729 typedef ``['computed-from-template-arguments]`` rounding_error_type;
730 typedef ``['computed-from-template-arguments]`` evaluation_error_type;
731 typedef ``['computed-from-template-arguments]`` indeterminate_result_error_type;
732 typedef ``['computed-from-template-arguments]`` precision_type;
733 typedef ``['computed-from-template-arguments]`` promote_float_type;
734 typedef ``['computed-from-template-arguments]`` promote_double_type;
735 typedef ``['computed-from-template-arguments]`` discrete_quantile_type;
736 typedef ``['computed-from-template-arguments]`` assert_undefined_type;
739 template <...argument list...>
740 typename normalise<policy<>, A1>::type make_policy(...argument list..);
742 template <class Policy,
743 class A1 = default_policy,
744 class A2 = default_policy,
745 class A3 = default_policy,
746 class A4 = default_policy,
747 class A5 = default_policy,
748 class A6 = default_policy,
749 class A7 = default_policy,
750 class A8 = default_policy,
751 class A9 = default_policy,
752 class A10 = default_policy,
753 class A11 = default_policy,
754 class A12 = default_policy,
755 class A13 = default_policy>
758 typedef ``computed-from-template-arguments`` type;
761 The member typedefs of class `policy` are intended for internal use
762 but are documented briefly here for the sake of completeness.
764 policy<...>::domain_error_type
766 Specifies how domain errors are handled, will be an instance of
767 `boost::math::policies::domain_error<>` with the template argument to
768 `domain_error` one of the `error_policy_type` enumerated values.
770 policy<...>::pole_error_type
772 Specifies how pole-errors are handled, will be an instance of
773 `boost::math::policies::pole_error<>` with the template argument to
774 `pole_error` one of the `error_policy_type` enumerated values.
776 policy<...>::overflow_error_type
778 Specifies how overflow errors are handled, will be an instance of
779 `boost::math::policies::overflow_error<>` with the template argument to
780 `overflow_error` one of the `error_policy_type` enumerated values.
782 policy<...>::underflow_error_type
784 Specifies how underflow errors are handled, will be an instance of
785 `boost::math::policies::underflow_error<>` with the template argument to
786 `underflow_error` one of the `error_policy_type` enumerated values.
788 policy<...>::denorm_error_type
790 Specifies how denorm errors are handled, will be an instance of
791 `boost::math::policies::denorm_error<>` with the template argument to
792 `denorm_error` one of the `error_policy_type` enumerated values.
794 policy<...>::rounding_error_type
796 Specifies how rounding errors are handled, will be an instance of
797 `boost::math::policies::rounding_error<>` with the template argument to
798 `rounding_error` one of the `error_policy_type` enumerated values.
800 policy<...>::evaluation_error_type
802 Specifies how evaluation errors are handled, will be an instance of
803 `boost::math::policies::evaluation_error<>` with the template argument to
804 `evaluation_error` one of the `error_policy_type` enumerated values.
806 policy<...>::indeterminate_error_type
808 Specifies how indeterminate result errors are handled, will be an instance of
809 `boost::math::policies::indeterminate_result_error<>` with the template argument
810 to `indeterminate_result_error` one of the `error_policy_type` enumerated
813 policy<...>::precision_type
815 Specifies the internal precision to use in binary digits (uses zero
816 to represent whatever the default precision is). Will be an instance
817 of `boost::math::policies::digits2<N>` which in turn inherits from
818 `boost::mpl::int_<N>`.
820 policy<...>::promote_float_type
822 Specifies whether or not to promote `float` arguments to `double` precision
823 internally. Will be an instance of `boost::math::policies::promote_float<B>`
824 which in turn inherits from `boost::mpl::bool_<B>`.
826 policy<...>::promote_double_type
828 Specifies whether or not to promote `double` arguments to `long double` precision
829 internally. Will be an instance of `boost::math::policies::promote_float<B>`
830 which in turn inherits from `boost::mpl::bool_<B>`.
832 policy<...>::discrete_quantile_type
834 Specifies how discrete quantiles are evaluated, will be an instance
835 of `boost::math::policies::discrete_quantile<>` instantiated with one of
836 the `discrete_quantile_policy_type` enumerated type.
838 policy<...>::assert_undefined_type
840 Specifies whether mathematically-undefined properties are
841 asserted as compile-time errors, or treated as runtime errors
842 instead. Will be an instance of `boost::math::policies::assert_undefined<B>`
843 which in turn inherits from `boost::math::mpl::bool_<B>`.
846 template <...argument list...>
847 typename normalise<policy<>, A1>::type make_policy(...argument list..);
849 `make_policy` is a helper function that converts a list of policies into
850 a normalised `policy` class.
852 template <class Policy,
853 class A1 = default_policy,
854 class A2 = default_policy,
855 class A3 = default_policy,
856 class A4 = default_policy,
857 class A5 = default_policy,
858 class A6 = default_policy,
859 class A7 = default_policy,
860 class A8 = default_policy,
861 class A9 = default_policy,
862 class A10 = default_policy,
863 class A11 = default_policy,
864 class A12 = default_policy,
865 class A13 = default_policy>
868 typedef ``computed-from-template-arguments`` type;
871 The `normalise` class template converts one instantiation of the
872 `policy` class into a normalised form. This is used internally
873 to reduce code bloat: so that instantiating a special function
874 on `policy<A,B>` or `policy<B,A>` actually both generate the same
877 Further more, `normalise` can be used to combine
878 a policy with one or more policies: for example many of the
879 special functions will use this to set policies which they don't
880 make use of to their default values, before forwarding to the actual
881 implementation. In this way code bloat is reduced, since the
882 actual implementation depends only on the policy types that they
885 [endsect][/section:pol_ref_ref Policy Class Reference]
887 [endsect][/section:pol_ref Policy Reference]
888 [endmathpart][/section:policy Policies]
891 Copyright 2007, 2010 John Maddock and Paul A. Bristow.
892 Distributed under the Boost Software License, Version 1.0.
893 (See accompanying file LICENSE_1_0.txt or copy at
894 http://www.boost.org/LICENSE_1_0.txt).