102 lines
3.5 KiB
XML
102 lines
3.5 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<!DOCTYPE section PUBLIC "-//Boost//DTD BoostBook XML V1.1//EN"
|
|
"http://www.boost.org/tools/boostbook/dtd/boostbook.dtd">
|
|
<section id="safe_numerics.promotion_policies.native">
|
|
<title>native</title>
|
|
|
|
<section>
|
|
<title>Description</title>
|
|
|
|
<para>This type contains the functions to return a safe type corresponding
|
|
to the C++ type resulting from a given arithmetic operation.</para>
|
|
|
|
<para>Usage of this policy with safe types will produce the exact same
|
|
arithmetic results that using normal unsafe integer types will. Hence this
|
|
policy is suitable as a drop-in replacement for these unsafe types. Its
|
|
main function is to trap incorrect arithmetic results when using C++ for
|
|
integer arithmetic.</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Model of</title>
|
|
|
|
<para><link
|
|
linkend="safe_numerics.promotion_policy">PromotionPolicy</link></para>
|
|
|
|
<para>As an example of how this works consider C++ rules from section 5 of
|
|
the standard - "usual arithmetic conversions".</para>
|
|
|
|
<para><programlisting>void int f(int x, int y){
|
|
auto z = x + y; // z will be of type "int"
|
|
return z;
|
|
}</programlisting></para>
|
|
|
|
<para>According to these rules, z will be of type int. Depending on the
|
|
values of x and y, z may or may not contain the correct arithmetic result
|
|
of the operation x + y.</para>
|
|
|
|
<programlisting>using safe_int = safe<int, native>;
|
|
void int f(safe_int x, safe_int y){
|
|
auto z = x + y; // z will be of type "safe_int"
|
|
return z;
|
|
}</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Example of use</title>
|
|
|
|
<para>The following example illustrates the <code>native</code> type being
|
|
passed as a template parameter for the type <code>safe<int></code>.
|
|
This example is slightly contrived in that <code>safe<int></code>
|
|
has <code>native</code> as its default promotion parameter so explicitly
|
|
using <code>native</code> is not necessary.</para>
|
|
|
|
<programlisting>#include <cassert>
|
|
#include <boost/numeric/safe_numerics/safe_integer.hpp>
|
|
#include <boost/numeric/safe_numerics/native.hpp>
|
|
int main(){
|
|
using namespace boost::numeric;
|
|
// use native promotion policy where C++ standard arithmetic
|
|
// might lead to incorrect results
|
|
using safe_int8 = safe<std::int8_t, native>;
|
|
try{
|
|
safe_int8 x = 127;
|
|
safe_int8 y = 2;
|
|
safe_int8 z;
|
|
// rather than producing an invalid result an exception is thrown
|
|
z = x + y;
|
|
assert(false); // never arrive here
|
|
}
|
|
catch(std::exception & e){
|
|
// which we can catch here
|
|
std::cout << e.what() << std::endl;
|
|
}
|
|
|
|
// When result is an int, C++ promotion rules guarentee
|
|
// that there will be no incorrect result.
|
|
// In such cases, there is no runtime overhead from using safe types.
|
|
safe_int8 x = 127;
|
|
safe_int8 y = 2;
|
|
safe<int, native> z; // z can now hold the result of the addition of any two 8 bit numbers
|
|
z = x + y; // is guaranteed correct without any runtime overhead or exception.
|
|
|
|
return 0;
|
|
}</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Notes</title>
|
|
|
|
<para>See Chapter 5, Expressions, C++ Standard</para>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Header</title>
|
|
|
|
<para><code><ulink
|
|
url="../../include/boost/safe_numerics/native.hpp"><code>#include
|
|
<boost/numeric/safe_numerics/native.hpp>
|
|
</code></ulink></code></para>
|
|
</section>
|
|
</section>
|