libs/math/doc/html/math_toolkit/archetypes.html

   1 <html>
   2 <head>
   3 <meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
   4 <title>Conceptual Archetypes for Reals and Distributions</title>
   5 <link rel="stylesheet" href="../math.css" type="text/css">
   6 <meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
   7 <link rel="home" href="../index.html" title="Math Toolkit 2.5.2">
   8 <link rel="up" href="../using_udt.html" title="Chapter&#160;14.&#160;Use with User-Defined Floating-Point Types - Boost.Multiprecision and others">
   9 <link rel="prev" href="dist_concept.html" title="Conceptual Requirements for Distribution Types">
  10 <link rel="next" href="../policy.html" title="Chapter&#160;15.&#160;Policies: Controlling Precision, Error Handling etc">
  11 </head>
  12 <body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
  13 <table cellpadding="2" width="100%"><tr>
  14 <td valign="top"><img alt="Boost C++ Libraries" width="277" height="86" src="../../../../../boost.png"></td>
  15 <td align="center"><a href="../../../../../index.html">Home</a></td>
  16 <td align="center"><a href="../../../../../libs/libraries.htm">Libraries</a></td>
  17 <td align="center"><a href="http://www.boost.org/users/people.html">People</a></td>
  18 <td align="center"><a href="http://www.boost.org/users/faq.html">FAQ</a></td>
  19 <td align="center"><a href="../../../../../more/index.htm">More</a></td>
  20 </tr></table>
  21 <hr>
  22 <div class="spirit-nav">
  23 <a accesskey="p" href="dist_concept.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.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.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
  24 </div>
  25 <div class="section">
  26 <div class="titlepage"><div><div><h2 class="title" style="clear: both">
  27 <a name="math_toolkit.archetypes"></a><a class="link" href="archetypes.html" title="Conceptual Archetypes for Reals and Distributions">Conceptual Archetypes for Reals
  28     and Distributions</a>
  29 </h2></div></div></div>
  30 <p>
  31       There are a few concept archetypes available:
  32     </p>
  33 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
  34 <li class="listitem">
  35           Real concept for floating-point types.
  36         </li>
  37 <li class="listitem">
  38           Distribution concept for statistical distributions.
  39         </li>
  40 </ul></div>
  41 <h6>
  42 <a name="math_toolkit.archetypes.h0"></a>
  43       <span class="phrase"><a name="math_toolkit.archetypes.real_concept"></a></span><a class="link" href="archetypes.html#math_toolkit.archetypes.real_concept">Real
  44       concept</a>
  45     </h6>
  46 <p>
  47       <code class="computeroutput"><span class="identifier">std_real_concept</span></code> is an archetype
  48       for theReal types, including the built-in float, double, long double.
  49     </p>
  50 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">concepts</span><span class="special">/</span><span class="identifier">std_real_concept</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
  51 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span>
  52 <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
  53 <span class="keyword">namespace</span> <span class="identifier">concepts</span>
  54 <span class="special">{</span>
  55   <span class="keyword">class</span> <span class="identifier">std_real_concept</span><span class="special">;</span>
  56 <span class="special">}</span>
  57 <span class="special">}}</span> <span class="comment">// namespaces</span>
  58 </pre>
  59 <p>
  60       The main purpose in providing this type is to verify that standard library
  61       functions are found via a using declaration - bringing those functions into
  62       the current scope - and not just because they happen to be in global scope.
  63     </p>
  64 <p>
  65       In order to ensure that a call to say <code class="computeroutput"><span class="identifier">pow</span></code>
  66       can be found either via argument dependent lookup, or failing that then in
  67       the std namespace: all calls to standard library functions are unqualified,
  68       with the std:: versions found via a <code class="computeroutput"><span class="keyword">using</span></code>
  69       declaration to make them visible in the current scope. Unfortunately it's all
  70       to easy to forget the <code class="computeroutput"><span class="keyword">using</span></code> declaration,
  71       and call the double version of the function that happens to be in the global
  72       scope by mistake.
  73     </p>
  74 <p>
  75       For example if the code calls ::pow rather than std::pow, the code will cleanly
  76       compile, but truncation of long doubles to double will cause a significant
  77       loss of precision. In contrast a template instantiated with std_real_concept
  78       will <span class="bold"><strong>only</strong></span> compile if the all the standard
  79       library functions used have been brought into the current scope with a using
  80       declaration.
  81     </p>
  82 <h3>
  83 <a name="math_toolkit.archetypes.h1"></a>
  84       <span class="phrase"><a name="math_toolkit.archetypes.testing_the_real_concept"></a></span><a class="link" href="archetypes.html#math_toolkit.archetypes.testing_the_real_concept">Testing
  85       the real concept</a>
  86     </h3>
  87 <p>
  88       There is a test program <a href="../../../test/std_real_concept_check.cpp" target="_top">libs/math/test/std_real_concept_check.cpp</a>
  89       that instantiates every template in this library with type <code class="computeroutput"><span class="identifier">std_real_concept</span></code>
  90       to verify its usage of standard library functions.
  91     </p>
  92 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">concepts</span><span class="special">/</span><span class="identifier">real_concept</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
  93 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span>
  94 <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
  95 <span class="keyword">namespace</span> <span class="identifier">concepts</span><span class="special">{</span>
  96
  97 <span class="keyword">class</span> <span class="identifier">real_concept</span><span class="special">;</span>
  98
  99 <span class="special">}}}</span> <span class="comment">// namespaces</span>
 100 </pre>
 101 <p>
 102       <code class="computeroutput"><span class="identifier">real_concept</span></code> is an archetype
 103       for <a class="link" href="real_concepts.html" title="Conceptual Requirements for Real Number Types">user defined real types</a>,
 104       it declares its standard library functions in its own namespace: these will
 105       only be found if they are called unqualified allowing argument dependent lookup
 106       to locate them. In addition this type is useable at runtime: this allows code
 107       that would not otherwise be exercised by the built-in floating point types
 108       to be tested. There is no std::numeric_limits&lt;&gt; support for this type,
 109       since numeric_limits is not a conceptual requirement for <a class="link" href="real_concepts.html" title="Conceptual Requirements for Real Number Types">RealType</a>s.
 110     </p>
 111 <p>
 112       NTL RR is an example of a type meeting the requirements that this type models,
 113       but note that use of a thin wrapper class is required: refer to <a class="link" href="high_precision/use_ntl.html" title="Using NTL Library">"Using
 114       With NTL - a High-Precision Floating-Point Library"</a>.
 115     </p>
 116 <p>
 117       There is no specific test case for type <code class="computeroutput"><span class="identifier">real_concept</span></code>,
 118       instead, since this type is usable at runtime, each individual test case as
 119       well as testing <code class="computeroutput"><span class="keyword">float</span></code>, <code class="computeroutput"><span class="keyword">double</span></code> and <code class="computeroutput"><span class="keyword">long</span>
 120       <span class="keyword">double</span></code>, also tests <code class="computeroutput"><span class="identifier">real_concept</span></code>.
 121     </p>
 122 <h3>
 123 <a name="math_toolkit.archetypes.h2"></a>
 124       <span class="phrase"><a name="math_toolkit.archetypes.distribution_concept"></a></span><a class="link" href="archetypes.html#math_toolkit.archetypes.distribution_concept">Distribution
 125       Concept</a>
 126     </h3>
 127 <p>
 128       Distribution Concept models statistical distributions.
 129     </p>
 130 <pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">math</span><span class="special">/</span><span class="identifier">concepts</span><span class="special">/</span><span class="identifier">distribution</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span></pre>
 131 <pre class="programlisting"><span class="keyword">namespace</span> <span class="identifier">boost</span><span class="special">{</span>
 132 <span class="keyword">namespace</span> <span class="identifier">math</span><span class="special">{</span>
 133 <span class="keyword">namespace</span> <span class="identifier">concepts</span>
 134 <span class="special">{</span>
 135   <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">RealType</span><span class="special">&gt;</span>
 136   <span class="keyword">class</span> <span class="identifier">distribution_archetype</span><span class="special">;</span>
 137
 138   <span class="keyword">template</span> <span class="special">&lt;</span><span class="keyword">class</span> <span class="identifier">Distribution</span><span class="special">&gt;</span>
 139   <span class="keyword">struct</span> <span class="identifier">DistributionConcept</span><span class="special">;</span>
 140
 141 <span class="special">}}}</span> <span class="comment">// namespaces</span>
 142 </pre>
 143 <p>
 144       The class template <code class="computeroutput"><span class="identifier">distribution_archetype</span></code>
 145       is a model of the <a class="link" href="dist_concept.html" title="Conceptual Requirements for Distribution Types">Distribution concept</a>.
 146     </p>
 147 <p>
 148       The class template <code class="computeroutput"><span class="identifier">DistributionConcept</span></code>
 149       is a <a href="../../../../../libs/concept_check/index.html" target="_top">concept checking
 150       class</a> for distribution types.
 151     </p>
 152 <h3>
 153 <a name="math_toolkit.archetypes.h3"></a>
 154       <span class="phrase"><a name="math_toolkit.archetypes.testing_the_distribution_concept"></a></span><a class="link" href="archetypes.html#math_toolkit.archetypes.testing_the_distribution_concept">Testing
 155       the distribution concept</a>
 156     </h3>
 157 <p>
 158       The test program <a href="../../../test/compile_test/distribution_concept_check.cpp" target="_top">distribution_concept_check.cpp</a>
 159       is responsible for using <code class="computeroutput"><span class="identifier">DistributionConcept</span></code>
 160       to verify that all the distributions in this library conform to the <a class="link" href="dist_concept.html" title="Conceptual Requirements for Distribution Types">Distribution
 161       concept</a>.
 162     </p>
 163 <p>
 164       The class template <code class="computeroutput"><span class="identifier">DistributionConcept</span></code>
 165       verifies the existence (but not proper function) of the non-member accessors
 166       required by the <a class="link" href="dist_concept.html" title="Conceptual Requirements for Distribution Types">Distribution concept</a>.
 167       These are checked by calls like
 168     </p>
 169 <p>
 170       v = pdf(dist, x); // (Result v is ignored).
 171     </p>
 172 <p>
 173       And in addition, those that accept two arguments do the right thing when the
 174       arguments are of different types (the result type is always the same as the
 175       distribution's value_type). (This is implemented by some additional forwarding-functions
 176       in derived_accessors.hpp, so that there is no need for any code changes. Likewise
 177       boilerplate versions of the hazard/chf/coefficient_of_variation functions are
 178       implemented in there too.)
 179     </p>
 180 </div>
 181 <table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
 182 <td align="left"></td>
 183 <td align="right"><div class="copyright-footer">Copyright &#169; 2006-2010, 2012-2014 Nikhar Agrawal,
 184       Anton Bikineev, Paul A. Bristow, Marco Guazzone, Christopher Kormanyos, Hubert
 185       Holin, Bruno Lalande, John Maddock, Jeremy Murphy, Johan R&#229;de, Gautam Sewani,
 186       Benjamin Sobotta, Thijs van den Berg, Daryle Walker and Xiaogang Zhang<p>
 187         Distributed under the Boost Software License, Version 1.0. (See accompanying
 188         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>)
 189       </p>
 190 </div></td>
 191 </tr></table>
 192 <hr>
 193 <div class="spirit-nav">
 194 <a accesskey="p" href="dist_concept.html"><img src="../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../using_udt.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.html"><img src="../../../../../doc/src/images/next.png" alt="Next"></a>
 195 </div>
 196 </body>
 197 </html>