<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=US-ASCII">
<title>SafeNumeric<T></title>
<link rel="stylesheet" href="boostbook.css" type="text/css">
<meta name="generator" content="DocBook XSL Stylesheets V1.79.1">
<link rel="home" href="index.html" title="Safe Numerics">
<link rel="up" href="concepts.html" title="Type Requirements">
<link rel="prev" href="integer.html" title="Integer<T>">
<link rel="next" href="promotion_policy.html" title="PromotionPolicy<PP>">
</head>
<body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF">
<table cellpadding="2" width="100%"><tr>
<td valign="top"><img href="index.html" height="164px" src="pre-boost.jpg" alt="Library Documentation Index"></td>
<td><h2>Safe Numerics</h2></td>
</tr></table>
<div class="spirit-nav">
<a accesskey="p" href="integer.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="promotion_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
<div class="section">
<div class="titlepage"><div><div><h3 class="title">
<a name="safe_numerics.safe_numeric_concept"></a>SafeNumeric<T></h3></div></div></div>
<div class="toc"><dl class="toc">
<dt><span class="section"><a href="safe_numeric_concept.html#idm194822208704">Description</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm194822207248">Refinement of</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm194822205232">Notation</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm194822188752">Valid Expressions</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm194822122368">Invariants</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm194822120768">Models</a></span></dt>
<dt><span class="section"><a href="safe_numeric_concept.html#idm194822116400">Header</a></span></dt>
</dl></div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm194822208704"></a>Description</h4></div></div></div>
<p>This holds an arithmetic value which can be used as a replacement
for built-in C++ arithmetic values. These types differ from their built-in
counter parts in that the are guaranteed not to produce invalid arithmetic
results. These operations return safe types rather than built-in
types.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm194822207248"></a>Refinement of</h4></div></div></div>
<p><a class="link" href="numeric.html" title="Numeric<T>">Numeric</a> or <a class="link" href="integer.html" title="Integer<T>">Integer</a></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm194822205232"></a>Notation</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Symbol</th>
<th align="left">Description</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">T, U</code></td>
<td align="left">Types fulfilling <a class="link" href="numeric.html" title="Numeric<T>">Numeric</a> or <a class="link" href="integer.html" title="Integer<T>">Integer</a> type
requirements.</td>
</tr>
<tr>
<td align="left">t, u</td>
<td align="left">objects of types T, U</td>
</tr>
<tr>
<td align="left">S</td>
<td align="left">A type fulfilling SafeNumeric type requirements</td>
</tr>
<tr>
<td align="left">s, s1, s2</td>
<td align="left">objects of types S</td>
</tr>
<tr>
<td align="left">op</td>
<td align="left">C++ infix operator supported by underlying type T</td>
</tr>
<tr>
<td align="left">prefix_op</td>
<td align="left">C++ prefix operator: -, +, ~, ++, -- supported by
underlying type T</td>
</tr>
<tr>
<td align="left">postfix_op</td>
<td align="left">C++ postfix operator:++, -- supported by underlying type
T</td>
</tr>
<tr>
<td align="left">assign_op</td>
<td align="left">C++ assignment operator</td>
</tr>
</tbody>
</table></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm194822188752"></a>Valid Expressions</h4></div></div></div>
<div class="informaltable"><table class="table">
<colgroup>
<col align="left">
<col align="left">
<col align="left">
</colgroup>
<thead><tr>
<th align="left">Expression</th>
<th align="left">Result Type</th>
<th align="left">Description</th>
</tr></thead>
<tbody>
<tr>
<td align="left"><code class="computeroutput">s op t</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t op s</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">s1 op s2</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator op and return another
SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">prefix_op S</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator <code class="computeroutput">prefix_op</code> and
return another SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S postfix_op</code></td>
<td align="left">unspecified S</td>
<td align="left"><p>invoke C++ operator <code class="computeroutput">postfix_op</code> and
return another SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">s assign_op t</code></td>
<td align="left">S &</td>
<td align="left"><p>convert t to type S and assign it to s.
</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">t assign_op s</code></td>
<td align="left">T &</td>
<td align="left"><p>convert s to type T and assign it to s. If the
value t cannot be represented as an instance of type S, it is an
error.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S(t)</code></td>
<td align="left">S</td>
<td align="left"><p>construct an instance of S from a value of type T.
In this case, T is referred to as the base type of S. If the
value t cannot be represented as an instance of type S, it is an
exception condition is invoked. </p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">S</code></td>
<td align="left">S</td>
<td align="left"><p>construct an uninitialized instance of
S.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">T(s)</code></td>
<td align="left">T</td>
<td align="left"><p>implicit conversion of the value of s to type T. If
the value of s cannot be correctly represented as a type T, an
exception condition is invoked.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">static_cast<T>(s)</code></td>
<td align="left">T</td>
<td align="left"><p>convert the value of s to type T. If the value of s
cannot be correctly represented as a type T, an exception
condition is invoked. </p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">is_safe<S></code></td>
<td align="left"><code class="computeroutput">std::true_type</code></td>
<td align="left"><p>type trait to query whether any type S fulfills the
requirements for a SafeNumeric type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">base_type<S>::type</code></td>
<td align="left">T</td>
<td align="left"><p>Retrieve the base type of a given safe
type.</p></td>
</tr>
<tr>
<td align="left"><code class="computeroutput">base_value(s)</code></td>
<td align="left">T</td>
<td align="left"><p>Retrieve the value of an instance of a safe type.
This is equivalent to
<code class="computeroutput">static_cast<base_type<S>>(s)</code>.</p></td>
</tr>
</tbody>
</table></div>
<div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; ">
<li class="listitem"><p>The result of any binary operation where one or both of the
operands is a SafeNumeric type is also a SafeNumeric type.</p></li>
<li class="listitem"><p>All the expressions in the above table are
<code class="computeroutput">constexpr</code> expressions.</p></li>
<li class="listitem"><p>Binary expressions which are not assignments and whose operands
are both safe types require that promotion and exception policies of
the operands be identical.</p></li>
<li class="listitem"><p><code class="computeroutput">Operations on safe types are supported if and only if the
same operation is supported on the underlying types. For example, the
binary operations |</code>, <code class="computeroutput">&</code>, <code class="computeroutput">^</code> and
<code class="computeroutput">~</code> operations defined for safe unsigned integer types. But
they are not defined for floating point types. Currently the are also
defined for signed integer types. It's not clear that this is the
correct decision. On one hand, usage of these operators on signed
types is almost certainly an error in program logic. But trapping this
as an error conflicts with the goal of making safe types "drop-in"
replacements for the corresponding built-in types. In light of this,
these operators are currently supported as they are for normal
built-in types.</p></li>
<li class="listitem">
<p>Safe Numeric types will be implicitly converted to built-in
types when appropriate. Here's an example:</p>
<pre class="programlisting"><span class="keyword">void</span> <span class="identifier">f</span><span class="special">(</span><span class="keyword">int</span><span class="special">)</span><span class="special">;</span>
<span class="keyword">int</span> <span class="identifier">main</span><span class="special">(</span><span class="special">)</span><span class="special">{</span>
<span class="keyword">long</span> <span class="identifier">x</span><span class="special">;</span>
<span class="identifier">f</span><span class="special">(</span><span class="identifier">x</span><span class="special">)</span><span class="special">;</span> <span class="comment">// OK - builtin implicit version</span>
<span class="identifier">safe</span><span class="special"><</span><span class="keyword">long</span><span class="special">></span> <span class="identifier">y</span><span class="special">;</span>
<span class="identifier">f</span><span class="special">(</span><span class="identifier">y</span><span class="special">)</span><span class="special">;</span>
<span class="keyword">return</span> <span class="number">0</span><span class="special">;</span>
<span class="special">}</span></pre>
<p>This behavior supports the concept of
<code class="computeroutput">safe<T></code> as being a "drop-in" replacement for a
<code class="computeroutput">T</code>.</p>
</li>
</ul></div>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm194822122368"></a>Invariants</h4></div></div></div>
<p>The fundamental requirement of a SafeNumeric type is that it
implements all C++ operations permitted on its base type in a way the
prevents the return of an incorrect arithmetic result. Various
implementations of this concept may handle circumstances which produce
such results differently (throw exception, compile time trap, etc..). But
no implementation should return an arithmetically incorrect result.</p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm194822120768"></a>Models</h4></div></div></div>
<p><code class="computeroutput">safe<T></code></p>
<p><code class="computeroutput">safe_signed_range<-11, 11></code></p>
<p><code class="computeroutput">safe_unsigned_range<0, 11></code></p>
<p><code class="computeroutput">safe_signed_literal<4></code></p>
</div>
<div class="section">
<div class="titlepage"><div><div><h4 class="title">
<a name="idm194822116400"></a>Header</h4></div></div></div>
<p><a href="../../include/concept/safe_numeric.hpp" target="_top"><code class="computeroutput">#include
<boost/numeric/safe_numerics/concepts/safe_numeric.hpp></code></a></p>
</div>
</div>
<table xmlns:rev="http://www.cs.rpi.edu/~gregod/boost/tools/doc/revision" width="100%"><tr>
<td align="left"></td>
<td align="right"><div class="copyright-footer">Copyright © 2012-2018 Robert Ramey<p><a href="http://www.boost.org/LICENSE_1_0.txt" target="_top">Subject to Boost
Software License</a></p>
</div></td>
</tr></table>
<hr>
<div class="spirit-nav">
<a accesskey="p" href="integer.html"><img src="images/prev.png" alt="Prev"></a><a accesskey="u" href="concepts.html"><img src="images/up.png" alt="Up"></a><a accesskey="h" href="index.html"><img src="images/home.png" alt="Home"></a><a accesskey="n" href="promotion_policy.html"><img src="images/next.png" alt="Next"></a>
</div>
</body>
</html>