1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>Composition with Other Libraries</title> 5<link rel="stylesheet" href="boostbook.css" type="text/css"> 6<meta name="generator" content="DocBook XSL Stylesheets V1.79.1"> 7<link rel="home" href="index.html" title="Safe Numerics"> 8<link rel="up" href="case_studies.html" title="Case Studies"> 9<link rel="prev" href="case_studies.html" title="Case Studies"> 10<link rel="next" href="safety_critical_embedded_controller.html" title="Safety Critical Embedded Controller"> 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 href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td> 15<td><h2>Safe Numerics</h2></td> 16</tr></table> 17<div class="spirit-nav"> 18<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> 19</div> 20<div class="section"> 21<div class="titlepage"><div><div><h3 class="title"> 22<a name="safe_numerics.composition_with_other_libraries"></a>Composition with Other Libraries</h3></div></div></div> 23<p>For many years, Boost has included a library to represent and operate 24 on <a href="http://www.boost.org/doc/libs/1_64_0/libs/rational/" target="_top">rational 25 numbers</a>. Its well crafted, has good documentation and is well 26 maintained. Using the rational library is as easy as construction an 27 instance with the expression <code class="computeroutput">rational r(n, d)</code> where n and d are 28 integers of the same type. From then on it can be used pretty much as any 29 other number. Reading the documentation with safe integers in mind one 30 finds</p> 31<div class="blockquote"><blockquote class="blockquote"><p>Limited-precision integer types [such as <code class="computeroutput">int</code>] may 32 raise issues with the range sizes of their allowable negative values and 33 positive values. If the negative range is larger, then the 34 extremely-negative numbers will not have an additive inverse in the 35 positive range, making them unusable as denominator values since they 36 cannot be normalized to positive values (unless the user is lucky enough 37 that the input components are not relatively prime 38 pre-normalization).</p></blockquote></div> 39<p>Which hints of trouble. Examination of the code reveals which 40 suggest that care has been taken implement operations so as to avoid 41 overflows, catch divide by zero, etc. But the code itself doesn't seem to 42 consistently implement this idea. So we make a small demo program: 43 </p> 44<pre class="programlisting"><span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">iostream</span><span class="special">></span> 45<span class="preprocessor">#include</span> <span class="special"><</span><span class="identifier">limits</span><span class="special">></span> 46 47<span class="preprocessor">#include</span> <span class="special"><</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">></span> 48<span class="preprocessor">#include</span> <span class="special"><</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">></span> 49 50<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> 51 <span class="comment">// simple demo of rational library</span> 52 <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special"><</span><span class="keyword">int</span><span class="special">></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> 53 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"r = "</span> <span class="special"><<</span> <span class="identifier">r</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 54 <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special"><</span><span class="keyword">int</span><span class="special">></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> 55 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"q = "</span> <span class="special"><<</span> <span class="identifier">q</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 56 <span class="comment">// display the product</span> 57 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"r * q = "</span> <span class="special"><<</span> <span class="identifier">r</span> <span class="special">*</span> <span class="identifier">q</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 58 59 <span class="comment">// problem: rational doesn't handle integer overflow well</span> 60 <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special"><</span><span class="keyword">int</span><span class="special">></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> 61 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"c = "</span> <span class="special"><<</span> <span class="identifier">c</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 62 <span class="keyword">const</span> <span class="identifier">boost</span><span class="special">::</span><span class="identifier">rational</span><span class="special"><</span><span class="keyword">int</span><span class="special">></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> 63 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"d = "</span> <span class="special"><<</span> <span class="identifier">d</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 64 <span class="comment">// display the product - wrong answer</span> 65 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"c * d = "</span> <span class="special"><<</span> <span class="identifier">c</span> <span class="special">*</span> <span class="identifier">d</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 66 67 <span class="comment">// solution: use safe integer in rational definition</span> 68 <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"><</span> 69 <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"><</span><span class="keyword">int</span><span class="special">></span> 70 <span class="special">></span><span class="special">;</span> 71 72 <span class="comment">// use rationals created with safe_t</span> 73 <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> 74 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"c = "</span> <span class="special"><<</span> <span class="identifier">sc</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 75 <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> 76 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"d = "</span> <span class="special"><<</span> <span class="identifier">sd</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 77 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="string">"c * d = "</span><span class="special">;</span> 78 <span class="keyword">try</span> <span class="special">{</span> 79 <span class="comment">// multiply them. This will overflow</span> 80 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</span> <span class="special"><<</span> <span class="identifier">sc</span> <span class="special">*</span> <span class="identifier">sd</span> <span class="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 81 <span class="special">}</span> 82 <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">&</span> <span class="identifier">e</span><span class="special">)</span> <span class="special">{</span> 83 <span class="comment">// catch exception due to multiplication overflow</span> 84 <span class="identifier">std</span><span class="special">::</span><span class="identifier">cout</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="special"><<</span> <span class="identifier">std</span><span class="special">::</span><span class="identifier">endl</span><span class="special">;</span> 85 <span class="special">}</span> 86 87 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 88<span class="special">}</span> 89</pre> 90<p>which 91 produces the following output</p> 92<pre class="screen">r = 1/2 93q = -1/2 94r * q = -1/4 95c = 1/2147483647 96d = 1/2 97c * d = 1/-2 98c = 1/2147483647 99d = 1/2 100c * d = multiplication overflow: positive overflow error 101</pre> 102<p>The <a href="http://www.boost.org/doc/libs/1_64_0/libs/rational/" target="_top">rational library 103 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 104 requirements</a> placed on the underlying type. Turns out the our <a class="link" href="integer.html" title="Integer<T>">own definition of an integer type</a> 105 fulfills (actually surpasses) these requirements. So we have reason to hope 106 that we can use <code class="computeroutput">safe<int></code> as the underlying type to 107 create what we might call a "<code class="computeroutput">safe_rational</code>". This we have done 108 in the above example where we demonstrate how to compose the rational 109 library with the safe numerics library in order to create what amounts to a 110 safe_rational library - all without writing a line of code! Still, things 111 are not perfect. Since the <a href="http://www.boost.org/doc/libs/1_64_0/libs/rational/" target="_top">rational numbers 112 library</a> implements its own checking for divide by zero by throwing 113 an exception, the safe numerics code for handling this - included exception 114 policy will not be respected. To summarize:</p> 115<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 116<li class="listitem"><p>In some cases safe types can be used as template parameters to 117 other types to inject the concept of "no erroneous results" into the 118 target type.</p></li> 119<li class="listitem"><p>Such composition is not guaranteed to work. The target type must 120 be reviewed in some detail.</p></li> 121</ul></div> 122</div> 123<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 124<td align="left"></td> 125<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost 126 Software License</a></p> 127</div></td> 128</tr></table> 129<hr> 130<div class="spirit-nav"> 131<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> 132</div> 133</body> 134</html> 135
