3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Using Macros to Change the Policy Defaults</title>
5 <link rel="stylesheet" href="../../math.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
7 <link rel="home" href="../../index.html" title="Math Toolkit 2.11.0">
8 <link rel="up" href="../pol_ref.html" title="Policy Reference">
9 <link rel="prev" href="iteration_pol.html" title="Iteration Limits Policies">
10 <link rel="next" href="namespace_pol.html" title="Setting Polices at Namespace Scope">
12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
13 <table cellpadding="2" width="100%"><tr>
14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
15 <td align="center"><a href="../../../../../../index.html">Home</a></td>
16 <td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
19 <td align="center"><a href="../../../../../../more/index.htm">More</a></td>
22 <div class="spirit-nav">
23 <a accesskey="p" href="iteration_pol.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="namespace_pol.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
26 <div class="titlepage"><div><div><h3 class="title">
27 <a name="math_toolkit.pol_ref.policy_defaults"></a><a class="link" href="policy_defaults.html" title="Using Macros to Change the Policy Defaults">Using Macros to
28 Change the Policy Defaults</a>
29 </h3></div></div></div>
31 You can use the various macros below to change any (or all) of the policies.
34 You can make a local change by placing a macro definition <span class="bold"><strong>before</strong></span>
35 a function or distribution #include.
37 <div class="caution"><table border="0" summary="Caution">
39 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td>
40 <th align="left">Caution</th>
42 <tr><td align="left" valign="top"><p>
43 There is a danger of One-Definition-Rule violations if you add ad-hoc macros
44 to more than one source files: these must be set the same in <span class="bold"><strong>every translation unit</strong></span>.
47 <div class="caution"><table border="0" summary="Caution">
49 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Caution]" src="../../../../../../doc/src/images/caution.png"></td>
50 <th align="left">Caution</th>
52 <tr><td align="left" valign="top"><p>
53 If you place it after the #include it will have no effect, (and it will
54 affect only any other following #includes). This is probably not what you
59 If you want to alter the defaults for any or all of the policies for <span class="bold"><strong>all</strong></span> functions and distributions, installation-wide,
60 then you can do so by defining various macros in <a href="../../../../../../boost/math/tools/user.hpp" target="_top">boost/math/tools/user.hpp</a>.
63 <a name="math_toolkit.pol_ref.policy_defaults.h0"></a>
64 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_domain_error_policy"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_domain_error_policy">BOOST_MATH_DOMAIN_ERROR_POLICY</a>
67 Defines what happens when a domain error occurs, if not defined then defaults
68 to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, but can
69 be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
70 <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
73 <a name="math_toolkit.pol_ref.policy_defaults.h1"></a>
74 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_pole_error_policy"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_pole_error_policy">BOOST_MATH_POLE_ERROR_POLICY</a>
77 Defines what happens when a pole error occurs, if not defined then defaults
78 to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, but can
79 be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
80 <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
83 <a name="math_toolkit.pol_ref.policy_defaults.h2"></a>
84 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_overflow_error_policy"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_overflow_error_policy">BOOST_MATH_OVERFLOW_ERROR_POLICY</a>
87 Defines what happens when an overflow error occurs, if not defined then defaults
88 to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, but can
89 be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
90 <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
93 <a name="math_toolkit.pol_ref.policy_defaults.h3"></a>
94 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_rounding_error_policy"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_rounding_error_policy">BOOST_MATH_ROUNDING_ERROR_POLICY</a>
97 Defines what happens when a rounding error occurs, if not defined then defaults
98 to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, but can
99 be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
100 <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
103 <a name="math_toolkit.pol_ref.policy_defaults.h4"></a>
104 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_evaluation_error_poli"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_evaluation_error_poli">BOOST_MATH_EVALUATION_ERROR_POLICY</a>
107 Defines what happens when an internal evaluation error occurs, if not defined
108 then defaults to <code class="computeroutput"><span class="identifier">throw_on_error</span></code>,
109 but can be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
110 <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
113 <a name="math_toolkit.pol_ref.policy_defaults.h5"></a>
114 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_underflow_error_polic"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_underflow_error_polic">BOOST_MATH_UNDERFLOW_ERROR_POLICY</a>
117 Defines what happens when an overflow error occurs, if not defined then defaults
118 to <code class="computeroutput"><span class="identifier">ignore_error</span></code>, but can
119 be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
120 <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
123 <a name="math_toolkit.pol_ref.policy_defaults.h6"></a>
124 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_denorm_error_policy"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_denorm_error_policy">BOOST_MATH_DENORM_ERROR_POLICY</a>
127 Defines what happens when a denormalisation error occurs, if not defined
128 then defaults to <code class="computeroutput"><span class="identifier">ignore_error</span></code>,
129 but can be set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>, <code class="computeroutput"><span class="identifier">errno_on_error</span></code>,
130 <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
133 <a name="math_toolkit.pol_ref.policy_defaults.h7"></a>
134 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_indeterminate_result_"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_indeterminate_result_">BOOST_MATH_INDETERMINATE_RESULT_ERROR_POLICY</a>
137 Defines what happens when the result is indeterminate, but where there is
138 none the less a convention for the result. If not defined then defaults to
139 <code class="computeroutput"><span class="identifier">ignore_error</span></code>, but can be
140 set to any of the enumerated actions for error handing: <code class="computeroutput"><span class="identifier">throw_on_error</span></code>,
141 <code class="computeroutput"><span class="identifier">errno_on_error</span></code>, <code class="computeroutput"><span class="identifier">ignore_error</span></code> or <code class="computeroutput"><span class="identifier">user_error</span></code>.
144 <a name="math_toolkit.pol_ref.policy_defaults.h8"></a>
145 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_digits10_policy"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_digits10_policy">BOOST_MATH_DIGITS10_POLICY</a>
148 Defines how many decimal digits to use in internal computations: defaults
149 to <code class="computeroutput"><span class="number">0</span></code> - meaning use all available
150 digits - but can be set to some other decimal value. Since setting this is
151 likely to have a substantial impact on accuracy, it's not generally recommended
152 that you change this from the default.
155 <a name="math_toolkit.pol_ref.policy_defaults.h9"></a>
156 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_promote_float_policy"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_promote_float_policy">BOOST_MATH_PROMOTE_FLOAT_POLICY</a>
159 Determines whether <code class="computeroutput"><span class="keyword">float</span></code> types
160 get promoted to <code class="computeroutput"><span class="keyword">double</span></code> internally
161 to ensure maximum precision in the result, defaults to <code class="computeroutput"><span class="keyword">true</span></code>,
162 but can be set to <code class="computeroutput"><span class="keyword">false</span></code> to turn
163 promotion of <code class="computeroutput"><span class="keyword">float</span></code>'s off.
166 <a name="math_toolkit.pol_ref.policy_defaults.h10"></a>
167 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_promote_double_policy"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_promote_double_policy">BOOST_MATH_PROMOTE_DOUBLE_POLICY</a>
170 Determines whether <code class="computeroutput"><span class="keyword">double</span></code> types
171 get promoted to <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code>
172 internally to ensure maximum precision in the result, defaults to <code class="computeroutput"><span class="keyword">true</span></code>, but can be set to <code class="computeroutput"><span class="keyword">false</span></code>
173 to turn promotion of <code class="computeroutput"><span class="keyword">double</span></code>'s
177 <a name="math_toolkit.pol_ref.policy_defaults.h11"></a>
178 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_discrete_quantile_pol"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_discrete_quantile_pol">BOOST_MATH_DISCRETE_QUANTILE_POLICY</a>
181 Determines how discrete quantiles return their results: either as an integer,
182 or as a real value, can be set to one of the enumerated values: <code class="computeroutput"><span class="identifier">real</span></code>, <code class="computeroutput"><span class="identifier">integer_round_outwards</span></code>,
183 <code class="computeroutput"><span class="identifier">integer_round_inwards</span></code>, <code class="computeroutput"><span class="identifier">integer_round_down</span></code>, <code class="computeroutput"><span class="identifier">integer_round_up</span></code>,
184 <code class="computeroutput"><span class="identifier">integer_round_nearest</span></code>. Defaults
185 to <code class="computeroutput"><span class="identifier">integer_round_outwards</span></code>.
188 <a name="math_toolkit.pol_ref.policy_defaults.h12"></a>
189 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_assert_undefined_poli"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_assert_undefined_poli">BOOST_MATH_ASSERT_UNDEFINED_POLICY</a>
192 Determines whether functions that are mathematically undefined for a specific
193 distribution compile or raise a static (i.e. compile-time) assertion. Defaults
194 to <code class="computeroutput"><span class="keyword">true</span></code>: meaning that any mathematically
195 undefined function will not compile. When set to <code class="computeroutput"><span class="keyword">false</span></code>
196 then the function will compile but return the result of a domain error: this
197 can be useful for some generic code, that needs to work with all distributions
198 and determine at runtime whether or not a particular property is well defined.
201 <a name="math_toolkit.pol_ref.policy_defaults.h13"></a>
202 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_max_series_iteration_"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_max_series_iteration_">BOOST_MATH_MAX_SERIES_ITERATION_POLICY</a>
205 Determines how many series iterations a special function is permitted to
206 perform before it gives up and returns an <a class="link" href="../error_handling.html#math_toolkit.error_handling.evaluation_error">evaluation_error</a>:
210 <a name="math_toolkit.pol_ref.policy_defaults.h14"></a>
211 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.boost_math_max_root_iteration_po"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.boost_math_max_root_iteration_po">BOOST_MATH_MAX_ROOT_ITERATION_POLICY</a>
214 Determines how many root-finding iterations a special function is permitted
215 to perform before it gives up and returns an <a class="link" href="../error_handling.html#math_toolkit.error_handling.evaluation_error">evaluation_error</a>:
219 <a name="math_toolkit.pol_ref.policy_defaults.h15"></a>
220 <span class="phrase"><a name="math_toolkit.pol_ref.policy_defaults.example"></a></span><a class="link" href="policy_defaults.html#math_toolkit.pol_ref.policy_defaults.example">Example</a>
223 Suppose we want overflow errors to set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> and return an infinity, discrete
224 quantiles to return a real-valued result (rather than round to integer),
225 and for mathematically undefined functions to compile, but return a domain
226 error. Then we could add the following to boost/math/tools/user.hpp:
228 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
229 <span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DISCRETE_QUANTILE_POLICY</span> <span class="identifier">real</span>
230 <span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span> <span class="keyword">false</span>
233 or we could place these definitions <span class="bold"><strong>before</strong></span>
235 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">distributions</span><span class="special">/</span><span class="identifier">normal</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
236 <span class="keyword">using</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">normal_distribution</span><span class="special">;</span>
239 in a source .cpp file.
242 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
243 <td align="left"></td>
244 <td align="right"><div class="copyright-footer">Copyright © 2006-2019 Nikhar
245 Agrawal, Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos,
246 Hubert Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Matthew Pulver, Johan
247 Råde, Gautam Sewani, Benjamin Sobotta, Nicholas Thompson, Thijs van den Berg,
248 Daryle Walker and Xiaogang Zhang<p>
249 Distributed under the Boost Software License, Version 1.0. (See accompanying
250 file LICENSE_1_0.txt or copy at <a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">http://www.boost.org/LICENSE_1_0.txt</a>)
255 <div class="spirit-nav">
256 <a accesskey="p" href="iteration_pol.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_ref.html"><img src="../../../../../../doc/src/images/up.png" alt="Up"></a><a accesskey="h" href="../../index.html"><img src="../../../../../../doc/src/images/home.png" alt="Home"></a><a accesskey="n" href="namespace_pol.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>