devn00b
/
EQ2EMu


			
				
					
						
						
							123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134
							<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>Composition with Other Libraries</title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="case_studies.html" title="Case Studies">
<link rel="prev" href="case_studies.html" title="Case Studies">
<link rel="next" href="safety_critical_embedded_controller.html" title="Safety Critical Embedded Controller">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="case_studies.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="case_studies.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="safety_critical_embedded_controller.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safe_numerics.composition_with_other_libraries"></a>Composition with Other Libraries</h3></div></div></div>
<p>For many years, Boost has included a library to represent and operate
  on <a href="http://www.boost.org/doc/libs/1_64_0/libs/rational/" target="_top">rational
  numbers</a>. Its well crafted, has good documentation and is well
  maintained. Using the rational library is as easy as construction an
  instance with the expression <code class="computeroutput">rational r(n, d)</code> where n and d are
  integers of the same type. From then on it can be used pretty much as any
  other number. Reading the documentation with safe integers in mind one
  finds</p>
<div class="blockquote"><blockquote class="blockquote"><p>Limited-precision integer types [such as <code class="computeroutput">int</code>] may
      raise issues with the range sizes of their allowable negative values and
      positive values. If the negative range is larger, then the
      extremely-negative numbers will not have an additive inverse in the
      positive range, making them unusable as denominator values since they
      cannot be normalized to positive values (unless the user is lucky enough
      that the input components are not relatively prime
      pre-normalization).</p></blockquote></div>
<p>Which hints of trouble. Examination of the code reveals which
  suggest that care has been taken implement operations so as to avoid
  overflows, catch divide by zero, etc. But the code itself doesn't seem to
  consistently implement this idea. So we make a small demo program:
  </p>
<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">iostream</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">limits</span><span class="special">&gt;</span>

<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">rational</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>
<span class="preprocessor">#include</span> <span class="special">&lt;</span><span class="identifier">boost</span><span class="special">/</span><span class="identifier">safe_numerics</span><span class="special">/</span><span class="identifier">safe_integer</span><span class="special">.</span><span class="identifier">hpp</span><span class="special">&gt;</span>

<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="keyword">int</span><span class="special">,</span> <span class="keyword">const</span> <span class="keyword">char</span> <span class="special">*</span><span class="special">[</span><span class="special">]</span><span class="special">)</span><span class="special">{</span>
    <span class="comment">// simple demo of rational library</span>
    <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">r</span> <span class="special">{</span><span class="number">1</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">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"r = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">r</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">q</span> <span class="special">{</span><span class="special">-</span><span class="number">2</span><span class="special">,</span> <span class="number">4</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">&lt;&lt;</span> <span class="string">"q = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">q</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="comment">// display the product</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"r * q = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">r</span> <span class="special">*</span> <span class="identifier">q</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>

    <span class="comment">// problem: rational doesn't handle integer overflow well</span>
    <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">c</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="identifier">INT_MAX</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">&lt;&lt;</span> <span class="string">"c = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">c</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span> <span class="identifier">d</span> <span class="special">{</span><span class="number">1</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">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"d = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">d</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="comment">// display the product - wrong answer</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"c * d = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">c</span> <span class="special">*</span> <span class="identifier">d</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>

    <span class="comment">// solution: use safe integer in rational definition</span>
    <span class="keyword">using</span> <span class="identifier">safe_rational</span> <span class="special">=</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special">&lt;</span>
        <span class="identifier">boost</span><span class="special">::</span><span class="identifier">safe_numerics</span><span class="special">::</span><span class="identifier">safe</span><span class="special">&lt;</span><span class="keyword">int</span><span class="special">&gt;</span>
    <span class="special">&gt;</span><span class="special">;</span>

    <span class="comment">// use rationals created with safe_t</span>
    <span class="keyword">const</span> <span class="identifier">safe_rational</span> <span class="identifier">sc</span> <span class="special">{</span><span class="number">1</span><span class="special">,</span> <span class="identifier">INT_MAX</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">&lt;&lt;</span> <span class="string">"c = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sc</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="keyword">const</span> <span class="identifier">safe_rational</span> <span class="identifier">sd</span> <span class="special">{</span><span class="number">1</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">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"d = "</span> <span class="special">&lt;&lt;</span> <span class="identifier">sd</span> <span class="special">&lt;&lt;</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span>
    <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="string">"c * d = "</span><span class="special">;</span>
    <span class="keyword">try</span> <span class="special">{</span>
        <span class="comment">// multiply them. This will overflow</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</span> <span class="identifier">sc</span> <span class="special">*</span> <span class="identifier">sd</span> <span class="special">&lt;&lt;</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">catch</span> <span class="special">(</span><span class="identifier">std</span><span class="special">::</span><span class="identifier">exception</span> <span class="keyword">const</span><span class="special">&amp;</span> <span class="identifier">e</span><span class="special">)</span> <span class="special">{</span>
        <span class="comment">// catch exception due to multiplication overflow</span>
        <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special">&lt;&lt;</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="special">&lt;&lt;</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>
</pre>
<p>which
  produces the following output</p>
<pre class="screen">r = 1/2
q = -1/2
r * q = -1/4
c = 1/2147483647
d = 1/2
c * d = 1/-2
c = 1/2147483647
d = 1/2
c * d = multiplication overflow: positive overflow error
</pre>
<p>The <a href="http://www.boost.org/doc/libs/1_64_0/libs/rational/" target="_top">rational library
  documentation</a> is quite specific as to the <a href="http://www.boost.org/doc/libs/1_64_0/libs/rational/rational.html#Integer%20Type%20Requirements" target="_top">type
  requirements</a> placed on the underlying type. Turns out the our <a class="link" href="integer.html" title="Integer&lt;T&gt;">own definition of an integer type</a>
  fulfills (actually surpasses) these requirements. So we have reason to hope
  that we can use <code class="computeroutput">safe&lt;int&gt;</code> as the underlying type to
  create what we might call a "<code class="computeroutput">safe_rational</code>". This we have done
  in the above example where we demonstrate how to compose the rational
  library with the safe numerics library in order to create what amounts to a
  safe_rational library - all without writing a line of code! Still, things
  are not perfect. Since the <a href="http://www.boost.org/doc/libs/1_64_0/libs/rational/" target="_top">rational numbers
  library</a> implements its own checking for divide by zero by throwing
  an exception, the safe numerics code for handling this - included exception
  policy will not be respected. To summarize:</p>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>In some cases safe types can be used as template parameters to
        other types to inject the concept of "no erroneous results" into the
        target type.</p></li>
<li class="listitem"><p>Such composition is not guaranteed to work. The target type must
        be reviewed in some detail.</p></li>
</ul></div>
</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 &#169; 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
      Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="case_studies.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="case_studies.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="safety_critical_embedded_controller.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>