1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII"> 4<title>Numeric<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="concepts.html" title="Type Requirements"> 10<link rel="next" href="integer.html" title="Integer<T>"> 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="concepts.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="integer.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.numeric"></a>Numeric<T></h3></div></div></div> 23<div class="toc"><dl class="toc"> 24<dt><span class="section"><a href="numeric.html#safe_numerics.numeric.description">Description</a></span></dt> 25<dt><span class="section"><a href="numeric.html#idm130204085440">Notation</a></span></dt> 26<dt><span class="section"><a href="numeric.html#idm130204078192">Associated Types</a></span></dt> 27<dt><span class="section"><a href="numeric.html#idm130204072896">Valid Expressions</a></span></dt> 28<dt><span class="section"><a href="numeric.html#idm130203973088">Models</a></span></dt> 29<dt><span class="section"><a href="numeric.html#idm130203971280">Header</a></span></dt> 30<dt><span class="section"><a href="numeric.html#idm130203969088">Note on Usage of <code class="computeroutput">std::numeric_limits</code></a></span></dt> 31</dl></div> 32<div class="section"> 33<div class="titlepage"><div><div><h4 class="title"> 34<a name="safe_numerics.numeric.description"></a>Description</h4></div></div></div> 35<p>A type is Numeric if it has the properties of a number.</p> 36<p>More specifically, a type T is Numeric if there exists a 37 specialization of <code class="computeroutput">std::numeric_limits<T></code>. See the 38 documentation for the standard library class <code class="computeroutput">numeric_limits</code>. 39 The standard library includes such specializations for all the built-in 40 numeric types. Note that this concept is distinct from the C++ standard 41 library type traits <code class="computeroutput">is_integral</code> and 42 <code class="computeroutput">is_arithmetic</code>. These latter fulfill the requirement of the 43 concept Numeric. But there are types T which fulfill this concept for 44 which <code class="computeroutput">is_arithmetic<T>::value == false</code>. For example see 45 <code class="computeroutput">safe_signed_integer<int></code>.</p> 46</div> 47<div class="section"> 48<div class="titlepage"><div><div><h4 class="title"> 49<a name="idm130204085440"></a>Notation</h4></div></div></div> 50<div class="informaltable"><table class="table"> 51<colgroup> 52<col align="left"> 53<col align="left"> 54</colgroup> 55<tbody> 56<tr> 57<td align="left"><code class="computeroutput">T, U, V</code></td> 58<td align="left">A type that is a model of Numeric</td> 59</tr> 60<tr> 61<td align="left"><code class="computeroutput">t, u</code></td> 62<td align="left">An object of a type modeling Numeric</td> 63</tr> 64</tbody> 65</table></div> 66</div> 67<div class="section"> 68<div class="titlepage"><div><div><h4 class="title"> 69<a name="idm130204078192"></a>Associated Types</h4></div></div></div> 70<div class="informaltable"><table class="table"> 71<colgroup> 72<col align="left"> 73<col align="left"> 74</colgroup> 75<tbody><tr> 76<td align="left"><code class="computeroutput">std::numeric_limits<T></code></td> 77<td align="left">The numeric_limits class template provides a C++ program 78 with information about various properties of the implementation's 79 representation of the arithmetic types. See C++ standard 80 18.3.2.2.</td> 81</tr></tbody> 82</table></div> 83</div> 84<div class="section"> 85<div class="titlepage"><div><div><h4 class="title"> 86<a name="idm130204072896"></a>Valid Expressions</h4></div></div></div> 87<p>In addition to the expressions defined in <a href="http://www.sgi.com/tech/stl/Assignable.html" target="_top">Assignable</a> the 88 following expressions must be valid. Any operations which result in 89 integers which cannot be represented as some Numeric type will throw an 90 exception.</p> 91<div class="table"> 92<a name="idm130204071072"></a><p class="title"><b>Table 1. General</b></p> 93<div class="table-contents"><table class="table" summary="General"> 94<colgroup> 95<col align="left"> 96<col align="left"> 97<col align="left"> 98</colgroup> 99<thead><tr> 100<th align="left">Expression</th> 101<th align="left">Return Type</th> 102<th align="left">Return Value</th> 103</tr></thead> 104<tbody> 105<tr> 106<td align="left"><code class="computeroutput">std::numeric_limits<T>::is_bounded 107 </code></td> 108<td align="left"><code class="computeroutput">bool</code></td> 109<td align="left"> 110<code class="computeroutput">true</code> or <code class="computeroutput">false</code> 111</td> 112</tr> 113<tr> 114<td align="left"><code class="computeroutput">std::numeric_limits<T>::is_integer</code></td> 115<td align="left"><code class="computeroutput">bool</code></td> 116<td align="left"> 117<code class="computeroutput">true</code> or <code class="computeroutput">false</code> 118</td> 119</tr> 120<tr> 121<td align="left"><code class="computeroutput">std::numeric_limits<T>::is_signed</code></td> 122<td align="left"><code class="computeroutput">bool</code></td> 123<td align="left"> 124<code class="computeroutput">true</code> or <code class="computeroutput">false</code> 125</td> 126</tr> 127<tr> 128<td align="left"><code class="computeroutput">std::numeric_limits<T>::is_specialized 129 </code></td> 130<td align="left"><code class="computeroutput">bool</code></td> 131<td align="left"><code class="computeroutput">true</code></td> 132</tr> 133</tbody> 134</table></div> 135</div> 136<p><br class="table-break"></p> 137<div class="table"> 138<a name="idm130204050048"></a><p class="title"><b>Table 2. Unary Operators</b></p> 139<div class="table-contents"><table class="table" summary="Unary Operators"> 140<colgroup> 141<col align="left"> 142<col align="left"> 143<col align="left"> 144</colgroup> 145<thead><tr> 146<th align="left">Expression</th> 147<th align="left">Return Type</th> 148<th align="left">Semantics</th> 149</tr></thead> 150<tbody> 151<tr> 152<td align="left"><code class="computeroutput">-t</code></td> 153<td align="left"><code class="computeroutput">T</code></td> 154<td align="left">Invert sign</td> 155</tr> 156<tr> 157<td align="left"><code class="computeroutput">+t</code></td> 158<td align="left"><code class="computeroutput">T</code></td> 159<td align="left">unary plus - a no op</td> 160</tr> 161<tr> 162<td align="left"><code class="computeroutput">t--</code></td> 163<td align="left"><code class="computeroutput">T</code></td> 164<td align="left">post decrement</td> 165</tr> 166<tr> 167<td align="left"><code class="computeroutput">t++</code></td> 168<td align="left"><code class="computeroutput">T</code></td> 169<td align="left">post increment</td> 170</tr> 171<tr> 172<td align="left"><code class="computeroutput">--t</code></td> 173<td align="left"><code class="computeroutput">T</code></td> 174<td align="left">pre decrement</td> 175</tr> 176<tr> 177<td align="left"><code class="computeroutput">++t</code></td> 178<td align="left"><code class="computeroutput">T</code></td> 179<td align="left">pre increment</td> 180</tr> 181</tbody> 182</table></div> 183</div> 184<br class="table-break"><div class="table"> 185<a name="idm130204029296"></a><p class="title"><b>Table 3. Binary Operators</b></p> 186<div class="table-contents"><table class="table" summary="Binary Operators"> 187<colgroup> 188<col align="left"> 189<col align="left"> 190<col align="left"> 191</colgroup> 192<thead><tr> 193<th align="left">Expression</th> 194<th align="left">Return Type</th> 195<th align="left">Semantics</th> 196</tr></thead> 197<tbody> 198<tr> 199<td align="left"><code class="computeroutput">t - u</code></td> 200<td align="left"><code class="computeroutput">V</code></td> 201<td align="left">subtract u from t</td> 202</tr> 203<tr> 204<td align="left"><code class="computeroutput">t + u</code></td> 205<td align="left"><code class="computeroutput">V</code></td> 206<td align="left">add u to t</td> 207</tr> 208<tr> 209<td align="left"><code class="computeroutput">t * u</code></td> 210<td align="left"><code class="computeroutput">V</code></td> 211<td align="left">multiply t by u</td> 212</tr> 213<tr> 214<td align="left"><code class="computeroutput">t / u</code></td> 215<td align="left"><code class="computeroutput">T</code></td> 216<td align="left">divide t by u</td> 217</tr> 218<tr> 219<td align="left"><code class="computeroutput">t % u</code></td> 220<td align="left"><code class="computeroutput">T</code></td> 221<td align="left">t modulus u</td> 222</tr> 223<tr> 224<td align="left"><code class="computeroutput">t < u</code></td> 225<td align="left"><code class="computeroutput">bool</code></td> 226<td align="left"> 227<code class="computeroutput">true</code> if t less than u, <code class="computeroutput">false</code> 228 otherwise</td> 229</tr> 230<tr> 231<td align="left"><code class="computeroutput">t <= u</code></td> 232<td align="left"><code class="computeroutput">bool</code></td> 233<td align="left"> 234<code class="computeroutput">true</code> if t less than or equal to u, 235 <code class="computeroutput">false</code> otherwise</td> 236</tr> 237<tr> 238<td align="left"><code class="computeroutput">t > u</code></td> 239<td align="left"><code class="computeroutput">bool</code></td> 240<td align="left"> 241<code class="computeroutput">true</code> if t greater than u, <code class="computeroutput">false</code> 242 otherwise</td> 243</tr> 244<tr> 245<td align="left"><code class="computeroutput">t >= u</code></td> 246<td align="left"><code class="computeroutput">bool</code></td> 247<td align="left"> 248<code class="computeroutput">true</code> if t greater than or equal to u, 249 <code class="computeroutput">false</code> otherwise</td> 250</tr> 251<tr> 252<td align="left"><code class="computeroutput">t == u</code></td> 253<td align="left"><code class="computeroutput">bool</code></td> 254<td align="left"> 255<code class="computeroutput">true</code> if t equal to u, <code class="computeroutput">false</code> 256 otherwise</td> 257</tr> 258<tr> 259<td align="left"><code class="computeroutput">t != u</code></td> 260<td align="left"><code class="computeroutput">bool</code></td> 261<td align="left"> 262<code class="computeroutput">true</code> if t not equal to u, <code class="computeroutput">false</code> 263 otherwise</td> 264</tr> 265<tr> 266<td align="left"><code class="computeroutput">t = u</code></td> 267<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td> 268<td align="left">assign value of u to t</td> 269</tr> 270<tr> 271<td align="left"><code class="computeroutput">t += u</code></td> 272<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td> 273<td align="left">add u to t and assign to t</td> 274</tr> 275<tr> 276<td align="left"><code class="computeroutput">t -= u</code></td> 277<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td> 278<td align="left">subtract u from t and assign to t</td> 279</tr> 280<tr> 281<td align="left"><code class="computeroutput">t *= u</code></td> 282<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td> 283<td align="left">multiply t by u and assign to t</td> 284</tr> 285<tr> 286<td align="left"><code class="computeroutput">t /= u</code></td> 287<td align="left"><code class="computeroutput"><code class="computeroutput">T</code></code></td> 288<td align="left">divide t by u and assign to t</td> 289</tr> 290</tbody> 291</table></div> 292</div> 293<br class="table-break"> 294</div> 295<div class="section"> 296<div class="titlepage"><div><div><h4 class="title"> 297<a name="idm130203973088"></a>Models</h4></div></div></div> 298<p><code class="computeroutput">int, float, safe_signed_integer<int>, 299 safe_signed_range<int>, checked_result<int>, 300 etc.</code></p> 301</div> 302<div class="section"> 303<div class="titlepage"><div><div><h4 class="title"> 304<a name="idm130203971280"></a>Header</h4></div></div></div> 305<p><a href="../../include/concept/numeric.hpp" target="_top"><code class="computeroutput">#include 306 <boost/numeric/safe_numerics/concepts/numeric.hpp> 307 </code></a></p> 308</div> 309<div class="section"> 310<div class="titlepage"><div><div><h4 class="title"> 311<a name="idm130203969088"></a>Note on Usage of <code class="computeroutput">std::numeric_limits</code> 312</h4></div></div></div> 313<p>We define the word "Numeric" in terms of the operations which are 314 supported by "Numeric" types. This is in line with the current and 315 historical usage of the word "concept" in the context of C++. It is also 316 common to define compile time predicates such as 317 "<code class="computeroutput">is_numeric<T></code>" to permit one to include expressions in 318 his code which will generated a compile time error if the specified type 319 (T) does not support the operations required. But this is not always true. 320 In the C++ standard library there is a predicate 321 <code class="computeroutput">is_arithmetic<T></code> whose name might suggest that it 322 should return <code class="computeroutput">true</code> for any type which supports the operations 323 above. But this is not the case. The standard defines 324 <code class="computeroutput">is_arithmetic<T></code> as <code class="computeroutput">true</code> for any of the 325 builtin types <code class="computeroutput">int</code>, <code class="computeroutput">long</code>, <code class="computeroutput">float</code>, 326 <code class="computeroutput">double</code>, etc and <code class="computeroutput">false</code> for any other types. So 327 even if a user defined type U were to support the operations above, 328 <code class="computeroutput">is_arithmetic<U></code> would still return <code class="computeroutput">false</code>. 329 This is quite unintuitive and not a good match for our purposes. Hence we 330 define our own term "Numeric" to designate any type T which:</p> 331<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 332<li class="listitem"><p>Supports the operations above</p></li> 333<li class="listitem"><p>Specializes the standard type numeric_limits</p></li> 334</ul></div> 335<p>while following the C++ standard in using 336 <code class="computeroutput">is_arithmetic<T></code>, <code class="computeroutput">is_integral<T></code> to 337 detect specific types only. The standard types are useful in various 338 aspects of the implementation - which of course is done in terms of the 339 standard types.</p> 340<p>This in turn raises another question: Is it "legal" to specialize 341 <code class="computeroutput">std::numeric_limits</code> for one's own types such as 342 <code class="computeroutput">safe<int></code>. In my view the standard is ambiguous on 343 this. See various interpretations: </p> 344<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 345<li class="listitem"><p><a href="https://stackoverflow.com/questions/16122912/is-it-ok-to-specialize-stdnumeric-limitst-for-user-defined-number-like-class" target="_top">is-it-ok-to-specialize-stdnumeric-limitst-for-user-defined-number-like-class</a></p></li> 346<li class="listitem"><p><a href="https://en.cppreference.com/w/cpp/types/numeric_limits" target="_top">cppreference.com/w/cpp/types/numeric_limits</a></p></li> 347</ul></div> 348<p>In any case, it seems pretty clear that no harm will come of it. In 349 spite of the consideration given to this issue, it turns out that the 350 found no real need to implement these predicates. For example, there is no 351 "is_numeric<T>" implemented as part of the safe numerics library. 352 This may change in the future though. Even if not used, defining and 353 maintaining these type requirements in this document has been very 354 valuable in keeping the concepts and code more unified and 355 understandable.</p> 356<p>Remember that above considerations apply to other numeric types used 357 in this library even though we don't explicitly repeat this information 358 for every case.</p> 359</div> 360</div> 361<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 362<td align="left"></td> 363<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 364 Software License</a></p> 365</div></td> 366</tr></table> 367<hr> 368<div class="spirit-nav"> 369<a accesskey="p" href="concepts.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="integer.html"><img src="images/next.png" alt="Next"></a> 370</div> 371</body> 372</html> 373
