1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>SafeNumeric<T></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="concepts.html" title="Type Requirements"> 9<link rel="prev" href="integer.html" title="Integer<T>"> 10<link rel="next" href="promotion_policy.html" title="PromotionPolicy<PP>"> 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="integer.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.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="promotion_policy.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.safe_numeric_concept"></a>SafeNumeric<T></h3></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="safe_numeric_concept.html#idm130203881648">Description</a></span></dt> 25<dt><span class="section"><a href="safe_numeric_concept.html#idm130203880192">Refinement of</a></span></dt> 26<dt><span class="section"><a href="safe_numeric_concept.html#idm130203877840">Notation</a></span></dt> 27<dt><span class="section"><a href="safe_numeric_concept.html#idm130203860368">Valid Expressions</a></span></dt> 28<dt><span class="section"><a href="safe_numeric_concept.html#idm130203788608">Invariants</a></span></dt> 29<dt><span class="section"><a href="safe_numeric_concept.html#idm130203787008">Models</a></span></dt> 30<dt><span class="section"><a href="safe_numeric_concept.html#idm130203782672">Header</a></span></dt> 31</dl></div> 32<div class="section"> 33<div class="titlepage"><div><div><h4 class="title"> 34<a name="idm130203881648"></a>Description</h4></div></div></div> 35<p>This holds an arithmetic value which can be used as a replacement 36 for built-in C++ arithmetic values. These types differ from their built-in 37 counter parts in that the are guaranteed not to produce invalid arithmetic 38 results. These operations return safe types rather than built-in 39 types.</p> 40</div> 41<div class="section"> 42<div class="titlepage"><div><div><h4 class="title"> 43<a name="idm130203880192"></a>Refinement of</h4></div></div></div> 44<p><a class="link" href="numeric.html" title="Numeric<T>">Numeric</a> or <a class="link" href="integer.html" title="Integer<T>">Integer</a></p> 45</div> 46<div class="section"> 47<div class="titlepage"><div><div><h4 class="title"> 48<a name="idm130203877840"></a>Notation</h4></div></div></div> 49<div class="informaltable"><table class="table"> 50<colgroup> 51<col align="left"> 52<col align="left"> 53</colgroup> 54<thead><tr> 55<th align="left">Symbol</th> 56<th align="left">Description</th> 57</tr></thead> 58<tbody> 59<tr> 60<td align="left"><code class="computeroutput">T, U</code></td> 61<td align="left">Types fulfilling <a class="link" href="numeric.html" title="Numeric<T>">Numeric</a> or <a class="link" href="integer.html" title="Integer<T>">Integer</a> type 62 requirements.</td> 63</tr> 64<tr> 65<td align="left">t, u</td> 66<td align="left">objects of types T, U</td> 67</tr> 68<tr> 69<td align="left">S</td> 70<td align="left">A type fulfilling SafeNumeric type requirements</td> 71</tr> 72<tr> 73<td align="left">s, s1, s2</td> 74<td align="left">objects of types S</td> 75</tr> 76<tr> 77<td align="left">op</td> 78<td align="left">C++ infix operator supported by underlying type T</td> 79</tr> 80<tr> 81<td align="left">prefix_op</td> 82<td align="left">C++ prefix operator: -, +, ~, ++, -- supported by 83 underlying type T</td> 84</tr> 85<tr> 86<td align="left">postfix_op</td> 87<td align="left">C++ postfix operator:++, -- supported by underlying type 88 T</td> 89</tr> 90<tr> 91<td align="left">assign_op</td> 92<td align="left">C++ assignment operator</td> 93</tr> 94</tbody> 95</table></div> 96</div> 97<div class="section"> 98<div class="titlepage"><div><div><h4 class="title"> 99<a name="idm130203860368"></a>Valid Expressions</h4></div></div></div> 100<div class="informaltable"><table class="table"> 101<colgroup> 102<col align="left"> 103<col align="left"> 104<col align="left"> 105</colgroup> 106<thead><tr> 107<th align="left">Expression</th> 108<th align="left">Result Type</th> 109<th align="left">Description</th> 110</tr></thead> 111<tbody> 112<tr> 113<td align="left"><code class="computeroutput">s op t</code></td> 114<td align="left">unspecified S</td> 115<td align="left"><p>invoke C++ operator op and return another 116 SafeNumeric type.</p></td> 117</tr> 118<tr> 119<td align="left"><code class="computeroutput">t op s</code></td> 120<td align="left">unspecified S</td> 121<td align="left"><p>invoke C++ operator op and return another 122 SafeNumeric type.</p></td> 123</tr> 124<tr> 125<td align="left"><code class="computeroutput">s1 op s2</code></td> 126<td align="left">unspecified S</td> 127<td align="left"><p>invoke C++ operator op and return another 128 SafeNumeric type.</p></td> 129</tr> 130<tr> 131<td align="left"><code class="computeroutput">prefix_op S</code></td> 132<td align="left">unspecified S</td> 133<td align="left"><p>invoke C++ operator <code class="computeroutput">prefix_op</code> and 134 return another SafeNumeric type.</p></td> 135</tr> 136<tr> 137<td align="left"><code class="computeroutput">S postfix_op</code></td> 138<td align="left">unspecified S</td> 139<td align="left"><p>invoke C++ operator <code class="computeroutput">postfix_op</code> and 140 return another SafeNumeric type.</p></td> 141</tr> 142<tr> 143<td align="left"><code class="computeroutput">s assign_op t</code></td> 144<td align="left">S &</td> 145<td align="left"><p>convert t to type S and assign it to s. 146 </p></td> 147</tr> 148<tr> 149<td align="left"><code class="computeroutput">t assign_op s</code></td> 150<td align="left">T &</td> 151<td align="left"><p>convert s to type T and assign it to s. If the 152 value t cannot be represented as an instance of type S, it is an 153 error.</p></td> 154</tr> 155<tr> 156<td align="left"><code class="computeroutput">S(t)</code></td> 157<td align="left">S</td> 158<td align="left"><p>construct an instance of S from a value of type T. 159 In this case, T is referred to as the base type of S. If the 160 value t cannot be represented as an instance of type S, it is an 161 exception condition is invoked. </p></td> 162</tr> 163<tr> 164<td align="left"><code class="computeroutput">S</code></td> 165<td align="left">S</td> 166<td align="left"><p>construct an uninitialized instance of 167 S.</p></td> 168</tr> 169<tr> 170<td align="left"><code class="computeroutput">T(s)</code></td> 171<td align="left">T</td> 172<td align="left"><p>implicit conversion of the value of s to type T. If 173 the value of s cannot be correctly represented as a type T, an 174 exception condition is invoked.</p></td> 175</tr> 176<tr> 177<td align="left"><code class="computeroutput">static_cast<T>(s)</code></td> 178<td align="left">T</td> 179<td align="left"><p>convert the value of s to type T. If the value of s 180 cannot be correctly represented as a type T, an exception 181 condition is invoked. </p></td> 182</tr> 183<tr> 184<td align="left"><code class="computeroutput">is_safe<S></code></td> 185<td align="left"><code class="computeroutput">std::true_type</code></td> 186<td align="left"><p>type trait to query whether any type S fulfills the 187 requirements for a SafeNumeric type.</p></td> 188</tr> 189<tr> 190<td align="left"><code class="computeroutput">base_type<S>::type</code></td> 191<td align="left">T</td> 192<td align="left"><p>Retrieve the base type of a given safe 193 type.</p></td> 194</tr> 195<tr> 196<td align="left"><code class="computeroutput">base_value(s)</code></td> 197<td align="left">T</td> 198<td align="left"><p>Retrieve the value of an instance of a safe type. 199 This is equivalent to 200 <code class="computeroutput">static_cast<base_type<S>>(s)</code>.</p></td> 201</tr> 202</tbody> 203</table></div> 204<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 205<li class="listitem"><p>The result of any binary operation where one or both of the 206 operands is a SafeNumeric type is also a SafeNumeric type.</p></li> 207<li class="listitem"><p>All the expressions in the above table are 208 <code class="computeroutput">constexpr</code> expressions.</p></li> 209<li class="listitem"><p>Binary expressions which are not assignments and whose operands 210 are both safe types require that promotion and exception policies of 211 the operands be identical.</p></li> 212<li class="listitem"><p><code class="computeroutput">Operations on safe types are supported if and only if the 213 same operation is supported on the underlying types. For example, the 214 binary operations |</code>, <code class="computeroutput">&</code>, <code class="computeroutput">^</code> and 215 <code class="computeroutput">~</code> operations defined for safe unsigned integer types. But 216 they are not defined for floating point types. Currently the are also 217 defined for signed integer types. It's not clear that this is the 218 correct decision. On one hand, usage of these operators on signed 219 types is almost certainly an error in program logic. But trapping this 220 as an error conflicts with the goal of making safe types "drop-in" 221 replacements for the corresponding built-in types. In light of this, 222 these operators are currently supported as they are for normal 223 built-in types.</p></li> 224<li class="listitem"> 225<p>Safe Numeric types will be implicitly converted to built-in 226 types when appropriate. Here's an example:</p> 227<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="special">;</span> 228 229<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="special">)</span><span class="special">{</span> 230 <span class="keyword">long</span> <span class="identifier">x</span><span class="special">;</span> 231 <span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span><span class="special">;</span> <span class="comment">// OK - builtin implicit version</span> 232 <span class="identifier">safe</span><span class="special"><</span><span class="keyword">long</span><span class="special">></span> <span class="identifier">y</span><span class="special">;</span> 233 <span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">)</span><span class="special">;</span> 234 <span class="keyword">return</span> <span class="number">0</span><span class="special">;</span> 235<span class="special">}</span></pre> 236<p>This behavior supports the concept of 237 <code class="computeroutput">safe<T></code> as being a "drop-in" replacement for a 238 <code class="computeroutput">T</code>.</p> 239</li> 240</ul></div> 241</div> 242<div class="section"> 243<div class="titlepage"><div><div><h4 class="title"> 244<a name="idm130203788608"></a>Invariants</h4></div></div></div> 245<p>The fundamental requirement of a SafeNumeric type is that it 246 implements all C++ operations permitted on its base type in a way the 247 prevents the return of an incorrect arithmetic result. Various 248 implementations of this concept may handle circumstances which produce 249 such results differently (throw exception, compile time trap, etc..). But 250 no implementation should return an arithmetically incorrect result.</p> 251</div> 252<div class="section"> 253<div class="titlepage"><div><div><h4 class="title"> 254<a name="idm130203787008"></a>Models</h4></div></div></div> 255<p><code class="computeroutput">safe<T></code></p> 256<p><code class="computeroutput">safe_signed_range<-11, 11></code></p> 257<p><code class="computeroutput">safe_unsigned_range<0, 11></code></p> 258<p><code class="computeroutput">safe_signed_literal<4></code></p> 259</div> 260<div class="section"> 261<div class="titlepage"><div><div><h4 class="title"> 262<a name="idm130203782672"></a>Header</h4></div></div></div> 263<p><a href="../../include/concept/safe_numeric.hpp" target="_top"><code class="computeroutput">#include 264 <boost/numeric/safe_numerics/concepts/safe_numeric.hpp></code></a></p> 265</div> 266</div> 267<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 268<td align="left"></td> 269<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 270 Software License</a></p> 271</div></td> 272</tr></table> 273<hr> 274<div class="spirit-nav"> 275<a accesskey="p" href="integer.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.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="promotion_policy.html"><img src="images/next.png" alt="Next"></a> 276</div> 277</body> 278</html> 279
