mirror of
https://github.com/boostorg/safe_numerics.git
synced 2026-02-22 15:42:30 +00:00
63dd89210e
improved TOC and chunking. This is complicated by the fact we that we desire different depths. put copies of boost logo in subdirectories
99 lines
3.4 KiB
XML
99 lines
3.4 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 for 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. It's
|
|
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>Header</title>
|
|
|
|
<para><code><ulink url="../../include/native.hpp"><code>#include
|
|
<boost/safe_numerics/include/native.hpp>
|
|
</code></ulink></code></para>
|
|
</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 it's default promotion parameter so explicitly
|
|
using <code>native</code> is not necessary.</para>
|
|
|
|
<programlisting>#include <cassert>
|
|
#include <boost/safe_numerics/safe_integer.hpp>
|
|
#include <boost/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 and invalid result an exception is thrown
|
|
z = x + y;
|
|
assert(false); // never arrive here
|
|
}
|
|
catch(std::exception & e){
|
|
// which 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 guarenteed correct without any runtime overhead or interrupt.
|
|
|
|
return 0;
|
|
}</programlisting>
|
|
</section>
|
|
|
|
<section>
|
|
<title>Notes</title>
|
|
|
|
<para>See Chapter 5, Expressions, C++ Standard</para>
|
|
</section>
|
|
</section>
|