]> git.proxmox.com Git - ceph.git/blame - ceph/src/boost/libs/numeric/conversion/doc/html/boost_numericconversion/definitions.html
projects / ceph.git / blame
? search:
summary | shortlog | log | commit | commitdiff | tree
blob | blame (incremental) | history | HEAD
bump version to 12.2.2-pve1
[ceph.git] / ceph / src / boost / libs / numeric / conversion / doc / html / boost_numericconversion / definitions.html
CommitLineData
7c673cae
FG		 1<html>
2<head>
3<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
4<title>Definitions</title>
5<link rel="stylesheet" href="../boostbook.css" type="text/css">
6<meta name="generator" content="DocBook XSL Stylesheets V1.78.1">
7<link rel="home" href="../index.html" title="Chapter&#160;1.&#160;Boost.NumericConversion">
8<link rel="up" href="../index.html" title="Chapter&#160;1.&#160;Boost.NumericConversion">
9<link rel="prev" href="../index.html" title="Chapter&#160;1.&#160;Boost.NumericConversion">
10<link rel="next" href="converter___function_object.html" title="converter&lt;&gt; 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="sidebar">
55<div class="titlepage"></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 (&#167;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 (&#167;1.8)
79 and has a type (&#167;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 (&#167;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 (&#167;3.9/4). For <span class="underline">POD</span> types (&#167;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 &#960;).
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 &#960; 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 (&#167;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> (&#167;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> (&#167;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> (&#167;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> (&#167;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> (&#167;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 &#167;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">&lt;&gt;</span> <span class="identifier">numeric_limits</span><span class="special">&lt;</span><span class="identifier">MyInt</span><span class="special">&gt;</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">&lt;</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 &lt;&lt;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">&lt;</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">&gt;</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">&lt;</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">&gt;</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">&gt;=</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">&lt;=</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">&lt;</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">&gt;</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 (&#167;4) some of which are conversions between arithmetic types.
697 </p>
698<p>
699 These are <span class="underline">Integral promotions</span> (&#167;4.5),
700 <span class="underline">Integral conversions</span> (&#167;4.7), <span class="underline">Floating point promotions</span> (&#167;4.6), <span class="underline">Floating point conversions</span> (&#167;4.8) and <span class="underline">Floating-integral conversions</span> (&#167;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 &#167;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">-&gt;</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">&amp;</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">-&gt;</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">-&gt;</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-&gt;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">&amp;</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">-&gt;</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-&gt;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">&amp;</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">-&gt;</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-&gt;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">&amp;</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">-&gt;</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">-&gt;</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">&lt;</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">-&gt;</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">-&gt;</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">-&gt;</span><span class="keyword">float</span></code> is subranged, <code class="computeroutput"><span class="keyword">float</span><span class="special">-&gt;</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">&gt;</span> <span class="identifier">INT_MAX</span></code>
928 (&#167;3.9/3), so:
929 </p>
930<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
931<li class="listitem">
932 'int-&gt;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-&gt;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">-&gt;</span><span class="identifier">T</span></code>
948 and <code class="computeroutput"><span class="identifier">T</span><span class="special">-&gt;</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">-&gt;</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">-&gt;</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">-&gt;</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 &#169; 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>
Ceph