Initial commit
This commit is contained in:
@@ -0,0 +1,105 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Setting Policies for Distributions on an Ad Hoc Basis</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="changing_policy_defaults.html" title="Changing the Policy Defaults">
|
||||
<link rel="next" href="ad_hoc_sf_policies.html" title="Changing the Policy on an Ad Hoc Basis for the Special Functions">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="changing_policy_defaults.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_sf_policies.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.ad_hoc_dist_policies"></a><a class="link" href="ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">Setting
|
||||
Policies for Distributions on an Ad Hoc Basis</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
All of the statistical distributions in this library are class templates
|
||||
that accept two template parameters: real type (float, double ...) and policy
|
||||
(how to handle exceptional events), both with sensible defaults, for example:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
|
||||
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span> <span class="special">=</span> <span class="keyword">double</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span> <span class="special">=</span> <span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special"><></span> <span class="special">></span>
|
||||
<span class="keyword">class</span> <span class="identifier">fisher_f_distribution</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">fisher_f_distribution</span><span class="special"><></span> <span class="identifier">fisher_f</span><span class="special">;</span>
|
||||
|
||||
<span class="special">}}</span>
|
||||
</pre>
|
||||
<p>
|
||||
This policy gets used by all the accessor functions that accept a distribution
|
||||
as an argument, and forwarded to all the functions called by these. So if
|
||||
you use the shorthand-typedef for the distribution, then you get <code class="computeroutput"><span class="keyword">double</span></code> precision arithmetic and all the default
|
||||
policies.
|
||||
</p>
|
||||
<p>
|
||||
However, say for example we wanted to evaluate the quantile of the binomial
|
||||
distribution at float precision, without internal promotion to double, and
|
||||
with the result rounded to the <span class="emphasis"><em>nearest</em></span> integer, then
|
||||
here's how it can be done:
|
||||
</p>
|
||||
<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">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
<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">binomial_distribution</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Begin by defining a policy type, that gives the behaviour we want:</span>
|
||||
|
||||
<span class="comment">//using namespace boost::math::policies; or explicitly</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
|
||||
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">promote_float</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">discrete_quantile</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">integer_round_nearest</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span>
|
||||
<span class="identifier">promote_float</span><span class="special"><</span><span class="keyword">false</span><span class="special">>,</span> <span class="comment">// Do not promote to double.</span>
|
||||
<span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_nearest</span><span class="special">></span> <span class="comment">// Round result to nearest integer.</span>
|
||||
<span class="special">></span> <span class="identifier">mypolicy</span><span class="special">;</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="comment">// Then define a new distribution that uses it:</span>
|
||||
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">binomial_distribution</span><span class="special"><</span><span class="keyword">float</span><span class="special">,</span> <span class="identifier">mypolicy</span><span class="special">></span> <span class="identifier">mybinom</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// And now use it to get the quantile:</span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"quantile(mybinom(200, 0.25), 0.05) is: "</span> <span class="special"><<</span>
|
||||
<span class="identifier">quantile</span><span class="special">(</span><span class="identifier">mybinom</span><span class="special">(</span><span class="number">200</span><span class="special">,</span> <span class="number">0.25</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Which outputs:
|
||||
</p>
|
||||
<pre class="programlisting">quantile is: 40</pre>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="changing_policy_defaults.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_sf_policies.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,174 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Changing the Policy on an Ad Hoc Basis for the Special Functions</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">
|
||||
<link rel="next" href="namespace_policies.html" title="Setting Policies at Namespace or Translation Unit Scope">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="ad_hoc_dist_policies.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="namespace_policies.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.ad_hoc_sf_policies"></a><a class="link" href="ad_hoc_sf_policies.html" title="Changing the Policy on an Ad Hoc Basis for the Special Functions">Changing
|
||||
the Policy on an Ad Hoc Basis for the Special Functions</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
All of the special functions in this library come in two overloaded forms,
|
||||
one with a final "policy" parameter, and one without. For example:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
|
||||
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">Policy</span><span class="special">></span>
|
||||
<span class="identifier">RealType</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RealType</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">Policy</span><span class="special">&);</span>
|
||||
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">></span>
|
||||
<span class="identifier">RealType</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RealType</span><span class="special">);</span>
|
||||
|
||||
<span class="special">}}</span> <span class="comment">// namespaces</span>
|
||||
</pre>
|
||||
<p>
|
||||
Normally, the second version is just a forwarding wrapper to the first like
|
||||
this:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">></span>
|
||||
<span class="keyword">inline</span> <span class="identifier">RealType</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RealType</span> <span class="identifier">x</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">return</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">x</span><span class="special">,</span> <span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special"><>());</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
So calling a special function with a specific policy is just a matter of
|
||||
defining the policy type to use and passing it as the final parameter. For
|
||||
example, suppose we want <code class="computeroutput"><span class="identifier">tgamma</span></code>
|
||||
to behave in a C-compatible fashion and set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> when an error occurs, and never throw
|
||||
an exception:
|
||||
</p>
|
||||
<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">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
<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">tgamma</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Define the policy to use:</span>
|
||||
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span> <span class="comment">// may be convenient, or</span>
|
||||
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
|
||||
<span class="comment">// Types of error whose action can be altered by policies:.</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">evaluation_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">overflow_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">pole_error</span><span class="special">;</span>
|
||||
<span class="comment">// Actions on error (in enum error_policy_type):</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">errno_on_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">ignore_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">throw_on_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">user_error</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span>
|
||||
<span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">pole_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">evaluation_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">></span>
|
||||
<span class="special">></span> <span class="identifier">c_policy</span><span class="special">;</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="comment">// Now use the policy when calling tgamma:</span>
|
||||
|
||||
<span class="comment">// http://msdn.microsoft.com/en-us/library/t3ayayh1.aspx </span>
|
||||
<span class="comment">// Microsoft errno declared in STDLIB.H as "extern int errno;" </span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="comment">// Reset.</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(30000) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">tgamma</span><span class="special">(</span><span class="number">30000</span><span class="special">,</span> <span class="identifier">c_policy</span><span class="special">())</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Too big parameter</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// errno 34 Numerical result out of range.</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(-10) is: "</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">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">,</span> <span class="identifier">c_policy</span><span class="special">())</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Negative parameter.</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// error 33 Numerical argument out of domain.</span>
|
||||
<span class="special">}</span> <span class="comment">// int main()</span>
|
||||
</pre>
|
||||
<p>
|
||||
which outputs:
|
||||
</p>
|
||||
<pre class="programlisting">Result of tgamma(30000) is: 1.#INF
|
||||
errno = 34
|
||||
Result of tgamma(-10) is: 1.#QNAN
|
||||
errno = 33
|
||||
</pre>
|
||||
<p>
|
||||
Alternatively, for ad hoc use, we can use the <code class="computeroutput"><span class="identifier">make_policy</span></code>
|
||||
helper function to create a policy for us: this usage is more verbose, so
|
||||
is probably only preferred when a policy is going to be used once only:
|
||||
</p>
|
||||
<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">special_functions</span><span class="special">/</span><span class="identifier">gamma</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
<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">tgamma</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// using namespace boost::math::policies; // or</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">errno_on_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">make_policy</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">pole_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">overflow_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">evaluation_error</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(30000) is: "</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">tgamma</span><span class="special">(</span>
|
||||
<span class="number">30000</span><span class="special">,</span>
|
||||
<span class="identifier">make_policy</span><span class="special">(</span>
|
||||
<span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>(),</span>
|
||||
<span class="identifier">pole_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>(),</span>
|
||||
<span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>(),</span>
|
||||
<span class="identifier">evaluation_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>()</span>
|
||||
<span class="special">)</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>
|
||||
<span class="comment">// Check errno was set:</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="comment">// and again with evaluation at a pole:</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(-10) is: "</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">tgamma</span><span class="special">(</span>
|
||||
<span class="special">-</span><span class="number">10</span><span class="special">,</span>
|
||||
<span class="identifier">make_policy</span><span class="special">(</span>
|
||||
<span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>(),</span>
|
||||
<span class="identifier">pole_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>(),</span>
|
||||
<span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>(),</span>
|
||||
<span class="identifier">evaluation_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>()</span>
|
||||
<span class="special">)</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>
|
||||
<span class="comment">// Check errno was set:</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="ad_hoc_dist_policies.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="namespace_policies.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,258 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Changing the Policy Defaults</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="policy_usage.html" title="So How are Policies Used Anyway?">
|
||||
<link rel="next" href="ad_hoc_dist_policies.html" title="Setting Policies for Distributions on an Ad Hoc Basis">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<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>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.changing_policy_defaults"></a><a class="link" href="changing_policy_defaults.html" title="Changing the Policy Defaults">Changing
|
||||
the Policy Defaults</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The default policies used by the library are changed by the usual configuration
|
||||
macro method.
|
||||
</p>
|
||||
<p>
|
||||
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>
|
||||
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>
|
||||
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>
|
||||
exception.
|
||||
</p>
|
||||
<div class="tip"><table border="0" summary="Tip">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="../../../../../../doc/src/images/tip.png"></td>
|
||||
<th align="left">Tip</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top">
|
||||
<p>
|
||||
For Microsoft Visual Studio,you can add to the Project Property Page, C/C++,
|
||||
Preprocessor, Preprocessor definitions like:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span><span class="special">=</span><span class="number">0</span>
|
||||
<span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span><span class="special">=</span><span class="identifier">errno_on_error</span></pre>
|
||||
<p>
|
||||
This may be helpful to avoid complications with pre-compiled headers that
|
||||
may mean that the equivalent definitions in source code:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_ASSERT_UNDEFINED_POLICY</span> <span class="keyword">false</span>
|
||||
<span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_OVERFLOW_ERROR_POLICY</span> <span class="identifier">errno_on_error</span></pre>
|
||||
<p>
|
||||
<span class="bold"><strong>may be ignored</strong></span>.
|
||||
</p>
|
||||
<p>
|
||||
The compiler command line shows:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="special">/</span><span class="identifier">D</span> <span class="string">"BOOST_MATH_ASSERT_UNDEFINED_POLICY=0"</span>
|
||||
<span class="special">/</span><span class="identifier">D</span> <span class="string">"BOOST_MATH_OVERFLOW_ERROR_POLICY=errno_on_error"</span></pre>
|
||||
</td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
There is however a very important caveat to this:
|
||||
</p>
|
||||
<div class="important"><table border="0" summary="Important">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Important]" src="../../../../../../doc/src/images/important.png"></td>
|
||||
<th align="left">Important</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top">
|
||||
<p>
|
||||
<span class="bold"><strong><span class="emphasis"><em>Default policies changed by setting configuration
|
||||
macros must be changed uniformly in every translation unit in the program.</em></span></strong></span>
|
||||
</p>
|
||||
<p>
|
||||
Failure to follow this rule may result in violations of the "One Definition
|
||||
Rule (ODR)" and result in unpredictable program behaviour.
|
||||
</p>
|
||||
</td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
That means there are only two safe ways to use these macros:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||||
<li class="listitem">
|
||||
Edit them in <a href="../../../../../../boost/math/tools/user.hpp" target="_top">boost/math/tools/user.hpp</a>,
|
||||
so that the defaults are set on an installation-wide basis. Unfortunately
|
||||
this may not be convenient if you are using a pre-installed Boost distribution
|
||||
(on Linux for example).
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Set the defines in your project's Makefile or build environment, so that
|
||||
they are set uniformly across all translation units.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
What you should <span class="bold"><strong>not</strong></span> do is:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">
|
||||
Set the defines in the source file using <code class="computeroutput"><span class="preprocessor">#define</span></code>
|
||||
as doing so almost certainly will break your program, unless you're absolutely
|
||||
certain that the program is restricted to a single translation unit.
|
||||
</li></ul></div>
|
||||
<p>
|
||||
And, yes, you will find examples in our test programs where we break this
|
||||
rule: but only because we know there will always be a single translation
|
||||
unit only: <span class="emphasis"><em>don't say that you weren't warned!</em></span>
|
||||
</p>
|
||||
<p>
|
||||
The following example demonstrates the effect of setting the macro BOOST_MATH_DOMAIN_ERROR_POLICY
|
||||
when an invalid argument is encountered. For the purposes of this example,
|
||||
we'll pass a negative degrees of freedom parameter to the student's t distribution.
|
||||
</p>
|
||||
<p>
|
||||
Since we know that this is a single file program we could just add:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
|
||||
</pre>
|
||||
<p>
|
||||
to the top of the source file to change the default policy to one that simply
|
||||
returns a NaN when a domain error occurs. Alternatively we could use:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
|
||||
</pre>
|
||||
<p>
|
||||
To ensure the <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code>
|
||||
is set when a domain error occurs as well as returning a NaN.
|
||||
</p>
|
||||
<p>
|
||||
This is safe provided the program consists of a single translation unit
|
||||
<span class="emphasis"><em>and</em></span> we place the define <span class="emphasis"><em>before</em></span>
|
||||
any #includes. Note that should we add the define after the includes then
|
||||
it will have no effect! A warning such as:
|
||||
</p>
|
||||
<pre class="programlisting">warning C4005: 'BOOST_MATH_OVERFLOW_ERROR_POLICY' : macro redefinition</pre>
|
||||
<p>
|
||||
is a certain sign that it will <span class="emphasis"><em>not</em></span> have the desired
|
||||
effect.
|
||||
</p>
|
||||
<p>
|
||||
We'll begin our sample program with the needed includes:
|
||||
</p>
|
||||
<pre class="programlisting"> <span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
|
||||
|
||||
<span class="comment">// Boost</span>
|
||||
<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>
|
||||
<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>
|
||||
|
||||
<span class="comment">// std</span>
|
||||
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
|
||||
<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span>
|
||||
<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">stdexcept</span><span class="special">></span>
|
||||
<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span><span class="special">;</span>
|
||||
|
||||
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">cstddef</span><span class="special">></span>
|
||||
<span class="comment">// using ::errno</span>
|
||||
</pre>
|
||||
<p>
|
||||
Next we'll define the program's main() to call the student's t distribution
|
||||
with an invalid degrees of freedom parameter, the program is set up to handle
|
||||
either an exception or a NaN:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<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>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"BOOST_MATH_DOMAIN_ERROR_POLICY is set to: "</span>
|
||||
<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>
|
||||
|
||||
<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>
|
||||
<span class="keyword">double</span> <span class="identifier">t</span> <span class="special">=</span> <span class="number">10</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">try</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span> <span class="comment">// Clear/reset.</span>
|
||||
<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>
|
||||
<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>
|
||||
<span class="comment">// Test for error reported by other means:</span>
|
||||
<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>
|
||||
<span class="special">{</span>
|
||||
<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>
|
||||
<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>
|
||||
<span class="special">{</span> <span class="comment">// So errno has been set.</span>
|
||||
<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>
|
||||
<span class="special">}</span>
|
||||
<span class="special">}</span>
|
||||
<span class="keyword">else</span>
|
||||
<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>
|
||||
<span class="special">}</span>
|
||||
<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>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span>
|
||||
<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>
|
||||
<span class="special">}</span>
|
||||
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="special">}</span> <span class="comment">// int main()</span>
|
||||
</pre>
|
||||
<p>
|
||||
Here's what the program output looks like with a default build (one that
|
||||
<span class="bold"><strong>does throw exceptions</strong></span>):
|
||||
</p>
|
||||
<pre class="programlisting">Example error handling using Student's t function.
|
||||
BOOST_MATH_DOMAIN_ERROR_POLICY is set to: throw_on_error
|
||||
|
||||
Message from thrown exception was:
|
||||
Error in function boost::math::students_t_distribution<double>::students_t_distribution:
|
||||
Degrees of freedom argument is -1, but must be > 0 !
|
||||
</pre>
|
||||
<p>
|
||||
Alternatively let's build with:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">ignore_error</span>
|
||||
</pre>
|
||||
<p>
|
||||
Now the program output is:
|
||||
</p>
|
||||
<pre class="programlisting">Example error handling using Student's t function.
|
||||
BOOST_MATH_DOMAIN_ERROR_POLICY is set to: ignore_error
|
||||
cdf returned a NaN!
|
||||
</pre>
|
||||
<p>
|
||||
And finally let's build with:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#define</span> <span class="identifier">BOOST_MATH_DOMAIN_ERROR_POLICY</span> <span class="identifier">errno_on_error</span>
|
||||
</pre>
|
||||
<p>
|
||||
Which gives the output show errno:
|
||||
</p>
|
||||
<pre class="programlisting">Example error handling using Student's t function.
|
||||
BOOST_MATH_DOMAIN_ERROR_POLICY is set to: errno_on_error
|
||||
cdf returned a NaN!
|
||||
errno is set to: 33
|
||||
</pre>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<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>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,366 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Setting Policies at Namespace or Translation Unit Scope</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="ad_hoc_sf_policies.html" title="Changing the Policy on an Ad Hoc Basis for the Special Functions">
|
||||
<link rel="next" href="user_def_err_pol.html" title="Calling User Defined Error Handlers">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="ad_hoc_sf_policies.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="user_def_err_pol.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.namespace_policies"></a><a class="link" href="namespace_policies.html" title="Setting Policies at Namespace or Translation Unit Scope">Setting
|
||||
Policies at Namespace or Translation Unit Scope</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Sometimes what you want to do is just change a set of policies within the
|
||||
current scope: <span class="bold"><strong>the one thing you should not do in this
|
||||
situation is use the configuration macros</strong></span>, as this can lead to
|
||||
"One Definition Rule" violations. Instead this library provides
|
||||
a pair of macros especially for this purpose.
|
||||
</p>
|
||||
<p>
|
||||
Let's consider the special functions first: we can declare a set of forwarding
|
||||
functions that all use a specific policy using the macro BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS(<span class="emphasis"><em>Policy</em></span>).
|
||||
This macro should be used either inside a unique namespace set aside for
|
||||
the purpose (for example, a C namespace for a C-style policy), or an unnamed
|
||||
namespace if you just want the functions visible in global scope for the
|
||||
current file only.
|
||||
</p>
|
||||
<p>
|
||||
Suppose we want <code class="computeroutput"><span class="identifier">C</span><span class="special">::</span><span class="identifier">foo</span><span class="special">()</span></code> to
|
||||
behave in a C-compatible way and set <code class="computeroutput"><span class="special">::</span><span class="identifier">errno</span></code> on error rather than throwing any
|
||||
exceptions.
|
||||
</p>
|
||||
<p>
|
||||
We'll begin by including the needed header for our function:
|
||||
</p>
|
||||
<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">special_functions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
<span class="comment">//using boost::math::tgamma; // Not needed because using C::tgamma.</span>
|
||||
</pre>
|
||||
<p>
|
||||
Open up the "C" namespace that we'll use for our functions, and
|
||||
define the policy type we want: in this case a C-style one that sets ::errno
|
||||
and returns a standard value, rather than throwing exceptions.
|
||||
</p>
|
||||
<p>
|
||||
Any policies we don't specify here will inherit the defaults.
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">C</span>
|
||||
<span class="special">{</span> <span class="comment">// To hold our C-style policy.</span>
|
||||
<span class="comment">//using namespace boost::math::policies; or explicitly:</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
|
||||
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">domain_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">pole_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">overflow_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">evaluation_error</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">errno_on_error</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span>
|
||||
<span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">pole_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">evaluation_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">></span>
|
||||
<span class="special">></span> <span class="identifier">c_policy</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
All we need do now is invoke the BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS macro
|
||||
passing our policy type c_policy as the single argument:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">c_policy</span><span class="special">)</span>
|
||||
|
||||
<span class="special">}</span> <span class="comment">// close namespace C</span>
|
||||
</pre>
|
||||
<p>
|
||||
We now have a set of forwarding functions defined in namespace C that all
|
||||
look something like this:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">></span>
|
||||
<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special"><</span><span class="identifier">RT</span><span class="special">>::</span><span class="identifier">type</span>
|
||||
<span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RT</span> <span class="identifier">z</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">c_policy</span><span class="special">());</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
So that when we call <code class="computeroutput"><span class="identifier">C</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code>, we
|
||||
really end up calling <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span>
|
||||
<span class="identifier">C</span><span class="special">::</span><span class="identifier">c_policy</span><span class="special">())</span></code>:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(30000) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="number">30000</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// Note using C::tgamma</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// errno = 34</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(-10) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">C</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// errno = 33, overwriting previous value of 34.</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Which outputs:
|
||||
</p>
|
||||
<pre class="programlisting">Result of C::tgamma(30000) is: 1.#INF
|
||||
errno = 34
|
||||
Result of C::tgamma(-10) is: 1.#QNAN
|
||||
errno = 33
|
||||
</pre>
|
||||
<p>
|
||||
This mechanism is particularly useful when we want to define a project-wide
|
||||
policy, and don't want to modify the Boost source, or to set project wide
|
||||
build macros (possibly fragile and easy to forget).
|
||||
</p>
|
||||
<p>
|
||||
The same mechanism works well at file scope as well, by using an unnamed
|
||||
namespace, we can ensure that these declarations don't conflict with any
|
||||
alternate policies present in other translation units:
|
||||
</p>
|
||||
<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">special_functions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
<span class="comment">// using boost::math::tgamma; // Would create an ambiguity between</span>
|
||||
<span class="comment">// 'double boost::math::tgamma<int>(T)' and</span>
|
||||
<span class="comment">// 'double 'anonymous-namespace'::tgamma<int>(RT)'.</span>
|
||||
|
||||
<span class="keyword">namespace</span> <span class="identifier">mymath</span>
|
||||
<span class="special">{</span> <span class="comment">// unnamed</span>
|
||||
|
||||
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span>
|
||||
<span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">pole_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="identifier">evaluation_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">></span>
|
||||
<span class="special">></span> <span class="identifier">c_policy</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">c_policy</span><span class="special">)</span>
|
||||
</pre>
|
||||
<p>
|
||||
So that when we call <code class="computeroutput"><span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code>,
|
||||
we really end up calling <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span>
|
||||
<span class="identifier">anonymous</span><span class="special">-</span><span class="keyword">namespace</span><span class="special">::</span><span class="identifier">c_policy</span><span class="special">())</span></code>.
|
||||
</p>
|
||||
<pre class="programlisting"><span class="special">}</span> <span class="comment">// close unnamed namespace</span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(30000) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="number">30000</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="comment">// tgamma in unnamed namespace in this translation unit (file) only.</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(-10) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="comment">// Default tgamma policy would throw an exception, and abort.</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Handling policies for the statistical distributions is very similar except
|
||||
that now the macro BOOST_MATH_DECLARE_DISTRIBUTIONS accepts two parameters:
|
||||
the floating point type to use, and the policy type to apply. For example:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">BOOST_MATH_DECLARE_DISTRIBUTIONS</span><span class="special">(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">mypolicy</span><span class="special">)</span>
|
||||
</pre>
|
||||
<p>
|
||||
Results a set of typedefs being defined like this:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">typedef</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><span class="keyword">double</span><span class="special">,</span> <span class="identifier">mypolicy</span><span class="special">></span> <span class="identifier">normal</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
The name of each typedef is the same as the name of the distribution class
|
||||
template, but without the "_distribution" suffix.
|
||||
</p>
|
||||
<p>
|
||||
Suppose we want a set of distributions to behave as follows:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||||
<li class="listitem">
|
||||
Return infinity on overflow, rather than throwing an exception.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Don't perform any promotion from double to long double internally.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Return the closest integer result from the quantiles of discrete distributions.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
We'll begin by including the needed header for all the distributions:
|
||||
</p>
|
||||
<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">hpp</span><span class="special">></span>
|
||||
</pre>
|
||||
<p>
|
||||
Open up an appropriate namespace, calling it <code class="computeroutput"><span class="identifier">my_distributions</span></code>,
|
||||
for our distributions, and define the policy type we want. Any policies we
|
||||
don't specify here will inherit the defaults:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">my_distributions</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
|
||||
<span class="comment">// using boost::math::policies::errno_on_error; // etc.</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span>
|
||||
<span class="comment">// return infinity and set errno rather than throw:</span>
|
||||
<span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="comment">// Don't promote double -> long double internally:</span>
|
||||
<span class="identifier">promote_double</span><span class="special"><</span><span class="keyword">false</span><span class="special">>,</span>
|
||||
<span class="comment">// Return the closest integer result for discrete quantiles:</span>
|
||||
<span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_nearest</span><span class="special">></span>
|
||||
<span class="special">></span> <span class="identifier">my_policy</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
All we need do now is invoke the BOOST_MATH_DECLARE_DISTRIBUTIONS macro passing
|
||||
the floating point type <code class="computeroutput"><span class="keyword">double</span></code>
|
||||
and policy types <code class="computeroutput"><span class="identifier">my_policy</span></code>
|
||||
as arguments:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">BOOST_MATH_DECLARE_DISTRIBUTIONS</span><span class="special">(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">)</span>
|
||||
|
||||
<span class="special">}</span> <span class="comment">// close namespace my_namespace</span>
|
||||
</pre>
|
||||
<p>
|
||||
We now have a set of typedefs defined in namespace my_distributions that
|
||||
all look something like this:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">typedef</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><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">></span> <span class="identifier">normal</span><span class="special">;</span>
|
||||
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">cauchy_distribution</span><span class="special"><</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">></span> <span class="identifier">cauchy</span><span class="special">;</span>
|
||||
<span class="keyword">typedef</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">gamma_distribution</span><span class="special"><</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">></span> <span class="identifier">gamma</span><span class="special">;</span>
|
||||
<span class="comment">// etc</span>
|
||||
</pre>
|
||||
<p>
|
||||
So that when we use my_distributions::normal we really end up using <code class="computeroutput"><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><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">></span></code>:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// Construct distribution with something we know will overflow</span>
|
||||
<span class="comment">// (using double rather than if promoted to long double):</span>
|
||||
<span class="identifier">my_distributions</span><span class="special">::</span><span class="identifier">normal</span> <span class="identifier">norm</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span>
|
||||
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of quantile(norm, 0) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// -infinity.</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of quantile(norm, 1) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// +infinity.</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Now try a discrete distribution.</span>
|
||||
<span class="identifier">my_distributions</span><span class="special">::</span><span class="identifier">binomial</span> <span class="identifier">binom</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of quantile(binom, 0.05) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom</span><span class="special">,</span> <span class="number">0.05</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span> <span class="comment">// To check we get integer results.</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of quantile(complement(binom, 0.05)) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">binom</span><span class="special">,</span> <span class="number">0.05</span><span class="special">))</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Which outputs:
|
||||
</p>
|
||||
<pre class="programlisting">Result of quantile(norm, 0) is: -1.#INF
|
||||
errno = 34
|
||||
Result of quantile(norm, 1) is: 1.#INF
|
||||
errno = 34
|
||||
Result of quantile(binom, 0.05) is: 1
|
||||
Result of quantile(complement(binom, 0.05)) is: 8
|
||||
</pre>
|
||||
<p>
|
||||
This mechanism is particularly useful when we want to define a project-wide
|
||||
policy, and don't want to modify the Boost source or set project wide build
|
||||
macros (possibly fragile and easy to forget).
|
||||
</p>
|
||||
<div class="note"><table border="0" summary="Note">
|
||||
<tr>
|
||||
<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td>
|
||||
<th align="left">Note</th>
|
||||
</tr>
|
||||
<tr><td align="left" valign="top"><p>
|
||||
There is an important limitation to note: you can *not use the macros BOOST_MATH_DECLARE_DISTRIBUTIONS
|
||||
and BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS <span class="emphasis"><em>in the same namespace</em></span>*,
|
||||
as doing so creates ambiguities between functions and distributions of
|
||||
the same name.
|
||||
</p></td></tr>
|
||||
</table></div>
|
||||
<p>
|
||||
As before, the same mechanism works well at file scope as well: by using
|
||||
an unnamed namespace, we can ensure that these declarations don't conflict
|
||||
with any alternate policies present in other translation units:
|
||||
</p>
|
||||
<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">hpp</span><span class="special">></span> <span class="comment">// All distributions.</span>
|
||||
<span class="comment">// using boost::math::normal; // Would create an ambguity between</span>
|
||||
<span class="comment">// boost::math::normal_distribution<RealType> boost::math::normal and</span>
|
||||
<span class="comment">// 'anonymous-namespace'::normal'.</span>
|
||||
|
||||
<span class="keyword">namespace</span>
|
||||
<span class="special">{</span> <span class="comment">// anonymous or unnnamed (rather than named as in policy_eg_6.cpp).</span>
|
||||
|
||||
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
|
||||
<span class="comment">// using boost::math::policies::errno_on_error; // etc.</span>
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span>
|
||||
<span class="comment">// return infinity and set errno rather than throw:</span>
|
||||
<span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span>
|
||||
<span class="comment">// Don't promote double -> long double internally:</span>
|
||||
<span class="identifier">promote_double</span><span class="special"><</span><span class="keyword">false</span><span class="special">>,</span>
|
||||
<span class="comment">// Return the closest integer result for discrete quantiles:</span>
|
||||
<span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_nearest</span><span class="special">></span>
|
||||
<span class="special">></span> <span class="identifier">my_policy</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">BOOST_MATH_DECLARE_DISTRIBUTIONS</span><span class="special">(</span><span class="keyword">double</span><span class="special">,</span> <span class="identifier">my_policy</span><span class="special">)</span>
|
||||
|
||||
<span class="special">}</span> <span class="comment">// close namespace my_namespace</span>
|
||||
|
||||
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// Construct distribution with something we know will overflow.</span>
|
||||
<span class="identifier">normal</span> <span class="identifier">norm</span><span class="special">(</span><span class="number">10</span><span class="special">,</span> <span class="number">2</span><span class="special">);</span> <span class="comment">// using 'anonymous-namespace'::normal</span>
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of quantile(norm, 0) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">0</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">errno</span> <span class="special">=</span> <span class="number">0</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of quantile(norm, 1) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">norm</span><span class="special">,</span> <span class="number">1</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"errno = "</span> <span class="special"><<</span> <span class="identifier">errno</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="comment">// Now try a discrete distribution:</span>
|
||||
<span class="identifier">binomial</span> <span class="identifier">binom</span><span class="special">(</span><span class="number">20</span><span class="special">,</span> <span class="number">0.25</span><span class="special">);</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of quantile(binom, 0.05) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom</span><span class="special">,</span> <span class="number">0.05</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of quantile(complement(binom, 0.05)) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">complement</span><span class="special">(</span><span class="identifier">binom</span><span class="special">,</span> <span class="number">0.05</span><span class="special">))</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="ad_hoc_sf_policies.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="user_def_err_pol.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,141 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Policies Have Sensible Defaults</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="what_is_a_policy.html" title="So Just What is a Policy Anyway?">
|
||||
<link rel="next" href="policy_usage.html" title="So How are Policies Used Anyway?">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="what_is_a_policy.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="policy_usage.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.policy_tut_defaults"></a><a class="link" href="policy_tut_defaults.html" title="Policies Have Sensible Defaults">Policies
|
||||
Have Sensible Defaults</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Most of the time you can just ignore the policy framework.
|
||||
</p>
|
||||
<p>
|
||||
<span class="emphasis"><em>*The defaults for the various policies are as follows, if these
|
||||
work OK for you then you can stop reading now!</em></span>
|
||||
</p>
|
||||
<div class="variablelist">
|
||||
<p class="title"><b></b></p>
|
||||
<dl class="variablelist">
|
||||
<dt><span class="term">Domain Error</span></dt>
|
||||
<dd><p>
|
||||
Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code> exception.
|
||||
</p></dd>
|
||||
<dt><span class="term">Pole Error</span></dt>
|
||||
<dd><p>
|
||||
Occurs when a function is evaluated at a pole: throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">domain_error</span></code> exception.
|
||||
</p></dd>
|
||||
<dt><span class="term">Overflow Error</span></dt>
|
||||
<dd><p>
|
||||
Throws a <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">overflow_error</span></code> exception.
|
||||
</p></dd>
|
||||
<dt><span class="term">Underflow</span></dt>
|
||||
<dd><p>
|
||||
Ignores the underflow, and returns zero.
|
||||
</p></dd>
|
||||
<dt><span class="term">Denormalised Result</span></dt>
|
||||
<dd><p>
|
||||
Ignores the fact that the result is denormalised, and returns it.
|
||||
</p></dd>
|
||||
<dt><span class="term">Rounding Error</span></dt>
|
||||
<dd><p>
|
||||
Throws a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">rounding_error</span></code> exception.
|
||||
</p></dd>
|
||||
<dt><span class="term">Internal Evaluation Error</span></dt>
|
||||
<dd><p>
|
||||
Throws a <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">evaluation_error</span></code> exception.
|
||||
</p></dd>
|
||||
<dt><span class="term">Indeterminate Result Error</span></dt>
|
||||
<dd><p>
|
||||
Returns a result that depends on the function where the error occurred.
|
||||
</p></dd>
|
||||
<dt><span class="term">Promotion of float to double</span></dt>
|
||||
<dd><p>
|
||||
Does occur by default - gives full float precision results.
|
||||
</p></dd>
|
||||
<dt><span class="term">Promotion of double to long double</span></dt>
|
||||
<dd><p>
|
||||
Does occur by default if long double offers more precision than double.
|
||||
</p></dd>
|
||||
<dt><span class="term">Precision of Approximation Used</span></dt>
|
||||
<dd><p>
|
||||
By default uses an approximation that will result in the lowest level
|
||||
of error for the type of the result.
|
||||
</p></dd>
|
||||
<dt><span class="term">Behaviour of Discrete Quantiles</span></dt>
|
||||
<dd>
|
||||
<p>
|
||||
The quantile function will by default return an integer result that
|
||||
has been <span class="emphasis"><em>rounded outwards</em></span>. That is to say lower
|
||||
quantiles (where the probability is less than 0.5) are rounded downward,
|
||||
and upper quantiles (where the probability is greater than 0.5) are
|
||||
rounded upwards. This behaviour ensures that if an X% quantile is requested,
|
||||
then <span class="emphasis"><em>at least</em></span> the requested coverage will be present
|
||||
in the central region, and <span class="emphasis"><em>no more than</em></span> the requested
|
||||
coverage will be present in the tails.
|
||||
</p>
|
||||
<p>
|
||||
This behaviour can be changed so that the quantile functions are rounded
|
||||
differently, or even return a real-valued result using <a class="link" href="../pol_overview.html" title="Policy Overview">Policies</a>.
|
||||
It is strongly recommended that you read the tutorial <a class="link" href="understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
|
||||
Quantiles of Discrete Distributions</a> before using the quantile
|
||||
function on a discrete distribution. The <a class="link" href="../pol_ref/discrete_quant_ref.html" title="Discrete Quantile Policies">reference
|
||||
docs</a> describe how to change the rounding policy for these distributions.
|
||||
</p>
|
||||
</dd>
|
||||
</dl>
|
||||
</div>
|
||||
<p>
|
||||
What's more, if you define your own policy type, then it automatically inherits
|
||||
the defaults for any policies not explicitly set, so given:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="comment">// Define a policy that sets ::errno on overflow, and does</span>
|
||||
<span class="comment">// not promote double to long double internally:</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span><span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span> <span class="identifier">promote_double</span><span class="special"><</span><span class="keyword">false</span><span class="special">></span> <span class="special">></span> <span class="identifier">mypolicy</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
then <code class="computeroutput"><span class="identifier">mypolicy</span></code> defines a policy
|
||||
where only the overflow error handling and <code class="computeroutput"><span class="keyword">double</span></code>-promotion
|
||||
policies differ from the defaults.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="what_is_a_policy.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="policy_usage.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,73 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>So How are Policies Used Anyway?</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="policy_tut_defaults.html" title="Policies Have Sensible Defaults">
|
||||
<link rel="next" href="changing_policy_defaults.html" title="Changing the Policy Defaults">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="policy_tut_defaults.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="changing_policy_defaults.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.policy_usage"></a><a class="link" href="policy_usage.html" title="So How are Policies Used Anyway?">So How are Policies
|
||||
Used Anyway?</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
The details follow later, but basically policies can be set by either:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||||
<li class="listitem">
|
||||
Defining some macros that change the default behaviour: <span class="bold"><strong>this
|
||||
is the recommended method for setting installation-wide policies</strong></span>.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
By instantiating a distribution object with an explicit policy: this
|
||||
is mainly reserved for ad hoc policy changes.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
By passing a policy to a special function as an optional final argument:
|
||||
this is mainly reserved for ad hoc policy changes.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
By using some helper macros to define a set of functions or distributions
|
||||
in the current namespace that use a specific policy: <span class="bold"><strong>this
|
||||
is the recommended method for setting policies on a project- or translation-unit-wide
|
||||
basis</strong></span>.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
The following sections introduce these methods in more detail.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="policy_tut_defaults.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="changing_policy_defaults.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,417 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Understanding Quantiles of Discrete Distributions</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="user_def_err_pol.html" title="Calling User Defined Error Handlers">
|
||||
<link rel="next" href="../pol_ref.html" title="Policy Reference">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="user_def_err_pol.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="../pol_ref.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.understand_dis_quant"></a><a class="link" href="understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">Understanding
|
||||
Quantiles of Discrete Distributions</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Discrete distributions present us with a problem when calculating the quantile:
|
||||
we are starting from a continuous real-valued variable - the probability
|
||||
- but the result (the value of the random variable) should really be discrete.
|
||||
</p>
|
||||
<p>
|
||||
Consider for example a Binomial distribution, with a sample size of 50, and
|
||||
a success fraction of 0.5. There are a variety of ways we can plot a discrete
|
||||
distribution, but if we plot the PDF as a step-function then it looks something
|
||||
like this:
|
||||
</p>
|
||||
<p>
|
||||
<span class="inlinemediaobject"><img src="../../../graphs/binomial_pdf.png"></span>
|
||||
</p>
|
||||
<p>
|
||||
Now lets suppose that the user asks for a the quantile that corresponds to
|
||||
a probability of 0.05, if we zoom in on the CDF for that region here's what
|
||||
we see:
|
||||
</p>
|
||||
<p>
|
||||
<span class="inlinemediaobject"><img src="../../../graphs/binomial_quantile_1.png"></span>
|
||||
</p>
|
||||
<p>
|
||||
As can be seen there is no random variable that corresponds to a probability
|
||||
of exactly 0.05, so we're left with two choices as shown in the figure:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||||
<li class="listitem">
|
||||
We could round the result down to 18.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
We could round the result up to 19.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
In fact there's actually a third choice as well: we could "pretend"
|
||||
that the distribution was continuous and return a real valued result: in
|
||||
this case we would calculate a result of approximately 18.701 (this accurately
|
||||
reflects the fact that the result is nearer to 19 than 18).
|
||||
</p>
|
||||
<p>
|
||||
By using policies we can offer any of the above as options, but that still
|
||||
leaves the question: <span class="emphasis"><em>What is actually the right thing to do?</em></span>
|
||||
</p>
|
||||
<p>
|
||||
And in particular: <span class="emphasis"><em>What policy should we use by default?</em></span>
|
||||
</p>
|
||||
<p>
|
||||
In coming to an answer we should realise that:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||||
<li class="listitem">
|
||||
Calculating an integer result is often much faster than calculating a
|
||||
real-valued result: in fact in our tests it was up to 20 times faster.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Normally people calculate quantiles so that they can perform a test of
|
||||
some kind: <span class="emphasis"><em>"If the random variable is less than N then
|
||||
we can reject our null-hypothesis with 90% confidence."</em></span>
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
So there is a genuine benefit to calculating an integer result as well as
|
||||
it being "the right thing to do" from a philosophical point of
|
||||
view. What's more if someone asks for a quantile at 0.05, then we can normally
|
||||
assume that they are asking for <span class="emphasis"><em><span class="bold"><strong>at least</strong></span>
|
||||
95% of the probability to the right of the value chosen, and <span class="bold"><strong>no
|
||||
more than</strong></span> 5% of the probability to the left of the value chosen.</em></span>
|
||||
</p>
|
||||
<p>
|
||||
In the above binomial example we would therefore round the result down to
|
||||
18.
|
||||
</p>
|
||||
<p>
|
||||
The converse applies to upper-quantiles: If the probability is greater than
|
||||
0.5 we would want to round the quantile up, <span class="emphasis"><em>so that <span class="bold"><strong>at
|
||||
least</strong></span> the requested probability is to the left of the value returned,
|
||||
and <span class="bold"><strong>no more than</strong></span> 1 - the requested probability
|
||||
is to the right of the value returned.</em></span>
|
||||
</p>
|
||||
<p>
|
||||
Likewise for two-sided intervals, we would round lower quantiles down, and
|
||||
upper quantiles up. This ensures that we have <span class="emphasis"><em>at least the requested
|
||||
probability in the central region</em></span> and <span class="emphasis"><em>no more than 1
|
||||
minus the requested probability in the tail areas.</em></span>
|
||||
</p>
|
||||
<p>
|
||||
For example, taking our 50 sample binomial distribution with a success fraction
|
||||
of 0.5, if we wanted a two sided 90% confidence interval, then we would ask
|
||||
for the 0.05 and 0.95 quantiles with the results <span class="emphasis"><em>rounded outwards</em></span>
|
||||
so that <span class="emphasis"><em>at least 90% of the probability</em></span> is in the central
|
||||
area:
|
||||
</p>
|
||||
<p>
|
||||
<span class="inlinemediaobject"><img src="../../../graphs/binomial_pdf_3.png"></span>
|
||||
</p>
|
||||
<p>
|
||||
So far so good, but there is in fact a trap waiting for the unwary here:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
returns 18 as the result, which is what we would expect from the graph above,
|
||||
and indeed there is no x greater than 18 for which:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special"><=</span> <span class="number">0.05</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
However:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
returns 31, and indeed while there is no x less than 31 for which:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">cdf</span><span class="special">(</span><span class="identifier">binomial</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="identifier">x</span><span class="special">)</span> <span class="special">>=</span> <span class="number">0.95</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
We might naively expect that for this symmetrical distribution the result
|
||||
would be 32 (since 32 = 50 - 18), but we need to remember that the cdf of
|
||||
the binomial is <span class="emphasis"><em>inclusive</em></span> of the random variable. So
|
||||
while the left tail area <span class="emphasis"><em>includes</em></span> the quantile returned,
|
||||
the right tail area always excludes an upper quantile value: since that "belongs"
|
||||
to the central area.
|
||||
</p>
|
||||
<p>
|
||||
Look at the graph above to see what's going on here: the lower quantile of
|
||||
18 belongs to the left tail, so any value <= 18 is in the left tail. The
|
||||
upper quantile of 31 on the other hand belongs to the central area, so the
|
||||
tail area actually starts at 32, so any value > 31 is in the right tail.
|
||||
</p>
|
||||
<p>
|
||||
Therefore if U and L are the upper and lower quantiles respectively, then
|
||||
a random variable X is in the tail area - where we would reject the null
|
||||
hypothesis if:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">X</span> <span class="special"><=</span> <span class="identifier">L</span> <span class="special">||</span> <span class="identifier">X</span> <span class="special">></span> <span class="identifier">U</span>
|
||||
</pre>
|
||||
<p>
|
||||
And the a variable X is inside the central region if:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">L</span> <span class="special"><</span> <span class="identifier">X</span> <span class="special"><=</span> <span class="identifier">U</span>
|
||||
</pre>
|
||||
<p>
|
||||
The moral here is to <span class="emphasis"><em>always be very careful with your comparisons
|
||||
when dealing with a discrete distribution</em></span>, and if in doubt, <span class="emphasis"><em>base
|
||||
your comparisons on CDF's instead</em></span>.
|
||||
</p>
|
||||
<h5>
|
||||
<a name="math_toolkit.pol_tutorial.understand_dis_quant.h0"></a>
|
||||
<span class="phrase"><a name="math_toolkit.pol_tutorial.understand_dis_quant.other_rounding_policies_are_avai"></a></span><a class="link" href="understand_dis_quant.html#math_toolkit.pol_tutorial.understand_dis_quant.other_rounding_policies_are_avai">Other
|
||||
Rounding Policies are Available</a>
|
||||
</h5>
|
||||
<p>
|
||||
As you would expect from a section on policies, you won't be surprised to
|
||||
know that other rounding options are available:
|
||||
</p>
|
||||
<div class="variablelist">
|
||||
<p class="title"><b></b></p>
|
||||
<dl class="variablelist">
|
||||
<dt><span class="term">integer_round_outwards</span></dt>
|
||||
<dd>
|
||||
<p>
|
||||
This is the default policy as described above: lower quantiles are
|
||||
rounded down (probability < 0.5), and upper quantiles (probability
|
||||
> 0.5) are rounded up.
|
||||
</p>
|
||||
<p>
|
||||
This gives <span class="emphasis"><em>no more than</em></span> the requested probability
|
||||
in the tails, and <span class="emphasis"><em>at least</em></span> the requested probability
|
||||
in the central area.
|
||||
</p>
|
||||
</dd>
|
||||
<dt><span class="term">integer_round_inwards</span></dt>
|
||||
<dd>
|
||||
<p>
|
||||
This is the exact opposite of the default policy: lower quantiles are
|
||||
rounded up (probability < 0.5), and upper quantiles (probability
|
||||
> 0.5) are rounded down.
|
||||
</p>
|
||||
<p>
|
||||
This gives <span class="emphasis"><em>at least</em></span> the requested probability
|
||||
in the tails, and <span class="emphasis"><em>no more than</em></span> the requested probability
|
||||
in the central area.
|
||||
</p>
|
||||
</dd>
|
||||
<dt><span class="term">integer_round_down</span></dt>
|
||||
<dd><p>
|
||||
This policy will always round the result down no matter whether it
|
||||
is an upper or lower quantile
|
||||
</p></dd>
|
||||
<dt><span class="term">integer_round_up</span></dt>
|
||||
<dd><p>
|
||||
This policy will always round the result up no matter whether it is
|
||||
an upper or lower quantile
|
||||
</p></dd>
|
||||
<dt><span class="term">integer_round_nearest</span></dt>
|
||||
<dd><p>
|
||||
This policy will always round the result to the nearest integer no
|
||||
matter whether it is an upper or lower quantile
|
||||
</p></dd>
|
||||
<dt><span class="term">real</span></dt>
|
||||
<dd><p>
|
||||
This policy will return a real valued result for the quantile of a
|
||||
discrete distribution: this is generally much slower than finding an
|
||||
integer result but does allow for more sophisticated rounding policies.
|
||||
</p></dd>
|
||||
</dl>
|
||||
</div>
|
||||
<p>
|
||||
To understand how the rounding policies for the discrete distributions can
|
||||
be used, we'll use the 50-sample binomial distribution with a success fraction
|
||||
of 0.5 once again, and calculate all the possible quantiles at 0.05 and 0.95.
|
||||
</p>
|
||||
<p>
|
||||
Begin by including the needed headers (and some using statements for conciseness):
|
||||
</p>
|
||||
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span>
|
||||
<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">left</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">fixed</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">right</span><span class="special">;</span> <span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">scientific</span><span class="special">;</span>
|
||||
<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iomanip</span><span class="special">></span>
|
||||
<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setw</span><span class="special">;</span>
|
||||
<span class="keyword">using</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">;</span>
|
||||
|
||||
<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">binomial</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
</pre>
|
||||
<p>
|
||||
Next we'll bring the needed declarations into scope, and define distribution
|
||||
types for all the available rounding policies:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="comment">// Avoid </span>
|
||||
<span class="comment">// using namespace std; // and </span>
|
||||
<span class="comment">// using namespace boost::math;</span>
|
||||
<span class="comment">// to avoid potential ambiguity of names, like binomial.</span>
|
||||
<span class="comment">// using namespace boost::math::policies; is small risk, but</span>
|
||||
<span class="comment">// the necessary items are brought into scope thus:</span>
|
||||
|
||||
<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">binomial_distribution</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">discrete_quantile</span><span class="special">;</span>
|
||||
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">integer_round_outwards</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">integer_round_down</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">integer_round_up</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">integer_round_nearest</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">integer_round_inwards</span><span class="special">;</span>
|
||||
<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">policies</span><span class="special">::</span><span class="identifier">real</span><span class="special">;</span>
|
||||
|
||||
<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">binomial_distribution</span><span class="special">;</span> <span class="comment">// Not std::binomial_distribution.</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special"><</span>
|
||||
<span class="keyword">double</span><span class="special">,</span>
|
||||
<span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_outwards</span><span class="special">></span> <span class="special">></span> <span class="special">></span>
|
||||
<span class="identifier">binom_round_outwards</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special"><</span>
|
||||
<span class="keyword">double</span><span class="special">,</span>
|
||||
<span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_inwards</span><span class="special">></span> <span class="special">></span> <span class="special">></span>
|
||||
<span class="identifier">binom_round_inwards</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special"><</span>
|
||||
<span class="keyword">double</span><span class="special">,</span>
|
||||
<span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_down</span><span class="special">></span> <span class="special">></span> <span class="special">></span>
|
||||
<span class="identifier">binom_round_down</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special"><</span>
|
||||
<span class="keyword">double</span><span class="special">,</span>
|
||||
<span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_up</span><span class="special">></span> <span class="special">></span> <span class="special">></span>
|
||||
<span class="identifier">binom_round_up</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special"><</span>
|
||||
<span class="keyword">double</span><span class="special">,</span>
|
||||
<span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">integer_round_nearest</span><span class="special">></span> <span class="special">></span> <span class="special">></span>
|
||||
<span class="identifier">binom_round_nearest</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">binomial_distribution</span><span class="special"><</span>
|
||||
<span class="keyword">double</span><span class="special">,</span>
|
||||
<span class="identifier">policy</span><span class="special"><</span><span class="identifier">discrete_quantile</span><span class="special"><</span><span class="identifier">real</span><span class="special">></span> <span class="special">></span> <span class="special">></span>
|
||||
<span class="identifier">binom_real_quantile</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
Now let's set to work calling those quantiles:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span>
|
||||
<span class="string">"Testing rounding policies for a 50 sample binomial distribution,\n"</span>
|
||||
<span class="string">"with a success fraction of 0.5.\n\n"</span>
|
||||
<span class="string">"Lower quantiles are calculated at p = 0.05\n\n"</span>
|
||||
<span class="string">"Upper quantiles at p = 0.95.\n\n"</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"Policy"</span><span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"Lower Quantile"</span> <span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"Upper Quantile"</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Test integer_round_outwards:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"integer_round_outwards"</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_outwards</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_outwards</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Test integer_round_inwards:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"integer_round_inwards"</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_inwards</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_inwards</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Test integer_round_down:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"integer_round_down"</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_down</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_down</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Test integer_round_up:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"integer_round_up"</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_up</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_up</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Test integer_round_nearest:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"integer_round_nearest"</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_nearest</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_round_nearest</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Test real:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">25</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="string">"real"</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_real_quantile</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.05</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">setw</span><span class="special">(</span><span class="number">18</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">right</span>
|
||||
<span class="special"><<</span> <span class="identifier">quantile</span><span class="special">(</span><span class="identifier">binom_real_quantile</span><span class="special">(</span><span class="number">50</span><span class="special">,</span> <span class="number">0.5</span><span class="special">),</span> <span class="number">0.95</span><span class="special">)</span>
|
||||
<span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="special">}</span> <span class="comment">// int main()</span>
|
||||
</pre>
|
||||
<p>
|
||||
Which produces the program output:
|
||||
</p>
|
||||
<pre class="programlisting"> policy_eg_10.vcxproj -> J:\Cpp\MathToolkit\test\Math_test\Release\policy_eg_10.exe
|
||||
Testing rounding policies for a 50 sample binomial distribution,
|
||||
with a success fraction of 0.5.
|
||||
|
||||
Lower quantiles are calculated at p = 0.05
|
||||
|
||||
Upper quantiles at p = 0.95.
|
||||
|
||||
Policy Lower Quantile Upper Quantile
|
||||
integer_round_outwards 18 31
|
||||
integer_round_inwards 19 30
|
||||
integer_round_down 18 30
|
||||
integer_round_up 19 31
|
||||
integer_round_nearest 19 30
|
||||
real 18.701 30.299
|
||||
</pre>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="user_def_err_pol.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="../pol_ref.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,454 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>Calling User Defined Error Handlers</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="namespace_policies.html" title="Setting Policies at Namespace or Translation Unit Scope">
|
||||
<link rel="next" href="understand_dis_quant.html" title="Understanding Quantiles of Discrete Distributions">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="namespace_policies.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="understand_dis_quant.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.user_def_err_pol"></a><a class="link" href="user_def_err_pol.html" title="Calling User Defined Error Handlers">Calling User
|
||||
Defined Error Handlers</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
Suppose we want our own user-defined error handlers rather than the any of
|
||||
the default ones supplied by the library to be used. If we set the policy
|
||||
for a specific type of error to <code class="computeroutput"><span class="identifier">user_error</span></code>
|
||||
then the library will call a user-supplied error handler. These are forward
|
||||
declared, but not defined in boost/math/policies/error_handling.hpp like
|
||||
this:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">policies</span><span class="special">{</span>
|
||||
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_pole_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_overflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_underflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_denorm_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_evaluation_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">,</span> <span class="keyword">class</span> <span class="identifier">TargetType</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_rounding_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">TargetType</span><span class="special">&</span> <span class="identifier">t</span><span class="special">);</span>
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_indeterminate_result_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
|
||||
<span class="special">}}}</span> <span class="comment">// namespaces</span>
|
||||
</pre>
|
||||
<p>
|
||||
So out first job is to include the header we want to use, and then provide
|
||||
definitions for our user-defined error handlers that we want to use. We only
|
||||
provide our special domain and pole error handlers; other errors like overflow
|
||||
and underflow use the default.
|
||||
</p>
|
||||
<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">special_functions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
|
||||
<span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">namespace</span> <span class="identifier">policies</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">)</span>
|
||||
<span class="special">{</span> <span class="comment">// Ignoring function, message and val for this example, perhaps unhelpfully.</span>
|
||||
<span class="identifier">cerr</span> <span class="special"><<</span> <span class="string">"Domain Error!"</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">quiet_NaN</span><span class="special">();</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_pole_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">)</span>
|
||||
<span class="special">{</span> <span class="comment">// Ignoring function, message and val for this example, perhaps unhelpfully.</span>
|
||||
<span class="identifier">cerr</span> <span class="special"><<</span> <span class="string">"Pole Error!"</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">quiet_NaN</span><span class="special">();</span>
|
||||
<span class="special">}</span>
|
||||
<span class="special">}</span> <span class="comment">// namespace policies</span>
|
||||
<span class="special">}}</span> <span class="comment">// namespace boost{ namespace math</span>
|
||||
</pre>
|
||||
<p>
|
||||
Now we'll need to define a suitable policy that will call these handlers,
|
||||
and define some forwarding functions that make use of the policy:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">mymath</span><span class="special">{</span>
|
||||
|
||||
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span>
|
||||
<span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">>,</span>
|
||||
<span class="identifier">pole_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">></span>
|
||||
<span class="special">></span> <span class="identifier">user_error_policy</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">user_error_policy</span><span class="special">)</span>
|
||||
|
||||
<span class="special">}</span> <span class="comment">// close unnamed namespace</span>
|
||||
</pre>
|
||||
<p>
|
||||
We now have a set of forwarding functions defined in namespace mymath that
|
||||
all look something like this:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">></span>
|
||||
<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special"><</span><span class="identifier">RT</span><span class="special">>::</span><span class="identifier">type</span>
|
||||
<span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RT</span> <span class="identifier">z</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">user_error_policy</span><span class="special">());</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
So that when we call <code class="computeroutput"><span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code>
|
||||
we really end up calling <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span>
|
||||
<span class="identifier">user_error_policy</span><span class="special">())</span></code>,
|
||||
and any errors will get directed to our own error handlers.
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of erf_inv(-10) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">mymath</span><span class="special">::</span><span class="identifier">erf_inv</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(-10) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</span><span class="special">)</span> <span class="special"><<</span> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Which outputs:
|
||||
</p>
|
||||
<pre class="programlisting"> Domain Error!
|
||||
Pole Error!
|
||||
Result of erf_inv(-10) is: 1.#QNAN
|
||||
Result of tgamma(-10) is: 1.#QNAN
|
||||
</pre>
|
||||
<p>
|
||||
The previous example was all well and good, but the custom error handlers
|
||||
didn't really do much of any use. In this example we'll implement all the
|
||||
custom handlers and show how the information provided to them can be used
|
||||
to generate nice formatted error messages.
|
||||
</p>
|
||||
<p>
|
||||
Each error handler has the general form:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_</span><span class="emphasis"><em>error_type</em></span><span class="special">(</span>
|
||||
<span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span>
|
||||
<span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
</pre>
|
||||
<p>
|
||||
and accepts three arguments:
|
||||
</p>
|
||||
<div class="variablelist">
|
||||
<p class="title"><b></b></p>
|
||||
<dl class="variablelist">
|
||||
<dt><span class="term">const char* function</span></dt>
|
||||
<dd><p>
|
||||
The name of the function that raised the error, this string contains
|
||||
one or more %1% format specifiers that should be replaced by the name
|
||||
of real type T, like float or double.
|
||||
</p></dd>
|
||||
<dt><span class="term">const char* message</span></dt>
|
||||
<dd><p>
|
||||
A message associated with the error, normally this contains a %1% format
|
||||
specifier that should be replaced with the value of <span class="emphasis"><em>value</em></span>:
|
||||
however note that overflow and underflow messages do not contain this
|
||||
%1% specifier (since the value of <span class="emphasis"><em>value</em></span> is immaterial
|
||||
in these cases).
|
||||
</p></dd>
|
||||
<dt><span class="term">const T& value</span></dt>
|
||||
<dd><p>
|
||||
The value that caused the error: either an argument to the function
|
||||
if this is a domain or pole error, the tentative result if this is
|
||||
a denorm or evaluation error, or zero or infinity for underflow or
|
||||
overflow errors.
|
||||
</p></dd>
|
||||
</dl>
|
||||
</div>
|
||||
<p>
|
||||
As before we'll include the headers we need first:
|
||||
</p>
|
||||
<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">special_functions</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">></span>
|
||||
</pre>
|
||||
<p>
|
||||
Next we'll implement our own error handlers for each type of error, starting
|
||||
with domain errors:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
|
||||
<span class="keyword">namespace</span> <span class="identifier">policies</span>
|
||||
<span class="special">{</span>
|
||||
|
||||
<span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
</pre>
|
||||
<p>
|
||||
We'll begin with a bit of defensive programming in case function or message
|
||||
are empty:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">message</span> <span class="special">=</span> <span class="string">"Cause unknown with bad argument %1%"</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
Next we'll format the name of the function with the name of type T, perhaps
|
||||
double:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
|
||||
</pre>
|
||||
<p>
|
||||
Then likewise format the error message with the value of parameter <span class="emphasis"><em>val</em></span>,
|
||||
making sure we output all the potentially significant digits of <span class="emphasis"><em>val</em></span>:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
|
||||
<span class="keyword">int</span> <span class="identifier">prec</span> <span class="special">=</span> <span class="number">2</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">digits</span> <span class="special">*</span> <span class="number">30103UL</span><span class="special">)</span> <span class="special">/</span> <span class="number">100000UL</span><span class="special">;</span>
|
||||
<span class="comment">// int prec = std::numeric_limits<T>::max_digits10; // For C++0X Standard Library</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">message</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">io</span><span class="special">::</span><span class="identifier">group</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">prec</span><span class="special">),</span> <span class="identifier">val</span><span class="special">)).</span><span class="identifier">str</span><span class="special">();</span>
|
||||
</pre>
|
||||
<p>
|
||||
Now we just have to do something with the message, we could throw an exception,
|
||||
but for the purposes of this example we'll just dump the message to std::cerr:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="identifier">msg</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
</pre>
|
||||
<p>
|
||||
Finally the only sensible value we can return from a domain error is a NaN:
|
||||
</p>
|
||||
<pre class="programlisting"> <span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">quiet_NaN</span><span class="special">();</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Pole errors are essentially a special case of domain errors, so in this example
|
||||
we'll just return the result of a domain error:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_pole_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">return</span> <span class="identifier">user_domain_error</span><span class="special">(</span><span class="identifier">function</span><span class="special">,</span> <span class="identifier">message</span><span class="special">,</span> <span class="identifier">val</span><span class="special">);</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Overflow errors are very similar to domain errors, except that there's no
|
||||
%1% format specifier in the <span class="emphasis"><em>message</em></span> parameter:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_overflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">message</span> <span class="special">=</span> <span class="string">"Result of function is too large to represent"</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
|
||||
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="identifier">message</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="identifier">msg</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Value passed to the function is an infinity, just return it:</span>
|
||||
<span class="keyword">return</span> <span class="identifier">val</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Underflow errors are much the same as overflow:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_underflow_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">message</span> <span class="special">=</span> <span class="string">"Result of function is too small to represent"</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
|
||||
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="identifier">message</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="identifier">msg</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Value passed to the function is zero, just return it:</span>
|
||||
<span class="keyword">return</span> <span class="identifier">val</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Denormalised results are much the same as underflow:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_denorm_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">message</span> <span class="special">=</span> <span class="string">"Result of function is denormalised"</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
|
||||
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="identifier">message</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="identifier">msg</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// Value passed to the function is denormalised, just return it:</span>
|
||||
<span class="keyword">return</span> <span class="identifier">val</span><span class="special">;</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
Which leaves us with evaluation errors: these occur when an internal error
|
||||
occurs that prevents the function being fully evaluated. The parameter <span class="emphasis"><em>val</em></span>
|
||||
contains the closest approximation to the result found so far:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">T</span><span class="special">></span>
|
||||
<span class="identifier">T</span> <span class="identifier">user_evaluation_error</span><span class="special">(</span><span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">function</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span><span class="special">*</span> <span class="identifier">message</span><span class="special">,</span> <span class="keyword">const</span> <span class="identifier">T</span><span class="special">&</span> <span class="identifier">val</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">function</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">function</span> <span class="special">=</span> <span class="string">"Unknown function with arguments of type %1%"</span><span class="special">;</span>
|
||||
<span class="keyword">if</span><span class="special">(</span><span class="identifier">message</span> <span class="special">==</span> <span class="number">0</span><span class="special">)</span>
|
||||
<span class="identifier">message</span> <span class="special">=</span> <span class="string">"An internal evaluation error occurred with "</span>
|
||||
<span class="string">"the best value calculated so far of %1%"</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">string</span> <span class="identifier">msg</span><span class="special">(</span><span class="string">"Error in function "</span><span class="special">);</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">function</span><span class="special">)</span> <span class="special">%</span> <span class="keyword">typeid</span><span class="special">(</span><span class="identifier">T</span><span class="special">).</span><span class="identifier">name</span><span class="special">()).</span><span class="identifier">str</span><span class="special">();</span>
|
||||
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="string">": \n"</span><span class="special">;</span>
|
||||
<span class="keyword">int</span> <span class="identifier">prec</span> <span class="special">=</span> <span class="number">2</span> <span class="special">+</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">digits</span> <span class="special">*</span> <span class="number">30103UL</span><span class="special">)</span> <span class="special">/</span> <span class="number">100000UL</span><span class="special">;</span>
|
||||
<span class="comment">// int prec = std::numeric_limits<T>::max_digits10; // For C++0X Standard Library</span>
|
||||
<span class="identifier">msg</span> <span class="special">+=</span> <span class="special">(</span><span class="identifier">boost</span><span class="special">::</span><span class="identifier">format</span><span class="special">(</span><span class="identifier">message</span><span class="special">)</span> <span class="special">%</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">io</span><span class="special">::</span><span class="identifier">group</span><span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">setprecision</span><span class="special">(</span><span class="identifier">prec</span><span class="special">),</span> <span class="identifier">val</span><span class="special">)).</span><span class="identifier">str</span><span class="special">();</span>
|
||||
|
||||
<span class="identifier">std</span><span class="special">::</span><span class="identifier">cerr</span> <span class="special"><<</span> <span class="identifier">msg</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
|
||||
|
||||
<span class="comment">// What do we return here? This is generally a fatal error, that should never occur,</span>
|
||||
<span class="comment">// so we just return a NaN for the purposes of the example:</span>
|
||||
<span class="keyword">return</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>::</span><span class="identifier">quiet_NaN</span><span class="special">();</span>
|
||||
<span class="special">}</span>
|
||||
|
||||
<span class="special">}</span> <span class="comment">// policies</span>
|
||||
<span class="special">}}</span> <span class="comment">// boost::math</span>
|
||||
</pre>
|
||||
<p>
|
||||
Now we'll need to define a suitable policy that will call these handlers,
|
||||
and define some forwarding functions that make use of the policy:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">mymath</span>
|
||||
<span class="special">{</span> <span class="comment">// unnamed.</span>
|
||||
|
||||
<span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
|
||||
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span>
|
||||
<span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">>,</span>
|
||||
<span class="identifier">pole_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">>,</span>
|
||||
<span class="identifier">overflow_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">>,</span>
|
||||
<span class="identifier">underflow_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">>,</span>
|
||||
<span class="identifier">denorm_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">>,</span>
|
||||
<span class="identifier">evaluation_error</span><span class="special"><</span><span class="identifier">user_error</span><span class="special">></span>
|
||||
<span class="special">></span> <span class="identifier">user_error_policy</span><span class="special">;</span>
|
||||
|
||||
<span class="identifier">BOOST_MATH_DECLARE_SPECIAL_FUNCTIONS</span><span class="special">(</span><span class="identifier">user_error_policy</span><span class="special">)</span>
|
||||
|
||||
<span class="special">}</span> <span class="comment">// unnamed namespace</span>
|
||||
</pre>
|
||||
<p>
|
||||
We now have a set of forwarding functions, defined in namespace mymath, that
|
||||
all look something like this:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">template</span> <span class="special"><</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">></span>
|
||||
<span class="keyword">inline</span> <span class="keyword">typename</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tools</span><span class="special">::</span><span class="identifier">promote_args</span><span class="special"><</span><span class="identifier">RT</span><span class="special">>::</span><span class="identifier">type</span>
|
||||
<span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">RT</span> <span class="identifier">z</span><span class="special">)</span>
|
||||
<span class="special">{</span>
|
||||
<span class="keyword">return</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span> <span class="identifier">user_error_policy</span><span class="special">());</span>
|
||||
<span class="special">}</span>
|
||||
</pre>
|
||||
<p>
|
||||
So that when we call <code class="computeroutput"><span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">)</span></code>
|
||||
we really end up calling <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="identifier">z</span><span class="special">,</span>
|
||||
<span class="identifier">user_error_policy</span><span class="special">())</span></code>,
|
||||
and any errors will get directed to our own error handlers:
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">int</span> <span class="identifier">main</span><span class="special">()</span>
|
||||
<span class="special">{</span>
|
||||
<span class="comment">// Raise a domain error:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of erf_inv(-10) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">mymath</span><span class="special">::</span><span class="identifier">erf_inv</span><span class="special">(-</span><span class="number">10</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> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="comment">// Raise a pole error:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(-10) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">10</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> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="comment">// Raise an overflow error:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(3000) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(</span><span class="number">3000</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> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="comment">// Raise an underflow error:</span>
|
||||
<span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"Result of tgamma(-190.5) is: "</span>
|
||||
<span class="special"><<</span> <span class="identifier">mymath</span><span class="special">::</span><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">190.5</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> <span class="identifier">endl</span><span class="special">;</span>
|
||||
<span class="comment">// Unfortunately we can't predicably raise a denormalised</span>
|
||||
<span class="comment">// result, nor can we raise an evaluation error in this example</span>
|
||||
<span class="comment">// since these should never really occur!</span>
|
||||
<span class="special">}</span> <span class="comment">// int main()</span>
|
||||
</pre>
|
||||
<p>
|
||||
Which outputs:
|
||||
</p>
|
||||
<pre class="programlisting">Error in function boost::math::erf_inv<double>(double, double):
|
||||
Argument outside range [-1, 1] in inverse erf function (got p=-10).
|
||||
Result of erf_inv(-10) is: 1.#QNAN
|
||||
|
||||
Error in function boost::math::tgamma<long double>(long double):
|
||||
Evaluation of tgamma at a negative integer -10.
|
||||
Result of tgamma(-10) is: 1.#QNAN
|
||||
|
||||
Error in function boost::math::tgamma<long double>(long double):
|
||||
Result of tgamma is too large to represent.
|
||||
Error in function boost::math::tgamma<double>(double):
|
||||
Result of function is too large to represent
|
||||
Result of tgamma(3000) is: 1.#INF
|
||||
|
||||
Error in function boost::math::tgamma<long double>(long double):
|
||||
Result of tgamma is too large to represent.
|
||||
Error in function boost::math::tgamma<long double>(long double):
|
||||
Result of tgamma is too small to represent.
|
||||
Result of tgamma(-190.5) is: 0
|
||||
</pre>
|
||||
<p>
|
||||
Notice how some of the calls result in an error handler being called more
|
||||
than once, or for more than one handler to be called: this is an artefact
|
||||
of the fact that many functions are implemented in terms of one or more sub-routines
|
||||
each of which may have it's own error handling. For example <code class="computeroutput"><span class="identifier">tgamma</span><span class="special">(-</span><span class="number">190.5</span><span class="special">)</span></code> is implemented
|
||||
in terms of <code class="computeroutput"><span class="identifier">tgamma</span><span class="special">(</span><span class="number">190.5</span><span class="special">)</span></code> - which
|
||||
overflows - the reflection formula for <code class="computeroutput"><span class="identifier">tgamma</span></code>
|
||||
then notices that it is dividing by infinity and so underflows.
|
||||
</p>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="namespace_policies.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="understand_dis_quant.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
@@ -0,0 +1,88 @@
|
||||
<html>
|
||||
<head>
|
||||
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
|
||||
<title>So Just What is a Policy Anyway?</title>
|
||||
<link rel="stylesheet" href="../../math.css" type="text/css">
|
||||
<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
|
||||
<link rel="home" href="../../index.html" title="Math Toolkit 2.1.0">
|
||||
<link rel="up" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="prev" href="../pol_tutorial.html" title="Policy Tutorial">
|
||||
<link rel="next" href="policy_tut_defaults.html" title="Policies Have Sensible Defaults">
|
||||
</head>
|
||||
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
|
||||
<table cellpadding="2" width="100%"><tr>
|
||||
<td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../../boost.png"></td>
|
||||
<td align="center"><a href="../../../../../../index.html">Home</a></td>
|
||||
<td align="center"><a href="../../../../../../libs/libraries.htm">Libraries</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
|
||||
<td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
|
||||
<td align="center"><a href="../../../../../../more/index.htm">More</a></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="../pol_tutorial.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="policy_tut_defaults.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
<div class="section">
|
||||
<div class="titlepage"><div><div><h3 class="title">
|
||||
<a name="math_toolkit.pol_tutorial.what_is_a_policy"></a><a class="link" href="what_is_a_policy.html" title="So Just What is a Policy Anyway?">So Just What
|
||||
is a Policy Anyway?</a>
|
||||
</h3></div></div></div>
|
||||
<p>
|
||||
A policy is a compile-time mechanism for customising the behaviour of a special
|
||||
function, or a statistical distribution. With Policies you can control:
|
||||
</p>
|
||||
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
|
||||
<li class="listitem">
|
||||
What action to take when an error occurs.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
What happens when you call a function that is mathematically undefined
|
||||
(for example, if you ask for the mean of a Cauchy distribution).
|
||||
</li>
|
||||
<li class="listitem">
|
||||
What happens when you ask for a quantile of a discrete distribution.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
Whether the library is allowed to internally promote <code class="computeroutput"><span class="keyword">float</span></code>
|
||||
to <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">double</span></code> to <code class="computeroutput"><span class="keyword">long</span>
|
||||
<span class="keyword">double</span></code> in order to improve precision.
|
||||
</li>
|
||||
<li class="listitem">
|
||||
What precision to use when calculating the result.
|
||||
</li>
|
||||
</ul></div>
|
||||
<p>
|
||||
Some of these policies could arguably be runtime variables, but then we couldn't
|
||||
use compile-time dispatch internally to select the best evaluation method
|
||||
for the given policies.
|
||||
</p>
|
||||
<p>
|
||||
For this reason a Policy is a <span class="emphasis"><em>type</em></span>: in fact it's an
|
||||
instance of the class template <code class="computeroutput"><span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">::</span><span class="identifier">policy</span><span class="special"><></span></code>. This class is just a compile-time-container
|
||||
of user-selected policies (sometimes called a type-list):
|
||||
</p>
|
||||
<pre class="programlisting"><span class="keyword">using</span> <span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">policies</span><span class="special">;</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="comment">// Define a policy that sets ::errno on overflow, and does</span>
|
||||
<span class="comment">// not promote double to long double internally:</span>
|
||||
<span class="comment">//</span>
|
||||
<span class="keyword">typedef</span> <span class="identifier">policy</span><span class="special"><</span><span class="identifier">domain_error</span><span class="special"><</span><span class="identifier">errno_on_error</span><span class="special">>,</span> <span class="identifier">promote_double</span><span class="special"><</span><span class="keyword">false</span><span class="special">></span> <span class="special">></span> <span class="identifier">mypolicy</span><span class="special">;</span>
|
||||
</pre>
|
||||
</div>
|
||||
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
|
||||
<td align="left"></td>
|
||||
<td align="right"><div class="copyright-footer">Copyright © 2006-2010, 2012-2014 Nikhar Agrawal,
|
||||
Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
|
||||
Holin, Bruno Lalande, John Maddock, Johan Råde, Gautam Sewani, Benjamin Sobotta,
|
||||
Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
|
||||
Distributed under the Boost Software License, Version 1.0. (See accompanying
|
||||
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>)
|
||||
</p>
|
||||
</div></td>
|
||||
</tr></table>
|
||||
<hr>
|
||||
<div class="spirit-nav">
|
||||
<a accesskey="p" href="../pol_tutorial.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="policy_tut_defaults.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a>
|
||||
</div>
|
||||
</body>
|
||||
</html>
|
||||
Reference in New Issue
Block a user