diff options
Diffstat (limited to 'libs/math/doc/sf_and_dist/html/math_toolkit/constants/tutorial/user_def.html')
| -rw-r--r-- | libs/math/doc/sf_and_dist/html/math_toolkit/constants/tutorial/user_def.html | 313 |
1 files changed, 313 insertions, 0 deletions
diff --git a/libs/math/doc/sf_and_dist/html/math_toolkit/constants/tutorial/user_def.html b/libs/math/doc/sf_and_dist/html/math_toolkit/constants/tutorial/user_def.html new file mode 100644 index 0000000000..b4a3f60a8e --- /dev/null +++ b/libs/math/doc/sf_and_dist/html/math_toolkit/constants/tutorial/user_def.html @@ -0,0 +1,313 @@ +<html> +<head> +<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> +<title>Use With User Defined Types</title> +<link rel="stylesheet" href="../../../../../../../../doc/src/boostbook.css" type="text/css"> +<meta name="generator" content="DocBook XSL Stylesheets V1.76.1"> +<link rel="home" href="../../../index.html" title="Math Toolkit"> +<link rel="up" href="../tutorial.html" title="Tutorial"> +<link rel="prev" href="templ.html" title="Use in template code"> +<link rel="next" href="../constants.html" title="The Mathematical Constants"> +</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="templ.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../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="../constants.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +<div class="section math_toolkit_constants_tutorial_user_def"> +<div class="titlepage"><div><div><h4 class="title"> +<a name="math_toolkit.constants.tutorial.user_def"></a><a class="link" href="user_def.html" title="Use With User Defined Types">Use With + User Defined Types</a> +</h4></div></div></div> +<p> + The syntax for using the function-call constants with user-defined types + is the same as it is in the template class, which is to say we use: + </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">constants</span><span class="special">.</span><span class="identifier">hpp</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">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special"><</span><span class="identifier">UserDefinedType</span><span class="special">>();</span> +</pre> +<p> + However, since the precision of the user-defined type may be much greater + than that of the built-in floating pointer types, how the value returned + is created is as follows: + </p> +<div class="itemizedlist"><ul class="itemizedlist" type="disc"> +<li class="listitem"> + If the precision of the type is known at compile time: + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + If the precision is less than or equal to that of a <code class="computeroutput"><span class="keyword">float</span></code> and the type is constructable + from a <code class="computeroutput"><span class="keyword">float</span></code> then + our code returns a <code class="computeroutput"><span class="keyword">float</span></code> + literal. If the user-defined type is a literal type then the + function call that returns the constant will be a <code class="computeroutput"><span class="identifier">constexp</span></code>. + </li> +<li class="listitem"> + If the precision is less than or equal to that of a <code class="computeroutput"><span class="keyword">double</span></code> and the type is constructable + from a <code class="computeroutput"><span class="keyword">double</span></code> then + our code returns a <code class="computeroutput"><span class="keyword">double</span></code> + literal. If the user-defined type is a literal type then the + function call that returns the constant will be a <code class="computeroutput"><span class="identifier">constexp</span></code>. + </li> +<li class="listitem"> + If the precision is less than or equal to that of a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code> + and the type is constructable from a <code class="computeroutput"><span class="keyword">long</span> + <span class="keyword">double</span></code> then our code returns + a <code class="computeroutput"><span class="keyword">long</span> <span class="keyword">double</span></code> + literal. If the user-defined type is a literal type then the + function call that returns the constant will be a <code class="computeroutput"><span class="identifier">constexp</span></code>. + </li> +<li class="listitem"> + If the precision is less than 100 decimal digits, then the constant + will be constructed (just the once, then cached in a thread-safe + manner) from a string representation of the constant. + </li> +<li class="listitem"> + Otherwise the value is computed (just once, then cached in a + thread-safe manner). + </li> +</ul></div> + </li> +<li class="listitem"> + If the precision is unknown at compile time then: + <div class="itemizedlist"><ul class="itemizedlist" type="circle"> +<li class="listitem"> + If the runtime precision (obtained from a call to <code class="computeroutput"><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">digits</span><span class="special"><</span><span class="identifier">T</span><span class="special">>()</span></code>) + is less than 100 decimal digits, then the constant is constructed + "on the fly" from the string representation of the + constant. + </li> +<li class="listitem"> + Otherwise the value is constructed "on the fly" by + calculating then value of the constant using the current default + precision of the type. Note that this can make use of the constants + rather expensive. + </li> +</ul></div> + </li> +</ul></div> +<p> + In addition, it is possible to pass a <code class="computeroutput"><span class="identifier">Policy</span></code> + type as a second template argument, and use this to control the precision: + </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">constants</span><span class="special">/</span><span class="identifier">constants</span><span class="special">.</span><span class="identifier">hpp</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">policies</span><span class="special">::</span><span class="identifier">policy</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">policies</span><span class="special">::</span><span class="identifier">digits2</span><span class="special"><</span><span class="number">80</span><span class="special">></span> <span class="special">></span> <span class="identifier">my_policy_type</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">constants</span><span class="special">::</span><span class="identifier">pi</span><span class="special"><</span><span class="identifier">MyType</span><span class="special">,</span> <span class="identifier">my_policy_type</span><span class="special">>();</span> +</pre> +<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> + Boost.Math doesn't know how to control the internal precision of <code class="computeroutput"><span class="identifier">MyType</span></code>, the policy just controls how + the selection process above is carried out, and the calculation precision + if the result is computed. + </p></td></tr> +</table></div> +<p> + It is also possible to control which method is used to construct the constant + by specialising the traits class <code class="computeroutput"><span class="identifier">construction_traits</span></code>: + </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">constant</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">Policy</span><span class="special">></span> +<span class="keyword">struct</span> <span class="identifier">construction_traits</span> +<span class="special">{</span> + <span class="keyword">typedef</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">int_</span><span class="special"><</span><span class="identifier">N</span><span class="special">></span> <span class="identifier">type</span><span class="special">;</span> +<span class="special">};</span> + +<span class="special">}}}</span> <span class="comment">// namespaces</span> +</pre> +<p> + Where <span class="emphasis"><em>N</em></span> takes one of the following values: + </p> +<div class="informaltable"><table class="table"> +<colgroup> +<col> +<col> +</colgroup> +<thead><tr> +<th> + <p> + <span class="emphasis"><em>N</em></span> + </p> + </th> +<th> + <p> + Meaning + </p> + </th> +</tr></thead> +<tbody> +<tr> +<td> + <p> + 0 + </p> + </td> +<td> + <p> + The precision is unavailable at compile time; either construct + from a decimal digit string or calculate on the fly depending + upon the runtime precision. + </p> + </td> +</tr> +<tr> +<td> + <p> + 1 + </p> + </td> +<td> + <p> + Return a float precision constant. + </p> + </td> +</tr> +<tr> +<td> + <p> + 2 + </p> + </td> +<td> + <p> + Return a double precision constant. + </p> + </td> +</tr> +<tr> +<td> + <p> + 3 + </p> + </td> +<td> + <p> + Return a long double precision constant. + </p> + </td> +</tr> +<tr> +<td> + <p> + 4 + </p> + </td> +<td> + <p> + Construct the result from the string representation, and cache + the result. + </p> + </td> +</tr> +<tr> +<td> + <p> + Any other value <span class="emphasis"><em>N</em></span> + </p> + </td> +<td> + <p> + Sets the compile time precision to <span class="emphasis"><em>N</em></span> bits. + </p> + </td> +</tr> +</tbody> +</table></div> +<h6> +<a name="math_toolkit.constants.tutorial.user_def.h0"></a> + <span><a name="math_toolkit.constants.tutorial.user_def.custom_specializing_a_constant"></a></span><a class="link" href="user_def.html#math_toolkit.constants.tutorial.user_def.custom_specializing_a_constant">Custom + Specializing a constant</a> + </h6> +<p> + In addition, for user-defined types that need special handling, it's possible + to [partially-] specialize the internal structure used by each constant. + For example, suppose we're using the C++ wrapper around MPFR <code class="computeroutput"><span class="identifier">mpfr_class</span></code>: this has its own representation + of Pi which we may well wish to use in place of the above mechanism. We + can achieve this by specialising 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">constants</span><span class="special">::</span><span class="identifier">detail</span><span class="special">::</span><span class="identifier">constant_pi</span></code>: + </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">constants</span><span class="special">{</span> <span class="keyword">namespace</span> <span class="identifier">detail</span><span class="special">{</span> + +<span class="keyword">template</span><span class="special"><></span> +<span class="keyword">struct</span> <span class="identifier">constant_pi</span><span class="special"><</span><span class="identifier">mpfr_class</span><span class="special">></span> +<span class="special">{</span> + <span class="keyword">template</span><span class="special"><</span><span class="keyword">int</span> <span class="identifier">N</span><span class="special">></span> + <span class="keyword">inline</span> <span class="identifier">T</span> <span class="identifier">get</span><span class="special">(</span><span class="keyword">const</span> <span class="identifier">mpl</span><span class="special">::</span><span class="identifier">int_</span><span class="special"><</span><span class="identifier">N</span><span class="special">>&)</span> + <span class="special">{</span> + <span class="comment">// The template param N is one of the values in the table above,</span> + <span class="comment">// we can either handle all cases in one as is the case here,</span> + <span class="comment">// or overload "get" for the different options.</span> + <span class="identifier">mpfr_class</span> <span class="identifier">result</span><span class="special">;</span> + <span class="identifier">mpfr_const_pi</span><span class="special">(</span><span class="identifier">result</span><span class="special">.</span><span class="identifier">get_mpfr_t</span><span class="special">(),</span> <span class="identifier">GMP_RNDN</span><span class="special">);</span> + <span class="keyword">return</span> <span class="identifier">result</span><span class="special">;</span> + <span class="special">}</span> +<span class="special">};</span> + +<span class="special">}}}}</span> <span class="comment">// namespaces</span> +</pre> +<h6> +<a name="math_toolkit.constants.tutorial.user_def.h1"></a> + <span><a name="math_toolkit.constants.tutorial.user_def.diagnosing_what_meta_programmed_code_is_doing"></a></span><a class="link" href="user_def.html#math_toolkit.constants.tutorial.user_def.diagnosing_what_meta_programmed_code_is_doing">Diagnosing + what meta-programmed code is doing</a> + </h6> +<p> + Finally, since it can be tricky to diagnose what meta-programmed code is + doing, there is a diagnostic routine that prints information about how + this library will handle a specific type, it can be used like this: + </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">constants</span><span class="special">/</span><span class="identifier">info</span><span class="special">.</span><span class="identifier">hpp</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="identifier">boost</span><span class="special">::</span><span class="identifier">math</span><span class="special">::</span><span class="identifier">constants</span><span class="special">::</span><span class="identifier">print_info_on_type</span><span class="special"><</span><span class="identifier">MyType</span><span class="special">>();</span> +<span class="special">}</span> +</pre> +<p> + If you wish, you can also pass an optional std::ostream argument to the + <code class="computeroutput"><span class="identifier">print_info_on_type</span></code> function. + Typical output for a user-defined type looks like this: + </p> +<pre class="programlisting">Information on the Implementation and Handling of +Mathematical Constants for Type class boost::math::concepts::real_concept + +Checking for std::numeric_limits<class boost::math::concepts::real_concept> specialisation: no +boost::math::policies::precision<class boost::math::concepts::real_concept, Policy> +reports that there is no compile type precision available. +boost::math::tools::digits<class boost::math::concepts::real_concept>() +reports that the current runtime precision is +53 binary digits. +No compile time precision is available, the construction method +will be decided at runtime and results will not be cached +- this may lead to poor runtime performance. +Current runtime precision indicates that +the constant will be constructed from a string on each call. +</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 John Maddock, Paul A. Bristow, Hubert Holin, Xiaogang Zhang, Bruno + Lalande, Johan Råde, Gautam Sewani, Thijs van den Berg and Benjamin Sobotta<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="templ.html"><img src="../../../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../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="../constants.html"><img src="../../../../../../../../doc/src/images/next.png" alt="Next"></a> +</div> +</body> +</html> |