1<html> 2<head> 3<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"> 4<title>Definitions</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="Chapter 1. Boost.NumericConversion"> 8<link rel="up" href="../index.html" title="Chapter 1. Boost.NumericConversion"> 9<link rel="prev" href="../index.html" title="Chapter 1. Boost.NumericConversion"> 10<link rel="next" href="converter___function_object.html" title="converter<> function object"> 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="../index.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="converter___function_object.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="boost_numericconversion.definitions"></a><a class="link" href="definitions.html" title="Definitions">Definitions</a> 28</h2></div></div></div> 29<div class="toc"><dl class="toc"> 30<dt><span class="section"><a href="definitions.html#boost_numericconversion.definitions.introduction">Introduction</a></span></dt> 31<dt><span class="section"><a href="definitions.html#boost_numericconversion.definitions.types_and_values">Types 32 and Values</a></span></dt> 33<dt><span class="section"><a href="definitions.html#boost_numericconversion.definitions.c___arithmetic_types">C++ 34 Arithmetic Types</a></span></dt> 35<dt><span class="section"><a href="definitions.html#boost_numericconversion.definitions.numeric_types">Numeric 36 Types</a></span></dt> 37<dt><span class="section"><a href="definitions.html#boost_numericconversion.definitions.range_and_precision">Range 38 and Precision</a></span></dt> 39<dt><span class="section"><a href="definitions.html#boost_numericconversion.definitions.exact__correctly_rounded_and_out_of_range_representations">Exact, 40 Correctly Rounded and Out-Of-Range Representations</a></span></dt> 41<dt><span class="section"><a href="definitions.html#boost_numericconversion.definitions.standard__numeric__conversions">Standard 42 (numeric) Conversions</a></span></dt> 43<dt><span class="section"><a href="definitions.html#boost_numericconversion.definitions.subranged_conversion_direction__subtype_and_supertype">Subranged 44 Conversion Direction, Subtype and Supertype</a></span></dt> 45</dl></div> 46<div class="section"> 47<div class="titlepage"><div><div><h3 class="title"> 48<a name="boost_numericconversion.definitions.introduction"></a><a class="link" href="definitions.html#boost_numericconversion.definitions.introduction" title="Introduction">Introduction</a> 49</h3></div></div></div> 50<p> 51 This section provides definitions of terms used in the Numeric Conversion 52 library. 53 </p> 54<div class="blurb"> 55<div class="titlepage"><div><div><p class="title"><b></b></p></div></div></div> 56<p> 57 <span class="bold"><strong>Notation</strong></span> <span class="underline">underlined 58 text</span> denotes terms defined in the C++ standard. 59 </p> 60<p> 61 <span class="bold"><strong>bold face</strong></span> denotes terms defined here but 62 not in the standard. 63 </p> 64</div> 65</div> 66<div class="section"> 67<div class="titlepage"><div><div><h3 class="title"> 68<a name="boost_numericconversion.definitions.types_and_values"></a><a class="link" href="definitions.html#boost_numericconversion.definitions.types_and_values" title="Types and Values">Types 69 and Values</a> 70</h3></div></div></div> 71<p> 72 As defined by the <span class="underline">C++ Object Model</span> 73 (§1.7) the <span class="underline">storage</span> or memory on which 74 a C++ program runs is a contiguous sequence of <span class="underline">bytes</span> 75 where each byte is a contiguous sequence of bits. 76 </p> 77<p> 78 An <span class="underline">object</span> is a region of storage (§1.8) 79 and has a type (§3.9). 80 </p> 81<p> 82 A <span class="underline">type</span> is a discrete set of values. 83 </p> 84<p> 85 An object of type <code class="computeroutput"><span class="identifier">T</span></code> has an 86 <span class="underline">object representation</span> which is the 87 sequence of bytes stored in the object (§3.9/4) 88 </p> 89<p> 90 An object of type <code class="computeroutput"><span class="identifier">T</span></code> has a 91 <span class="underline">value representation</span> which is the set 92 of bits that determine the <span class="emphasis"><em>value</em></span> of an object of that 93 type (§3.9/4). For <span class="underline">POD</span> types (§3.9/10), 94 this bitset is given by the object representation, but not all the bits in 95 the storage need to participate in the value representation (except for character 96 types): for example, some bits might be used for padding or there may be 97 trap-bits. 98 </p> 99<p> 100 <span class="inlinemediaobject"><img src="../images/space.png" alt="space"></span> 101 </p> 102<p> 103 The <span class="bold"><strong>typed value</strong></span> that is held by an object 104 is the value which is determined by its value representation. 105 </p> 106<p> 107 An <span class="bold"><strong>abstract value</strong></span> (untyped) is the conceptual 108 information that is represented in a type (i.e. the number π). 109 </p> 110<p> 111 The <span class="bold"><strong>intrinsic value</strong></span> of an object is the 112 binary value of the sequence of unsigned characters which form its object 113 representation. 114 </p> 115<p> 116 <span class="inlinemediaobject"><img src="../images/space.png" alt="space"></span> 117 </p> 118<p> 119 <span class="emphasis"><em>Abstract</em></span> values can be <span class="bold"><strong>represented</strong></span> 120 in a given type. 121 </p> 122<p> 123 To <span class="bold"><strong>represent</strong></span> an abstract value <code class="computeroutput"><span class="identifier">V</span></code> in a type <code class="computeroutput"><span class="identifier">T</span></code> 124 is to obtain a typed value <code class="computeroutput"><span class="identifier">v</span></code> 125 which corresponds to the abstract value <code class="computeroutput"><span class="identifier">V</span></code>. 126 </p> 127<p> 128 The operation is denoted using the <code class="computeroutput"><span class="identifier">rep</span><span class="special">()</span></code> operator, as in: <code class="computeroutput"><span class="identifier">v</span><span class="special">=</span><span class="identifier">rep</span><span class="special">(</span><span class="identifier">V</span><span class="special">)</span></code>. <code class="computeroutput"><span class="identifier">v</span></code> is the <span class="bold"><strong>representation</strong></span> 129 of <code class="computeroutput"><span class="identifier">V</span></code> in the type <code class="computeroutput"><span class="identifier">T</span></code>. 130 </p> 131<p> 132 For example, the abstract value π can be represented in the type <code class="computeroutput"><span class="keyword">double</span></code> as the <code class="computeroutput"><span class="keyword">double</span> 133 <span class="identifier">value</span> <span class="identifier">M_PI</span></code> 134 and in the type <code class="computeroutput"><span class="keyword">int</span></code> as the 135 <code class="computeroutput"><span class="keyword">int</span> <span class="identifier">value</span> 136 <span class="number">3</span></code> 137 </p> 138<p> 139 <span class="inlinemediaobject"><img src="../images/space.png" alt="space"></span> 140 </p> 141<p> 142 Conversely, <span class="emphasis"><em>typed values</em></span> can be <span class="bold"><strong>abstracted</strong></span>. 143 </p> 144<p> 145 To <span class="bold"><strong>abstract</strong></span> a typed value <code class="computeroutput"><span class="identifier">v</span></code> of type <code class="computeroutput"><span class="identifier">T</span></code> 146 is to obtain the abstract value <code class="computeroutput"><span class="identifier">V</span></code> 147 whose representation in <code class="computeroutput"><span class="identifier">T</span></code> 148 is <code class="computeroutput"><span class="identifier">v</span></code>. 149 </p> 150<p> 151 The operation is denoted using the <code class="computeroutput"><span class="identifier">abt</span><span class="special">()</span></code> operator, as in: <code class="computeroutput"><span class="identifier">V</span><span class="special">=</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">v</span><span class="special">)</span></code>. 152 </p> 153<p> 154 <code class="computeroutput"><span class="identifier">V</span></code> is the <span class="bold"><strong>abstraction</strong></span> 155 of <code class="computeroutput"><span class="identifier">v</span></code> of type <code class="computeroutput"><span class="identifier">T</span></code>. 156 </p> 157<p> 158 Abstraction is just an abstract operation (you can't do it); but it is defined 159 nevertheless because it will be used to give the definitions in the rest 160 of this document. 161 </p> 162</div> 163<div class="section"> 164<div class="titlepage"><div><div><h3 class="title"> 165<a name="boost_numericconversion.definitions.c___arithmetic_types"></a><a class="link" href="definitions.html#boost_numericconversion.definitions.c___arithmetic_types" title="C++ Arithmetic Types">C++ 166 Arithmetic Types</a> 167</h3></div></div></div> 168<p> 169 The C++ language defines <span class="underline">fundamental types</span> 170 (§3.9.1). The following subsets of the fundamental types are intended to 171 represent <span class="emphasis"><em>numbers</em></span>: 172 </p> 173<div class="variablelist"> 174<p class="title"><b></b></p> 175<dl class="variablelist"> 176<dt><span class="term"><span class="underline">signed integer types</span> (§3.9.1/2):</span></dt> 177<dd><p> 178 <code class="computeroutput"><span class="special">{</span><span class="keyword">signed</span> 179 <span class="keyword">char</span><span class="special">,</span> 180 <span class="keyword">signed</span> <span class="keyword">short</span> 181 <span class="keyword">int</span><span class="special">,</span> 182 <span class="keyword">signed</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">signed</span> <span class="keyword">long</span> <span class="keyword">int</span><span class="special">}</span></code> Can be used to represent general integer 183 numbers (both negative and positive). 184 </p></dd> 185<dt><span class="term"><span class="underline">unsigned integer types</span> (§3.9.1/3):</span></dt> 186<dd><p> 187 <code class="computeroutput"><span class="special">{</span><span class="keyword">unsigned</span> 188 <span class="keyword">char</span><span class="special">,</span> 189 <span class="keyword">unsigned</span> <span class="keyword">short</span> 190 <span class="keyword">int</span><span class="special">,</span> 191 <span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">,</span> <span class="keyword">unsigned</span> 192 <span class="keyword">long</span> <span class="keyword">int</span><span class="special">}</span></code> Can be used to represent positive 193 integer numbers with modulo-arithmetic. 194 </p></dd> 195<dt><span class="term"><span class="underline">floating-point types</span> (§3.9.1/8):</span></dt> 196<dd><p> 197 <code class="computeroutput"><span class="special">{</span><span class="keyword">float</span><span class="special">,</span><span class="keyword">double</span><span class="special">,</span><span class="keyword">long</span> <span class="keyword">double</span><span class="special">}</span></code> 198 Can be used to represent real numbers. 199 </p></dd> 200<dt><span class="term"><span class="underline">integral or integer types</span> (§3.9.1/7):</span></dt> 201<dd><p> 202 <code class="computeroutput"><span class="special">{{</span><span class="keyword">signed</span> 203 <span class="identifier">integers</span><span class="special">},{</span><span class="keyword">unsigned</span> <span class="identifier">integers</span><span class="special">},</span> <span class="keyword">bool</span><span class="special">,</span> <span class="keyword">char</span> <span class="keyword">and</span> <span class="keyword">wchar_t</span><span class="special">}</span></code> 204 </p></dd> 205<dt><span class="term"><span class="underline">arithmetic types</span> (§3.9.1/8):</span></dt> 206<dd><p> 207 <code class="computeroutput"><span class="special">{{</span><span class="identifier">integer</span> 208 <span class="identifier">types</span><span class="special">},{</span><span class="identifier">floating</span> <span class="identifier">types</span><span class="special">}}</span></code> 209 </p></dd> 210</dl> 211</div> 212<p> 213 The integer types are required to have a <span class="emphasis"><em>binary</em></span> value 214 representation. 215 </p> 216<p> 217 Additionally, the signed/unsigned integer types of the same base type (<code class="computeroutput"><span class="keyword">short</span></code>, <code class="computeroutput"><span class="keyword">int</span></code> 218 or <code class="computeroutput"><span class="keyword">long</span></code>) are required to have 219 the same value representation, that is: 220 </p> 221<pre class="programlisting"> <span class="keyword">int</span> <span class="identifier">i</span> <span class="special">=</span> <span class="special">-</span><span class="number">3</span> <span class="special">;</span> <span class="comment">// suppose value representation is: 10011 (sign bit + 4 magnitude bits)</span> 222<span class="keyword">unsigned</span> <span class="keyword">int</span> <span class="identifier">u</span> <span class="special">=</span> <span class="identifier">i</span> <span class="special">;</span> <span class="comment">// u is required to have the same 10011 as its value representation.</span> 223</pre> 224<p> 225 In other words, the integer types signed/unsigned X use the same value representation 226 but a different <span class="emphasis"><em>interpretation</em></span> of it; that is, their 227 <span class="emphasis"><em>typed values</em></span> might differ. 228 </p> 229<p> 230 Another consequence of this is that the range for signed X is always a smaller 231 subset of the range of unsigned X, as required by §3.9.1/3. 232 </p> 233<div class="note"><table border="0" summary="Note"> 234<tr> 235<td rowspan="2" align="center" valign="top" width="25"><img alt="[Note]" src="../../../../../../doc/src/images/note.png"></td> 236<th align="left">Note</th> 237</tr> 238<tr><td align="left" valign="top"> 239<p> 240 Always remember that unsigned types, unlike signed types, have modulo-arithmetic; 241 that is, they do not overflow. This means that: 242 </p> 243<p> 244 <span class="bold"><strong>-</strong></span> Always be extra careful when mixing 245 signed/unsigned types 246 </p> 247<p> 248 <span class="bold"><strong>-</strong></span> Use unsigned types only when you need 249 modulo arithmetic or very very large numbers. Don't use unsigned types 250 just because you intend to deal with positive values only (you can do this 251 with signed types as well). 252 </p> 253</td></tr> 254</table></div> 255</div> 256<div class="section"> 257<div class="titlepage"><div><div><h3 class="title"> 258<a name="boost_numericconversion.definitions.numeric_types"></a><a class="link" href="definitions.html#boost_numericconversion.definitions.numeric_types" title="Numeric Types">Numeric 259 Types</a> 260</h3></div></div></div> 261<p> 262 This section introduces the following definitions intended to integrate arithmetic 263 types with user-defined types which behave like numbers. Some definitions 264 are purposely broad in order to include a vast variety of user-defined number 265 types. 266 </p> 267<p> 268 Within this library, the term <span class="emphasis"><em>number</em></span> refers to an abstract 269 numeric value. 270 </p> 271<p> 272 A type is <span class="bold"><strong>numeric</strong></span> if: 273 </p> 274<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 275<li class="listitem"> 276 It is an arithmetic type, or, 277 </li> 278<li class="listitem"> 279 It is a user-defined type which 280 <div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "> 281<li class="listitem"> 282 Represents numeric abstract values (i.e. numbers). 283 </li> 284<li class="listitem"> 285 Can be converted (either implicitly or explicitly) to/from at least 286 one arithmetic type. 287 </li> 288<li class="listitem"> 289 Has <a class="link" href="definitions.html#boost_numericconversion.definitions.range_and_precision" title="Range and Precision">range</a> 290 (possibly unbounded) and <a class="link" href="definitions.html#boost_numericconversion.definitions.range_and_precision" title="Range and Precision">precision</a> 291 (possibly dynamic or unlimited). 292 </li> 293<li class="listitem"> 294 Provides an specialization of <code class="computeroutput"><span class="identifier">std</span><span class="special">::</span><span class="identifier">numeric_limits</span></code>. 295 </li> 296</ul></div> 297 </li> 298</ul></div> 299<p> 300 A numeric type is <span class="bold"><strong>signed</strong></span> if the abstract 301 values it represent include negative numbers. 302 </p> 303<p> 304 A numeric type is <span class="bold"><strong>unsigned</strong></span> if the abstract 305 values it represent exclude negative numbers. 306 </p> 307<p> 308 A numeric type is <span class="bold"><strong>modulo</strong></span> if it has modulo-arithmetic 309 (does not overflow). 310 </p> 311<p> 312 A numeric type is <span class="bold"><strong>integer</strong></span> if the abstract 313 values it represent are whole numbers. 314 </p> 315<p> 316 A numeric type is <span class="bold"><strong>floating</strong></span> if the abstract 317 values it represent are real numbers. 318 </p> 319<p> 320 An <span class="bold"><strong>arithmetic value</strong></span> is the typed value of 321 an arithmetic type 322 </p> 323<p> 324 A <span class="bold"><strong>numeric value</strong></span> is the typed value of a 325 numeric type 326 </p> 327<p> 328 These definitions simply generalize the standard notions of arithmetic types 329 and values by introducing a superset called <span class="underline">numeric</span>. 330 All arithmetic types and values are numeric types and values, but not vice 331 versa, since user-defined numeric types are not arithmetic types. 332 </p> 333<p> 334 The following examples clarify the differences between arithmetic and numeric 335 types (and values): 336 </p> 337<pre class="programlisting"><span class="comment">// A numeric type which is not an arithmetic type (is user-defined)</span> 338<span class="comment">// and which is intended to represent integer numbers (i.e., an 'integer' numeric type)</span> 339<span class="keyword">class</span> <span class="identifier">MyInt</span> 340<span class="special">{</span> 341 <span class="identifier">MyInt</span> <span class="special">(</span> <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">v</span> <span class="special">)</span> <span class="special">;</span> 342 <span class="keyword">long</span> <span class="keyword">long</span> <span class="identifier">to_builtin</span><span class="special">();</span> 343<span class="special">}</span> <span class="special">;</span> 344<span class="keyword">namespace</span> <span class="identifier">std</span> <span class="special">{</span> 345<span class="keyword">template</span><span class="special"><></span> <span class="identifier">numeric_limits</span><span class="special"><</span><span class="identifier">MyInt</span><span class="special">></span> <span class="special">{</span> <span class="special">...</span> <span class="special">}</span> <span class="special">;</span> 346<span class="special">}</span> 347 348<span class="comment">// A 'floating' numeric type (double) which is also an arithmetic type (built-in),</span> 349<span class="comment">// with a float numeric value.</span> 350<span class="keyword">double</span> <span class="identifier">pi</span> <span class="special">=</span> <span class="identifier">M_PI</span> <span class="special">;</span> 351 352<span class="comment">// A 'floating' numeric type with a whole numeric value.</span> 353<span class="comment">// NOTE: numeric values are typed valued, hence, they are, for instance,</span> 354<span class="comment">// integer or floating, despite the value itself being whole or including</span> 355<span class="comment">// a fractional part.</span> 356<span class="keyword">double</span> <span class="identifier">two</span> <span class="special">=</span> <span class="number">2.0</span> <span class="special">;</span> 357 358<span class="comment">// An integer numeric type with an integer numeric value.</span> 359<span class="identifier">MyInt</span> <span class="identifier">i</span><span class="special">(</span><span class="number">1234</span><span class="special">);</span> 360</pre> 361</div> 362<div class="section"> 363<div class="titlepage"><div><div><h3 class="title"> 364<a name="boost_numericconversion.definitions.range_and_precision"></a><a class="link" href="definitions.html#boost_numericconversion.definitions.range_and_precision" title="Range and Precision">Range 365 and Precision</a> 366</h3></div></div></div> 367<p> 368 Given a number set <code class="computeroutput"><span class="identifier">N</span></code>, some 369 of its elements are representable in a numeric type <code class="computeroutput"><span class="identifier">T</span></code>. 370 </p> 371<p> 372 The set of representable values of type <code class="computeroutput"><span class="identifier">T</span></code>, 373 or numeric set of <code class="computeroutput"><span class="identifier">T</span></code>, is a 374 set of numeric values whose elements are the representation of some subset 375 of <code class="computeroutput"><span class="identifier">N</span></code>. 376 </p> 377<p> 378 For example, the interval of <code class="computeroutput"><span class="keyword">int</span></code> 379 values <code class="computeroutput"><span class="special">[</span><span class="identifier">INT_MIN</span><span class="special">,</span><span class="identifier">INT_MAX</span><span class="special">]</span></code> is the set of representable values of type 380 <code class="computeroutput"><span class="keyword">int</span></code>, i.e. the <code class="computeroutput"><span class="keyword">int</span></code> numeric set, and corresponds to the representation 381 of the elements of the interval of abstract values <code class="computeroutput"><span class="special">[</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">INT_MIN</span><span class="special">),</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">INT_MAX</span><span class="special">)]</span></code> 382 from the integer numbers. 383 </p> 384<p> 385 Similarly, the interval of <code class="computeroutput"><span class="keyword">double</span></code> 386 values <code class="computeroutput"><span class="special">[-</span><span class="identifier">DBL_MAX</span><span class="special">,</span><span class="identifier">DBL_MAX</span><span class="special">]</span></code> is the <code class="computeroutput"><span class="keyword">double</span></code> 387 numeric set, which corresponds to the subset of the real numbers from <code class="computeroutput"><span class="identifier">abt</span><span class="special">(-</span><span class="identifier">DBL_MAX</span><span class="special">)</span></code> to <code class="computeroutput"><span class="identifier">abt</span><span class="special">(</span><span class="identifier">DBL_MAX</span><span class="special">)</span></code>. 388 </p> 389<p> 390 <span class="inlinemediaobject"><img src="../images/space.png" alt="space"></span> 391 </p> 392<p> 393 Let <span class="bold"><strong><code class="computeroutput"><span class="identifier">next</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code></strong></span> 394 denote the lowest numeric value greater than x. 395 </p> 396<p> 397 Let <span class="bold"><strong><code class="computeroutput"><span class="identifier">prev</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span></code></strong></span> 398 denote the highest numeric value lower then x. 399 </p> 400<p> 401 Let <span class="bold"><strong><code class="computeroutput"><span class="identifier">v</span><span class="special">=</span><span class="identifier">prev</span><span class="special">(</span><span class="identifier">next</span><span class="special">(</span><span class="identifier">V</span><span class="special">))</span></code></strong></span> and <span class="bold"><strong><code class="computeroutput"><span class="identifier">v</span><span class="special">=</span><span class="identifier">next</span><span class="special">(</span><span class="identifier">prev</span><span class="special">(</span><span class="identifier">V</span><span class="special">))</span></code></strong></span> 402 be identities that relate a numeric typed value <code class="computeroutput"><span class="identifier">v</span></code> 403 with a number <code class="computeroutput"><span class="identifier">V</span></code>. 404 </p> 405<p> 406 An ordered pair of numeric values <code class="computeroutput"><span class="identifier">x</span></code>,<code class="computeroutput"><span class="identifier">y</span></code> s.t. <code class="computeroutput"><span class="identifier">x</span><span class="special"><</span><span class="identifier">y</span></code> are 407 <span class="bold"><strong>consecutive</strong></span> iff <code class="computeroutput"><span class="identifier">next</span><span class="special">(</span><span class="identifier">x</span><span class="special">)==</span><span class="identifier">y</span></code>. 408 </p> 409<p> 410 The abstract distance between consecutive numeric values is usually referred 411 to as a <span class="underline">Unit in the Last Place</span>, or 412 <span class="bold"><strong>ulp</strong></span> for short. A ulp is a quantity whose 413 abstract magnitude is relative to the numeric values it corresponds to: If 414 the numeric set is not evenly distributed, that is, if the abstract distance 415 between consecutive numeric values varies along the set -as is the case with 416 the floating-point types-, the magnitude of 1ulp after the numeric value 417 <code class="computeroutput"><span class="identifier">x</span></code> might be (usually is) different 418 from the magnitude of a 1ulp after the numeric value y for <code class="computeroutput"><span class="identifier">x</span><span class="special">!=</span><span class="identifier">y</span></code>. 419 </p> 420<p> 421 Since numbers are inherently ordered, a <span class="bold"><strong>numeric set</strong></span> 422 of type <code class="computeroutput"><span class="identifier">T</span></code> is an ordered sequence 423 of numeric values (of type <code class="computeroutput"><span class="identifier">T</span></code>) 424 of the form: 425 </p> 426<pre class="programlisting"><span class="identifier">REP</span><span class="special">(</span><span class="identifier">T</span><span class="special">)={</span><span class="identifier">l</span><span class="special">,</span><span class="identifier">next</span><span class="special">(</span><span class="identifier">l</span><span class="special">),</span><span class="identifier">next</span><span class="special">(</span><span class="identifier">next</span><span class="special">(</span><span class="identifier">l</span><span class="special">)),...,</span><span class="identifier">prev</span><span class="special">(</span><span class="identifier">prev</span><span class="special">(</span><span class="identifier">h</span><span class="special">)),</span><span class="identifier">prev</span><span class="special">(</span><span class="identifier">h</span><span class="special">),</span><span class="identifier">h</span><span class="special">}</span> 427</pre> 428<p> 429 where <code class="computeroutput"><span class="identifier">l</span></code> and <code class="computeroutput"><span class="identifier">h</span></code> are respectively the lowest and highest 430 values of type <code class="computeroutput"><span class="identifier">T</span></code>, called 431 the boundary values of type <code class="computeroutput"><span class="identifier">T</span></code>. 432 </p> 433<p> 434 <span class="inlinemediaobject"><img src="../images/space.png" alt="space"></span> 435 </p> 436<p> 437 A numeric set is discrete. It has a <span class="bold"><strong>size</strong></span> 438 which is the number of numeric values in the set, a <span class="bold"><strong>width</strong></span> 439 which is the abstract difference between the highest and lowest boundary 440 values: <code class="computeroutput"><span class="special">[</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)-</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">l</span><span class="special">)]</span></code>, and a <span class="bold"><strong>density</strong></span> 441 which is the relation between its size and width: <code class="computeroutput"><span class="identifier">density</span><span class="special">=</span><span class="identifier">size</span><span class="special">/</span><span class="identifier">width</span></code>. 442 </p> 443<p> 444 The integer types have density 1, which means that there are no unrepresentable 445 integer numbers between <code class="computeroutput"><span class="identifier">abt</span><span class="special">(</span><span class="identifier">l</span><span class="special">)</span></code> 446 and <code class="computeroutput"><span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span></code> (i.e. 447 there are no gaps). On the other hand, floating types have density much smaller 448 than 1, which means that there are real numbers unrepresented between consecutive 449 floating values (i.e. there are gaps). 450 </p> 451<p> 452 <span class="inlinemediaobject"><img src="../images/space.png" alt="space"></span> 453 </p> 454<p> 455 The interval of <span class="underline">abstract values</span> <code class="computeroutput"><span class="special">[</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">l</span><span class="special">),</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)]</span></code> 456 is the range of the type <code class="computeroutput"><span class="identifier">T</span></code>, 457 denoted <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span></code>. 458 </p> 459<p> 460 A range is a set of abstract values and not a set of numeric values. In other 461 documents, such as the C++ standard, the word <code class="computeroutput"><span class="identifier">range</span></code> 462 is <span class="emphasis"><em>sometimes</em></span> used as synonym for <code class="computeroutput"><span class="identifier">numeric</span> 463 <span class="identifier">set</span></code>, that is, as the ordered sequence 464 of numeric values from <code class="computeroutput"><span class="identifier">l</span></code> 465 to <code class="computeroutput"><span class="identifier">h</span></code>. In this document, however, 466 a range is an abstract interval which subtends the numeric set. 467 </p> 468<p> 469 For example, the sequence <code class="computeroutput"><span class="special">[-</span><span class="identifier">DBL_MAX</span><span class="special">,</span><span class="identifier">DBL_MAX</span><span class="special">]</span></code> 470 is the numeric set of the type <code class="computeroutput"><span class="keyword">double</span></code>, 471 and the real interval <code class="computeroutput"><span class="special">[</span><span class="identifier">abt</span><span class="special">(-</span><span class="identifier">DBL_MAX</span><span class="special">),</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">DBL_MAX</span><span class="special">)]</span></code> 472 is its range. 473 </p> 474<p> 475 Notice, for instance, that the range of a floating-point type is <span class="emphasis"><em>continuous</em></span> 476 unlike its numeric set. 477 </p> 478<p> 479 This definition was chosen because: 480 </p> 481<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 482<li class="listitem"> 483 <span class="bold"><strong>(a)</strong></span> The discrete set of numeric values 484 is already given by the numeric set. 485 </li> 486<li class="listitem"> 487 <span class="bold"><strong>(b)</strong></span> Abstract intervals are easier to 488 compare and overlap since only boundary values need to be considered. 489 </li> 490</ul></div> 491<p> 492 This definition allows for a concise definition of <code class="computeroutput"><span class="identifier">subranged</span></code> 493 as given in the last section. 494 </p> 495<p> 496 The width of a numeric set, as defined, is exactly equivalent to the width 497 of a range. 498 </p> 499<p> 500 <span class="inlinemediaobject"><img src="../images/space.png" alt="space"></span> 501 </p> 502<p> 503 The <span class="bold"><strong>precision</strong></span> of a type is given by the 504 width or density of the numeric set. 505 </p> 506<p> 507 For integer types, which have density 1, the precision is conceptually equivalent 508 to the range and is determined by the number of bits used in the value representation: 509 The higher the number of bits the bigger the size of the numeric set, the 510 wider the range, and the higher the precision. 511 </p> 512<p> 513 For floating types, which have density <<1, the precision is given 514 not by the width of the range but by the density. In a typical implementation, 515 the range is determined by the number of bits used in the exponent, and the 516 precision by the number of bits used in the mantissa (giving the maximum 517 number of significant digits that can be exactly represented). The higher 518 the number of exponent bits the wider the range, while the higher the number 519 of mantissa bits, the higher the precision. 520 </p> 521</div> 522<div class="section"> 523<div class="titlepage"><div><div><h3 class="title"> 524<a name="boost_numericconversion.definitions.exact__correctly_rounded_and_out_of_range_representations"></a><a class="link" href="definitions.html#boost_numericconversion.definitions.exact__correctly_rounded_and_out_of_range_representations" title="Exact, Correctly Rounded and Out-Of-Range Representations">Exact, 525 Correctly Rounded and Out-Of-Range Representations</a> 526</h3></div></div></div> 527<p> 528 Given an abstract value <code class="computeroutput"><span class="identifier">V</span></code> 529 and a type <code class="computeroutput"><span class="identifier">T</span></code> with its corresponding 530 range <code class="computeroutput"><span class="special">[</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">l</span><span class="special">),</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)]</span></code>: 531 </p> 532<p> 533 If <code class="computeroutput"><span class="identifier">V</span> <span class="special"><</span> 534 <span class="identifier">abt</span><span class="special">(</span><span class="identifier">l</span><span class="special">)</span></code> or 535 <code class="computeroutput"><span class="identifier">V</span> <span class="special">></span> 536 <span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span></code>, <code class="computeroutput"><span class="identifier">V</span></code> is <span class="bold"><strong>not representable</strong></span> 537 (cannot be represented) in the type <code class="computeroutput"><span class="identifier">T</span></code>, 538 or, equivalently, it's representation in the type <code class="computeroutput"><span class="identifier">T</span></code> 539 is <span class="bold"><strong>out of range</strong></span>, or <span class="bold"><strong>overflows</strong></span>. 540 </p> 541<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 542<li class="listitem"> 543 If <code class="computeroutput"><span class="identifier">V</span> <span class="special"><</span> 544 <span class="identifier">abt</span><span class="special">(</span><span class="identifier">l</span><span class="special">)</span></code>, 545 the <span class="bold"><strong>overflow is negative</strong></span>. 546 </li> 547<li class="listitem"> 548 If <code class="computeroutput"><span class="identifier">V</span> <span class="special">></span> 549 <span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span></code>, 550 the <span class="bold"><strong>overflow is positive</strong></span>. 551 </li> 552</ul></div> 553<p> 554 If <code class="computeroutput"><span class="identifier">V</span> <span class="special">>=</span> 555 <span class="identifier">abt</span><span class="special">(</span><span class="identifier">l</span><span class="special">)</span></code> and 556 <code class="computeroutput"><span class="identifier">V</span> <span class="special"><=</span> 557 <span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span></code>, <code class="computeroutput"><span class="identifier">V</span></code> is <span class="bold"><strong>representable</strong></span> 558 (can be represented) in the type <code class="computeroutput"><span class="identifier">T</span></code>, 559 or, equivalently, its representation in the type <code class="computeroutput"><span class="identifier">T</span></code> 560 is <span class="bold"><strong>in range</strong></span>, or <span class="bold"><strong>does 561 not overflow</strong></span>. 562 </p> 563<p> 564 Notice that a numeric type, such as a C++ unsigned type, can define that 565 any <code class="computeroutput"><span class="identifier">V</span></code> does not overflow by 566 always representing not <code class="computeroutput"><span class="identifier">V</span></code> 567 itself but the abstract value <code class="computeroutput"><span class="identifier">U</span> 568 <span class="special">=</span> <span class="special">[</span> <span class="identifier">V</span> <span class="special">%</span> <span class="special">(</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)+</span><span class="number">1</span><span class="special">)</span> 569 <span class="special">]</span></code>, which is always in range. 570 </p> 571<p> 572 Given an abstract value <code class="computeroutput"><span class="identifier">V</span></code> 573 represented in the type <code class="computeroutput"><span class="identifier">T</span></code> 574 as <code class="computeroutput"><span class="identifier">v</span></code>, the <span class="bold"><strong>roundoff</strong></span> 575 error of the representation is the abstract difference: <code class="computeroutput"><span class="special">(</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">v</span><span class="special">)-</span><span class="identifier">V</span><span class="special">)</span></code>. 576 </p> 577<p> 578 Notice that a representation is an <span class="emphasis"><em>operation</em></span>, hence, 579 the roundoff error corresponds to the representation operation and not to 580 the numeric value itself (i.e. numeric values do not have any error themselves) 581 </p> 582<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 583<li class="listitem"> 584 If the roundoff is 0, the representation is <span class="bold"><strong>exact</strong></span>, 585 and <code class="computeroutput"><span class="identifier">V</span></code> is exactly representable 586 in the type <code class="computeroutput"><span class="identifier">T</span></code>. 587 </li> 588<li class="listitem"> 589 If the roundoff is not 0, the representation is <span class="bold"><strong>inexact</strong></span>, 590 and <code class="computeroutput"><span class="identifier">V</span></code> is inexactly representable 591 in the type <code class="computeroutput"><span class="identifier">T</span></code>. 592 </li> 593</ul></div> 594<p> 595 If a representation <code class="computeroutput"><span class="identifier">v</span></code> in 596 a type <code class="computeroutput"><span class="identifier">T</span></code> -either exact or 597 inexact-, is any of the adjacents of <code class="computeroutput"><span class="identifier">V</span></code> 598 in that type, that is, if <code class="computeroutput"><span class="identifier">v</span><span class="special">==</span><span class="identifier">prev</span></code> 599 or <code class="computeroutput"><span class="identifier">v</span><span class="special">==</span><span class="identifier">next</span></code>, the representation is faithfully 600 rounded. If the choice between <code class="computeroutput"><span class="identifier">prev</span></code> 601 and <code class="computeroutput"><span class="identifier">next</span></code> matches a given 602 <span class="bold"><strong>rounding direction</strong></span>, it is <span class="bold"><strong>correctly 603 rounded</strong></span>. 604 </p> 605<p> 606 All exact representations are correctly rounded, but not all inexact representations 607 are. In particular, C++ requires numeric conversions (described below) and 608 the result of arithmetic operations (not covered by this document) to be 609 correctly rounded, but batch operations propagate roundoff, thus final results 610 are usually incorrectly rounded, that is, the numeric value <code class="computeroutput"><span class="identifier">r</span></code> which is the computed result is neither 611 of the adjacents of the abstract value <code class="computeroutput"><span class="identifier">R</span></code> 612 which is the theoretical result. 613 </p> 614<p> 615 Because a correctly rounded representation is always one of adjacents of 616 the abstract value being represented, the roundoff is guaranteed to be at 617 most 1ulp. 618 </p> 619<p> 620 The following examples summarize the given definitions. Consider: 621 </p> 622<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 623<li class="listitem"> 624 A numeric type <code class="computeroutput"><span class="identifier">Int</span></code> representing 625 integer numbers with a <span class="emphasis"><em>numeric set</em></span>: <code class="computeroutput"><span class="special">{-</span><span class="number">2</span><span class="special">,-</span><span class="number">1</span><span class="special">,</span><span class="number">0</span><span class="special">,</span><span class="number">1</span><span class="special">,</span><span class="number">2</span><span class="special">}</span></code> and 626 <span class="emphasis"><em>range</em></span>: <code class="computeroutput"><span class="special">[-</span><span class="number">2</span><span class="special">,</span><span class="number">2</span><span class="special">]</span></code> 627 </li> 628<li class="listitem"> 629 A numeric type <code class="computeroutput"><span class="identifier">Cardinal</span></code> 630 representing integer numbers with a <span class="emphasis"><em>numeric set</em></span>: 631 <code class="computeroutput"><span class="special">{</span><span class="number">0</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="number">3</span><span class="special">,</span><span class="number">4</span><span class="special">,</span><span class="number">5</span><span class="special">,</span><span class="number">6</span><span class="special">,</span><span class="number">7</span><span class="special">,</span><span class="number">8</span><span class="special">,</span><span class="number">9</span><span class="special">}</span></code> and <span class="emphasis"><em>range</em></span>: <code class="computeroutput"><span class="special">[</span><span class="number">0</span><span class="special">,</span><span class="number">9</span><span class="special">]</span></code> (no 632 modulo-arithmetic here) 633 </li> 634<li class="listitem"> 635 A numeric type <code class="computeroutput"><span class="identifier">Real</span></code> representing 636 real numbers with a <span class="emphasis"><em>numeric set</em></span>: <code class="computeroutput"><span class="special">{-</span><span class="number">2.0</span><span class="special">,-</span><span class="number">1.5</span><span class="special">,-</span><span class="number">1.0</span><span class="special">,-</span><span class="number">0.5</span><span class="special">,-</span><span class="number">0.0</span><span class="special">,+</span><span class="number">0.0</span><span class="special">,+</span><span class="number">0.5</span><span class="special">,+</span><span class="number">1.0</span><span class="special">,+</span><span class="number">1.5</span><span class="special">,+</span><span class="number">2.0</span><span class="special">}</span></code> and 637 <span class="emphasis"><em>range</em></span>: <code class="computeroutput"><span class="special">[-</span><span class="number">2.0</span><span class="special">,+</span><span class="number">2.0</span><span class="special">]</span></code> 638 </li> 639<li class="listitem"> 640 A numeric type <code class="computeroutput"><span class="identifier">Whole</span></code> 641 representing real numbers with a <span class="emphasis"><em>numeric set</em></span>: <code class="computeroutput"><span class="special">{-</span><span class="number">2.0</span><span class="special">,-</span><span class="number">1.0</span><span class="special">,</span><span class="number">0.0</span><span class="special">,+</span><span class="number">1.0</span><span class="special">,+</span><span class="number">2.0</span><span class="special">}</span></code> and 642 <span class="emphasis"><em>range</em></span>: <code class="computeroutput"><span class="special">[-</span><span class="number">2.0</span><span class="special">,+</span><span class="number">2.0</span><span class="special">]</span></code> 643 </li> 644</ul></div> 645<p> 646 First, notice that the types <code class="computeroutput"><span class="identifier">Real</span></code> 647 and <code class="computeroutput"><span class="identifier">Whole</span></code> both represent 648 real numbers, have the same range, but different precision. 649 </p> 650<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 651<li class="listitem"> 652 The integer number <code class="computeroutput"><span class="number">1</span></code> (an 653 abstract value) can be exactly represented in any of these types. 654 </li> 655<li class="listitem"> 656 The integer number <code class="computeroutput"><span class="special">-</span><span class="number">1</span></code> 657 can be exactly represented in <code class="computeroutput"><span class="identifier">Int</span></code>, 658 <code class="computeroutput"><span class="identifier">Real</span></code> and <code class="computeroutput"><span class="identifier">Whole</span></code>, but cannot be represented in 659 <code class="computeroutput"><span class="identifier">Cardinal</span></code>, yielding negative 660 overflow. 661 </li> 662<li class="listitem"> 663 The real number <code class="computeroutput"><span class="number">1.5</span></code> can be 664 exactly represented in <code class="computeroutput"><span class="identifier">Real</span></code>, 665 and inexactly represented in the other types. 666 </li> 667<li class="listitem"> 668 If <code class="computeroutput"><span class="number">1.5</span></code> is represented as 669 either <code class="computeroutput"><span class="number">1</span></code> or <code class="computeroutput"><span class="number">2</span></code> in any of the types (except <code class="computeroutput"><span class="identifier">Real</span></code>), the representation is correctly 670 rounded. 671 </li> 672<li class="listitem"> 673 If <code class="computeroutput"><span class="number">0.5</span></code> is represented as 674 <code class="computeroutput"><span class="special">+</span><span class="number">1.5</span></code> 675 in the type <code class="computeroutput"><span class="identifier">Real</span></code>, it 676 is incorrectly rounded. 677 </li> 678<li class="listitem"> 679 <code class="computeroutput"><span class="special">(-</span><span class="number">2.0</span><span class="special">,-</span><span class="number">1.5</span><span class="special">)</span></code> 680 are the <code class="computeroutput"><span class="identifier">Real</span></code> adjacents 681 of any real number in the interval <code class="computeroutput"><span class="special">[-</span><span class="number">2.0</span><span class="special">,-</span><span class="number">1.5</span><span class="special">]</span></code>, yet there are no <code class="computeroutput"><span class="identifier">Real</span></code> 682 adjacents for <code class="computeroutput"><span class="identifier">x</span> <span class="special"><</span> 683 <span class="special">-</span><span class="number">2.0</span></code>, 684 nor for <code class="computeroutput"><span class="identifier">x</span> <span class="special">></span> 685 <span class="special">+</span><span class="number">2.0</span></code>. 686 </li> 687</ul></div> 688</div> 689<div class="section"> 690<div class="titlepage"><div><div><h3 class="title"> 691<a name="boost_numericconversion.definitions.standard__numeric__conversions"></a><a class="link" href="definitions.html#boost_numericconversion.definitions.standard__numeric__conversions" title="Standard (numeric) Conversions">Standard 692 (numeric) Conversions</a> 693</h3></div></div></div> 694<p> 695 The C++ language defines <span class="underline">Standard Conversions</span> 696 (§4) some of which are conversions between arithmetic types. 697 </p> 698<p> 699 These are <span class="underline">Integral promotions</span> (§4.5), 700 <span class="underline">Integral conversions</span> (§4.7), <span class="underline">Floating point promotions</span> (§4.6), <span class="underline">Floating point conversions</span> (§4.8) and <span class="underline">Floating-integral conversions</span> (§4.9). 701 </p> 702<p> 703 In the sequel, integral and floating point promotions are called <span class="bold"><strong>arithmetic promotions</strong></span>, and these plus integral, floating-point 704 and floating-integral conversions are called <span class="bold"><strong>arithmetic 705 conversions</strong></span> (i.e, promotions are conversions). 706 </p> 707<p> 708 Promotions, both Integral and Floating point, are <span class="emphasis"><em>value-preserving</em></span>, 709 which means that the typed value is not changed with the conversion. 710 </p> 711<p> 712 In the sequel, consider a source typed value <code class="computeroutput"><span class="identifier">s</span></code> 713 of type <code class="computeroutput"><span class="identifier">S</span></code>, the source abstract 714 value <code class="computeroutput"><span class="identifier">N</span><span class="special">=</span><span class="identifier">abt</span><span class="special">(</span><span class="identifier">s</span><span class="special">)</span></code>, a destination type <code class="computeroutput"><span class="identifier">T</span></code>; 715 and whenever possible, a result typed value <code class="computeroutput"><span class="identifier">t</span></code> 716 of type <code class="computeroutput"><span class="identifier">T</span></code>. 717 </p> 718<p> 719 Integer to integer conversions are always defined: 720 </p> 721<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 722<li class="listitem"> 723 If <code class="computeroutput"><span class="identifier">T</span></code> is unsigned, the 724 abstract value which is effectively represented is not <code class="computeroutput"><span class="identifier">N</span></code> but <code class="computeroutput"><span class="identifier">M</span><span class="special">=[</span> <span class="identifier">N</span> <span class="special">%</span> <span class="special">(</span> <span class="identifier">abt</span><span class="special">(</span><span class="identifier">h</span><span class="special">)</span> <span class="special">+</span> <span class="number">1</span> 725 <span class="special">)</span> <span class="special">]</span></code>, 726 where <code class="computeroutput"><span class="identifier">h</span></code> is the highest 727 unsigned typed value of type <code class="computeroutput"><span class="identifier">T</span></code>. 728 </li> 729<li class="listitem"> 730 If <code class="computeroutput"><span class="identifier">T</span></code> is signed and <code class="computeroutput"><span class="identifier">N</span></code> is not directly representable, the 731 result <code class="computeroutput"><span class="identifier">t</span></code> is <span class="underline">implementation-defined</span>, which means that 732 the C++ implementation is required to produce a value <code class="computeroutput"><span class="identifier">t</span></code> 733 even if it is totally unrelated to <code class="computeroutput"><span class="identifier">s</span></code>. 734 </li> 735</ul></div> 736<p> 737 Floating to Floating conversions are defined only if <code class="computeroutput"><span class="identifier">N</span></code> 738 is representable; if it is not, the conversion has <span class="underline">undefined 739 behavior</span>. 740 </p> 741<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 742<li class="listitem"> 743 If <code class="computeroutput"><span class="identifier">N</span></code> is exactly representable, 744 <code class="computeroutput"><span class="identifier">t</span></code> is required to be the 745 exact representation. 746 </li> 747<li class="listitem"> 748 If <code class="computeroutput"><span class="identifier">N</span></code> is inexactly representable, 749 <code class="computeroutput"><span class="identifier">t</span></code> is required to be one 750 of the two adjacents, with an implementation-defined choice of rounding 751 direction; that is, the conversion is required to be correctly rounded. 752 </li> 753</ul></div> 754<p> 755 Floating to Integer conversions represent not <code class="computeroutput"><span class="identifier">N</span></code> 756 but <code class="computeroutput"><span class="identifier">M</span><span class="special">=</span><span class="identifier">trunc</span><span class="special">(</span><span class="identifier">N</span><span class="special">)</span></code>, were 757 <code class="computeroutput"><span class="identifier">trunc</span><span class="special">()</span></code> 758 is to truncate: i.e. to remove the fractional part, if any. 759 </p> 760<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"> 761 If <code class="computeroutput"><span class="identifier">M</span></code> is not representable 762 in <code class="computeroutput"><span class="identifier">T</span></code>, the conversion 763 has <span class="underline">undefined behavior</span> (unless 764 <code class="computeroutput"><span class="identifier">T</span></code> is <code class="computeroutput"><span class="keyword">bool</span></code>, 765 see §4.12). 766 </li></ul></div> 767<p> 768 Integer to Floating conversions are always defined. 769 </p> 770<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 771<li class="listitem"> 772 If <code class="computeroutput"><span class="identifier">N</span></code> is exactly representable, 773 <code class="computeroutput"><span class="identifier">t</span></code> is required to be the 774 exact representation. 775 </li> 776<li class="listitem"> 777 If <code class="computeroutput"><span class="identifier">N</span></code> is inexactly representable, 778 <code class="computeroutput"><span class="identifier">t</span></code> is required to be one 779 of the two adjacents, with an implementation-defined choice of rounding 780 direction; that is, the conversion is required to be correctly rounded. 781 </li> 782</ul></div> 783</div> 784<div class="section"> 785<div class="titlepage"><div><div><h3 class="title"> 786<a name="boost_numericconversion.definitions.subranged_conversion_direction__subtype_and_supertype"></a><a class="link" href="definitions.html#boost_numericconversion.definitions.subranged_conversion_direction__subtype_and_supertype" title="Subranged Conversion Direction, Subtype and Supertype">Subranged 787 Conversion Direction, Subtype and Supertype</a> 788</h3></div></div></div> 789<p> 790 Given a source type <code class="computeroutput"><span class="identifier">S</span></code> and 791 a destination type <code class="computeroutput"><span class="identifier">T</span></code>, there 792 is a <span class="bold"><strong>conversion direction</strong></span> denoted: <code class="computeroutput"><span class="identifier">S</span><span class="special">-></span><span class="identifier">T</span></code>. 793 </p> 794<p> 795 For any two ranges the following <span class="emphasis"><em>range relation</em></span> can 796 be defined: A range <code class="computeroutput"><span class="identifier">X</span></code> can 797 be <span class="emphasis"><em>entirely contained</em></span> in a range <code class="computeroutput"><span class="identifier">Y</span></code>, 798 in which case it is said that <code class="computeroutput"><span class="identifier">X</span></code> 799 is enclosed by <code class="computeroutput"><span class="identifier">Y</span></code>. 800 </p> 801<div class="blockquote"><blockquote class="blockquote"><p> 802 <span class="bold"><strong>Formally:</strong></span> <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span></code> 803 is enclosed by <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span></code> iif 804 <code class="computeroutput"><span class="special">(</span><span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span> 805 <span class="identifier">intersection</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">T</span><span class="special">))</span> 806 <span class="special">==</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span></code>. 807 </p></blockquote></div> 808<p> 809 If the source type range, <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span></code>, 810 is not enclosed in the target type range, <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span></code>; 811 that is, if <code class="computeroutput"><span class="special">(</span><span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span> 812 <span class="special">&</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">T</span><span class="special">))</span> 813 <span class="special">!=</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span></code>, 814 the conversion direction is said to be <span class="bold"><strong>subranged</strong></span>, 815 which means that <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span></code> is not 816 entirely contained in <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span></code> and 817 therefore there is some portion of the source range which falls outside the 818 target range. In other words, if a conversion direction <code class="computeroutput"><span class="identifier">S</span><span class="special">-></span><span class="identifier">T</span></code> 819 is subranged, there are values in <code class="computeroutput"><span class="identifier">S</span></code> 820 which cannot be represented in <code class="computeroutput"><span class="identifier">T</span></code> 821 because they are out of range. Notice that for <code class="computeroutput"><span class="identifier">S</span><span class="special">-></span><span class="identifier">T</span></code>, 822 the adjective subranged applies to <code class="computeroutput"><span class="identifier">T</span></code>. 823 </p> 824<p> 825 Examples: 826 </p> 827<p> 828 Given the following numeric types all representing real numbers: 829 </p> 830<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 831<li class="listitem"> 832 <code class="computeroutput"><span class="identifier">X</span></code> with numeric set <code class="computeroutput"><span class="special">{-</span><span class="number">2.0</span><span class="special">,-</span><span class="number">1.0</span><span class="special">,</span><span class="number">0.0</span><span class="special">,+</span><span class="number">1.0</span><span class="special">,+</span><span class="number">2.0</span><span class="special">}</span></code> and 833 range <code class="computeroutput"><span class="special">[-</span><span class="number">2.0</span><span class="special">,+</span><span class="number">2.0</span><span class="special">]</span></code> 834 </li> 835<li class="listitem"> 836 <code class="computeroutput"><span class="identifier">Y</span></code> with numeric set <code class="computeroutput"><span class="special">{-</span><span class="number">2.0</span><span class="special">,-</span><span class="number">1.5</span><span class="special">,-</span><span class="number">1.0</span><span class="special">,-</span><span class="number">0.5</span><span class="special">,</span><span class="number">0.0</span><span class="special">,+</span><span class="number">0.5</span><span class="special">,+</span><span class="number">1.0</span><span class="special">,+</span><span class="number">1.5</span><span class="special">,+</span><span class="number">2.0</span><span class="special">}</span></code> and range <code class="computeroutput"><span class="special">[-</span><span class="number">2.0</span><span class="special">,+</span><span class="number">2.0</span><span class="special">]</span></code> 837 </li> 838<li class="listitem"> 839 <code class="computeroutput"><span class="identifier">Z</span></code> with numeric set <code class="computeroutput"><span class="special">{-</span><span class="number">1.0</span><span class="special">,</span><span class="number">0.0</span><span class="special">,+</span><span class="number">1.0</span><span class="special">}</span></code> and range <code class="computeroutput"><span class="special">[-</span><span class="number">1.0</span><span class="special">,+</span><span class="number">1.0</span><span class="special">]</span></code> 840 </li> 841</ul></div> 842<p> 843 For: 844 </p> 845<div class="variablelist"> 846<p class="title"><b></b></p> 847<dl class="variablelist"> 848<dt><span class="term">(a) X->Y:</span></dt> 849<dd><p> 850 <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">X</span><span class="special">)</span> <span class="special">&</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">Y</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">X</span><span class="special">)</span></code>, 851 then <code class="computeroutput"><span class="identifier">X</span><span class="special">-></span><span class="identifier">Y</span></code> is not subranged. Thus, all values 852 of type <code class="computeroutput"><span class="identifier">X</span></code> are representable 853 in the type <code class="computeroutput"><span class="identifier">Y</span></code>. 854 </p></dd> 855<dt><span class="term">(b) Y->X:</span></dt> 856<dd><p> 857 <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">Y</span><span class="special">)</span> <span class="special">&</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">X</span><span class="special">)</span> <span class="special">==</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">Y</span><span class="special">)</span></code>, 858 then <code class="computeroutput"><span class="identifier">Y</span><span class="special">-></span><span class="identifier">X</span></code> is not subranged. Thus, all values 859 of type <code class="computeroutput"><span class="identifier">Y</span></code> are representable 860 in the type <code class="computeroutput"><span class="identifier">X</span></code>, but 861 in this case, some values are <span class="emphasis"><em>inexactly</em></span> representable 862 (all the halves). (note: it is to permit this case that a range is 863 an interval of abstract values and not an interval of typed values) 864 </p></dd> 865<dt><span class="term">(b) X->Z:</span></dt> 866<dd><p> 867 <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">X</span><span class="special">)</span> <span class="special">&</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">Z</span><span class="special">)</span> <span class="special">!=</span> <span class="identifier">R</span><span class="special">(</span><span class="identifier">X</span><span class="special">)</span></code>, 868 then <code class="computeroutput"><span class="identifier">X</span><span class="special">-></span><span class="identifier">Z</span></code> is subranged. Thus, some values 869 of type <code class="computeroutput"><span class="identifier">X</span></code> are not representable 870 in the type <code class="computeroutput"><span class="identifier">Z</span></code>, they 871 fall out of range <code class="computeroutput"><span class="special">(-</span><span class="number">2.0</span> 872 <span class="keyword">and</span> <span class="special">+</span><span class="number">2.0</span><span class="special">)</span></code>. 873 </p></dd> 874</dl> 875</div> 876<p> 877 It is possible that <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span></code> is not 878 enclosed by <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span></code>, while 879 neither is <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">T</span><span class="special">)</span></code> enclosed 880 by <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="identifier">S</span><span class="special">)</span></code>; for 881 example, <code class="computeroutput"><span class="identifier">UNSIG</span><span class="special">=[</span><span class="number">0</span><span class="special">,</span><span class="number">255</span><span class="special">]</span></code> is not enclosed by <code class="computeroutput"><span class="identifier">SIG</span><span class="special">=[-</span><span class="number">128</span><span class="special">,</span><span class="number">127</span><span class="special">]</span></code>; neither 882 is <code class="computeroutput"><span class="identifier">SIG</span></code> enclosed by <code class="computeroutput"><span class="identifier">UNSIG</span></code>. This implies that is possible that 883 a conversion direction is subranged both ways. This occurs when a mixture 884 of signed/unsigned types are involved and indicates that in both directions 885 there are values which can fall out of range. 886 </p> 887<p> 888 Given the range relation (subranged or not) of a conversion direction <code class="computeroutput"><span class="identifier">S</span><span class="special">-></span><span class="identifier">T</span></code>, it is possible to classify <code class="computeroutput"><span class="identifier">S</span></code> and <code class="computeroutput"><span class="identifier">T</span></code> 889 as <span class="bold"><strong>supertype</strong></span> and <span class="bold"><strong>subtype</strong></span>: 890 If the conversion is subranged, which means that <code class="computeroutput"><span class="identifier">T</span></code> 891 cannot represent all possible values of type <code class="computeroutput"><span class="identifier">S</span></code>, 892 <code class="computeroutput"><span class="identifier">S</span></code> is the supertype and <code class="computeroutput"><span class="identifier">T</span></code> the subtype; otherwise, <code class="computeroutput"><span class="identifier">T</span></code> is the supertype and <code class="computeroutput"><span class="identifier">S</span></code> 893 the subtype. 894 </p> 895<p> 896 For example: 897 </p> 898<div class="blockquote"><blockquote class="blockquote"><p> 899 <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="keyword">float</span><span class="special">)=[-</span><span class="identifier">FLT_MAX</span><span class="special">,</span><span class="identifier">FLT_MAX</span><span class="special">]</span></code> 900 and <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="keyword">double</span><span class="special">)=[-</span><span class="identifier">DBL_MAX</span><span class="special">,</span><span class="identifier">DBL_MAX</span><span class="special">]</span></code> 901 </p></blockquote></div> 902<p> 903 If <code class="computeroutput"><span class="identifier">FLT_MAX</span> <span class="special"><</span> 904 <span class="identifier">DBL_MAX</span></code>: 905 </p> 906<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 907<li class="listitem"> 908 <code class="computeroutput"><span class="keyword">double</span><span class="special">-></span><span class="keyword">float</span></code> is subranged and <code class="computeroutput"><span class="identifier">supertype</span><span class="special">=</span><span class="keyword">double</span></code>, 909 <code class="computeroutput"><span class="identifier">subtype</span><span class="special">=</span><span class="keyword">float</span></code>. 910 </li> 911<li class="listitem"> 912 <code class="computeroutput"><span class="keyword">float</span><span class="special">-></span><span class="keyword">double</span></code> is not subranged and <code class="computeroutput"><span class="identifier">supertype</span><span class="special">=</span><span class="keyword">double</span></code>, <code class="computeroutput"><span class="identifier">subtype</span><span class="special">=</span><span class="keyword">float</span></code>. 913 </li> 914</ul></div> 915<p> 916 Notice that while <code class="computeroutput"><span class="keyword">double</span><span class="special">-></span><span class="keyword">float</span></code> is subranged, <code class="computeroutput"><span class="keyword">float</span><span class="special">-></span><span class="keyword">double</span></code> 917 is not, which yields the same supertype,subtype for both directions. 918 </p> 919<p> 920 Now consider: 921 </p> 922<div class="blockquote"><blockquote class="blockquote"><p> 923 <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="keyword">int</span><span class="special">)=[</span><span class="identifier">INT_MIN</span><span class="special">,</span><span class="identifier">INT_MAX</span><span class="special">]</span></code> and <code class="computeroutput"><span class="identifier">R</span><span class="special">(</span><span class="keyword">unsigned</span> <span class="keyword">int</span><span class="special">)=[</span><span class="number">0</span><span class="special">,</span><span class="identifier">UINT_MAX</span><span class="special">]</span></code> 924 </p></blockquote></div> 925<p> 926 A C++ implementation is required to have <code class="computeroutput"><span class="identifier">UINT_MAX</span> 927 <span class="special">></span> <span class="identifier">INT_MAX</span></code> 928 (§3.9/3), so: 929 </p> 930<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "> 931<li class="listitem"> 932 'int->unsigned' is subranged (negative values fall out of range) and 933 <code class="computeroutput"><span class="identifier">supertype</span><span class="special">=</span><span class="keyword">int</span></code>, <code class="computeroutput"><span class="identifier">subtype</span><span class="special">=</span><span class="keyword">unsigned</span></code>. 934 </li> 935<li class="listitem"> 936 'unsigned->int' is <span class="emphasis"><em>also</em></span> subranged (high positive 937 values fall out of range) and <code class="computeroutput"><span class="identifier">supertype</span><span class="special">=</span><span class="keyword">unsigned</span></code>, 938 <code class="computeroutput"><span class="identifier">subtype</span><span class="special">=</span><span class="keyword">int</span></code>. 939 </li> 940</ul></div> 941<p> 942 In this case, the conversion is subranged in both directions and the supertype,subtype 943 pairs are not invariant (under inversion of direction). This indicates that 944 none of the types can represent all the values of the other. 945 </p> 946<p> 947 When the supertype is the same for both <code class="computeroutput"><span class="identifier">S</span><span class="special">-></span><span class="identifier">T</span></code> 948 and <code class="computeroutput"><span class="identifier">T</span><span class="special">-></span><span class="identifier">S</span></code>, it is effectively indicating a type 949 which can represent all the values of the subtype. Consequently, if a conversion 950 <code class="computeroutput"><span class="identifier">X</span><span class="special">-></span><span class="identifier">Y</span></code> is not subranged, but the opposite <code class="computeroutput"><span class="special">(</span><span class="identifier">Y</span><span class="special">-></span><span class="identifier">X</span><span class="special">)</span></code> is, 951 so that the supertype is always <code class="computeroutput"><span class="identifier">Y</span></code>, 952 it is said that the direction <code class="computeroutput"><span class="identifier">X</span><span class="special">-></span><span class="identifier">Y</span></code> 953 is <span class="bold"><strong>correctly rounded value preserving</strong></span>, meaning 954 that all such conversions are guaranteed to produce results in range and 955 correctly rounded (even if inexact). For example, all integer to floating 956 conversions are correctly rounded value preserving. 957 </p> 958</div> 959</div> 960<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr> 961<td align="left"></td> 962<td align="right"><div class="copyright-footer">Copyright © 2004-2007 Fernando 963 Luis Cacciola Carballal<p> 964 Distributed under the Boost Software License, Version 1.0. (See accompanying 965 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>) 966 </p> 967</div></td> 968</tr></table> 969<hr> 970<div class="spirit-nav"> 971<a accesskey="p" href="../index.html"><img src="../../../../../../doc/src/images/prev.png" alt="Prev"></a><a accesskey="u" href="../index.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="converter___function_object.html"><img src="../../../../../../doc/src/images/next.png" alt="Next"></a> 972</div> 973</body> 974</html> 975
