3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4 <title>Changing the Policy Defaults</title>
5 <link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css">
6 <meta name="generator" content="DocBook XSL Stylesheets V1.76.1">
7 <link rel="home" href="../../../index.html" title="Math Toolkit">
8 <link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
9 <link rel="prev" href="policy_usage.html" title="So How are Policies Used Anyway?">
10 <link rel="next" href="ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">
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="policy_usage.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.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="ad_hoc_dist_policies.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>
25 <div class="section math_toolkit_policy_pol_tutorial_changing_policy_defaults">
26 <div class="titlepage"><div><div><h4 class="title">
27 <a name="math_toolkit.policy.pol_tutorial.changing_policy_defaults"></a><a class="link" href="changing_policy_defaults.html" title="Changing the Policy Defaults">Changing
28 the Policy Defaults</a>
29 </h4></div></div></div>
31 The default policies used by the library are changed by the usual configuration
35 For example, passing <code class="computeroutput"><span class="special">-</span><span class="identifier">DBOOST_MATH_DOMAIN_ERROR_POLICY</span><span class="special">=</span><span class="identifier">errno_on_error</span></code>
36 to your compiler will cause domain errors to set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> and return a <a href="http://en.wikipedia.org/wiki/NaN" target="_top">NaN</a>
37 rather than the usual default behaviour of throwing a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code>
40 <div class="tip"><table border="0" summary="Tip">
42 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../../../doc/src/images/tip.png"></td>
43 <th align="left">Tip</th>
45 <tr><td align="left" valign="top">
47 For Microsoft Visual Studio,you can add to the Project Property Page,
48 C/C++, Preprocessor, Preprocessor definitions like:
52 <pre class="programlisting"><span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span><span class="special">=</span><span class="number">0</span>
53 <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span><span class="special">=</span><span class="identifier">errno_on_error</span></pre>
57 This may be helpful to avoid complications with pre-compiled headers
58 that may mean that the equivalent definitions in source code:
62 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span> <span class="keyword">false</span>
63 <span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">errno_on_error</span></pre>
67 <span class="bold"><strong>may be ignored</strong></span>.
70 The compiler command line shows:
74 <pre class="programlisting"><span class="special">/</span><span class="identifier">D</span> <span class="string">"BOOST_MATH_ASSERT_UNDEFINED_POLICY=0"</span>
75 <span class="special">/</span><span class="identifier">D</span> <span class="string">"BOOST_MATH_OVERFLOW_ERROR_POLICY=errno_on_error"</span></pre>
81 There is however a very important caveat to this:
83 <div class="important"><table border="0" summary="Important">
85 <td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../../../doc/src/images/important.png"></td>
86 <th align="left">Important</th>
88 <tr><td align="left" valign="top">
90 <span class="bold"><strong><span class="emphasis"><em>Default policies changed by setting configuration
91 macros must be changed uniformly in every translation unit in the program.</em></span></strong></span>
94 Failure to follow this rule may result in violations of the "One
95 Definition Rule (ODR)" and result in unpredictable program behaviour.
100 That means there are only two safe ways to use these macros:
102 <div class="itemizedlist"><ul class="itemizedlist" type="disc">
103 <li class="listitem">
104 Edit them in <a href="../../../../../../../../boost/math/tools/user.hpp" target="_top">boost/math/tools/user.hpp</a>,
105 so that the defaults are set on an installation-wide basis. Unfortunately
106 this may not be convenient if you are using a pre-installed Boost distribution
107 (on Linux for example).
109 <li class="listitem">
110 Set the defines in your project's Makefile or build environment, so
111 that they are set uniformly across all translation units.
115 What you should <span class="bold"><strong>not</strong></span> do is:
117 <div class="itemizedlist"><ul class="itemizedlist" type="disc"><li class="listitem">
118 Set the defines in the source file using <code class="computeroutput"><span class="preprocessor">#define</span></code>
119 as doing so almost certainly will break your program, unless you're
120 absolutely certain that the program is restricted to a single translation
124 And, yes, you will find examples in our test programs where we break this
125 rule: but only because we know there will always be a single translation
126 unit only: <span class="emphasis"><em>don't say that you weren't warned!</em></span>
129 The following example demonstrates the effect of setting the macro BOOST_MATH_DOMAIN_ERROR_POLICY
130 when an invalid argument is encountered. For the purposes of this example,
131 we'll pass a negative degrees of freedom parameter to the student's t distribution.
134 Since we know that this is a single file program we could just add:
136 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
139 to the top of the source file to change the default policy to one that
140 simply returns a NaN when a domain error occurs. Alternatively we could
143 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
146 To ensure the <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
147 is set when a domain error occurs as well as returning a NaN.
150 This is safe provided the program consists of a single translation unit
151 <span class="emphasis"><em>and</em></span> we place the define <span class="emphasis"><em>before</em></span>
152 any #includes. Note that should we add the define after the includes then
153 it will have no effect! A warning such as:
155 <pre class="programlisting">warning C4005: 'BOOST_MATH_OVERFLOW_ERROR_POLICY' : macro redefinition</pre>
157 is a certain sign that it will <span class="emphasis"><em>not</em></span> have the desired
161 We'll begin our sample program with the needed includes:
165 <pre class="programlisting"><span class="comment">// Boost</span>
166 <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">students_t</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
167 <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">students_t</span><span class="special">;</span> <span class="comment">// Probability of students_t(df, t).</span>
169 <span class="comment">// std</span>
170 <span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
171 <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span>
172 <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
174 <span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">stdexcept</span><span class="special">></span>
175 <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">;</span>
177 <span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstddef</span><span class="special">></span>
178 <span class="comment">// using ::errno</span>
183 Next we'll define the program's main() to call the student's t distribution
184 with an invalid degrees of freedom parameter, the program is set up to
185 handle either an exception or a NaN:
189 <pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
190 <span class="special">{</span>
191 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Example error handling using Student's t function. "</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
192 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"BOOST_MATH_DOMAIN_ERROR_POLICY is set to: "</span>
193 <span class="special"><<</span> <span class="identifier">BOOST_STRINGIZE</span><span class="special">(</span><span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
195 <span class="keyword">double</span> <span class="identifier">degrees_of_freedom</span> <span class="special">=</span> <span class="special">-</span><span class="number">1</span><span class="special">;</span> <span class="comment">// A bad argument!</span>
196 <span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
198 <span class="keyword">try</span>
199 <span class="special">{</span>
200 <span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="comment">// Clear/reset.</span>
201 <span class="identifier">students_t</span> <span class="identifier">dist</span><span class="special">(</span><span class="identifier">degrees_of_freedom</span><span class="special">);</span> <span class="comment">// exception is thrown here if enabled.</span>
202 <span class="keyword">double</span> <span class="identifier">p</span> <span class="special">=</span> <span class="identifier">cdf</span><span class="special">(</span><span class="identifier">dist</span><span class="special">,</span> <span class="identifier">t</span><span class="special">);</span>
203 <span class="comment">// Test for error reported by other means:</span>
204 <span class="keyword">if</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">isnan</span><span class="special">)(</span><span class="identifier">p</span><span class="special">))</span>
205 <span class="special">{</span>
206 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"cdf returned a NaN!"</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
207 <span class="keyword">if</span> <span class="special">(</span><span class="identifier">errno</span> <span class="special">!=</span> <span class="number">0</span><span class="special">)</span>
208 <span class="special">{</span> <span class="comment">// So errno has been set.</span>
209 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno is set to: "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
210 <span class="special">}</span>
211 <span class="special">}</span>
212 <span class="keyword">else</span>
213 <span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Probability of Student's t is "</span> <span class="special"><<</span> <span class="identifier">p</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
214 <span class="special">}</span>
215 <span class="keyword">catch</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">&</span> <span class="identifier">e</span><span class="special">)</span>
216 <span class="special">{</span>
217 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span>
218 <span class="string">"\n"</span><span class="string">"Message from thrown exception was:\n "</span> <span class="special"><<</span> <span class="identifier">e</span><span class="special">.</span><span class="identifier">what</span><span class="special">()</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
219 <span class="special">}</span>
220 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
221 <span class="special">}</span> <span class="comment">// int main()</span>
226 Here's what the program output looks like with a default build (one that
227 <span class="bold"><strong>does throw exceptions</strong></span>):
229 <pre class="programlisting">Example error handling using Student's t function.
230 BOOST_MATH_DOMAIN_ERROR_POLICY is set to: throw_on_error
232 Message from thrown exception was:
233 Error in function boost::math::students_t_distribution<double>::students_t_distribution:
234 Degrees of freedom argument is -1, but must be > 0 !
237 Alternatively let's build with:
239 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
242 Now the program output is:
244 <pre class="programlisting">Example error handling using Student's t function.
245 BOOST_MATH_DOMAIN_ERROR_POLICY is set to: ignore_error
249 And finally let's build with:
251 <pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
254 Which gives the output show errno:
256 <pre class="programlisting">Example error handling using Student's t function.
257 BOOST_MATH_DOMAIN_ERROR_POLICY is set to: errno_on_error
262 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
263 <td align="left"></td>
264 <td align="right"><div class="copyright-footer">Copyright © 2006-2010 John Maddock, Paul A. Bristow, Hubert Holin, Xiaogang Zhang, Bruno
265 Lalande, Johan Råde, Gautam Sewani, Thijs van den Berg and Benjamin Sobotta<p>
266 Distributed under the Boost Software License, Version 1.0. (See accompanying
267 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>)
272 <div class="spirit-nav">
273 <a accesskey="p" href="policy_usage.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../pol_tutorial.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="ad_hoc_dist_policies.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a>