diff --git a/doc/boostbook/db2html.xsl b/doc/boostbook/db2html.xsl index c31de26..ef194dd 100644 --- a/doc/boostbook/db2html.xsl +++ b/doc/boostbook/db2html.xsl @@ -8,21 +8,36 @@ - - - - - -horizontal - + + + + + + + +horizontal + + + + + + + + + + + + + + - - - diff --git a/doc/boostbook/safe_compare.xml b/doc/boostbook/safe_compare.xml index 24eea5a..770b62a 100644 --- a/doc/boostbook/safe_compare.xml +++ b/doc/boostbook/safe_compare.xml @@ -88,12 +88,17 @@ bool safe_compare::not_equal(const T & lhs, const U & rhs);#include <boost/numeric/safe_compare.hpp> void f(){ - int i = -1; - unsigned char i = 0x129; + unsigned char i = 129; unsigned int j = 1; - bool result; - result = j < i; // incorrect result - result = safe_compare::less_than(j < i); // correct result + assert(j < i); // program traps because expression is false. But this is a surprise because 1 < 129 + assert( safe_compare::less_than(j,i)); // expression is true as we would expect +} + +// safe_compare is used to implement comparison operators for safe types. So we can do this: +void g(){ + safe<unsigned char> int i = 0x129; + safe<int> j = 1; + assert(j < i); // program works as expected } diff --git a/doc/boostbook/safe_introduction.xml b/doc/boostbook/safe_introduction.xml index 6a1c02a..37e109d 100644 --- a/doc/boostbook/safe_introduction.xml +++ b/doc/boostbook/safe_introduction.xml @@ -4,7 +4,7 @@
Introduction -
+
Problem Arithmetic operations in C++ are NOT guarenteed to yield a correct @@ -21,7 +21,7 @@ this code would introduce another source of errors.
-
+
Solution This library implements special versions of int, unsigned, etc. @@ -37,7 +37,7 @@ outside the closed range [MIN, MAX].
-
+
Requirements This library is is composed entirely of C++ Headers. I requires a diff --git a/doc/boostbook/safe_numerics.xml b/doc/boostbook/safe_numerics.xml index 461c61a..4cefda2 100644 --- a/doc/boostbook/safe_numerics.xml +++ b/doc/boostbook/safe_numerics.xml @@ -19,7 +19,7 @@ - Subject to Boost Software License + http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License Safe integer operations diff --git a/doc/html/acknowledgements.html b/doc/html/acknowledgements.html index efa448d..cd25c88 100644 --- a/doc/html/acknowledgements.html +++ b/doc/html/acknowledgements.html @@ -13,7 +13,7 @@ - + @@ -31,7 +31,7 @@
pre-boost HomeLibrariesLibraries People FAQ More
-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
diff --git a/doc/html/change_log.html b/doc/html/change_log.html index 6e8a1c5..8ac0cca 100644 --- a/doc/html/change_log.html +++ b/doc/html/change_log.html @@ -13,7 +13,7 @@ - + @@ -29,7 +29,7 @@
pre-boost HomeLibrariesLibraries People FAQ More
-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
diff --git a/doc/html/concepts.html b/doc/html/concepts.html index 937c2ff..ca7e99b 100644 --- a/doc/html/concepts.html +++ b/doc/html/concepts.html @@ -7,34 +7,362 @@ - + - +
pre-boost HomeLibrariesLibraries People FAQ More
-PrevUpHomeNext +PrevUpHomeNext

Concepts

-
Numeric<T>
+
Numeric<T>
+
+

+Numeric<T>

+
+
Description
+
Notation
+
Associated Types
+
Valid Expressions
+
Header
+
Models
+
+
+

+Description

+

A type is Numeric if it has the properties of a number.

+

More specifically, a type T is Numeric if there exists + specialization of std::numeric_limits<T>. See the + documentation for standard library class numeric_limits. The standard + library includes such specializations for all the primitive numeric types. + Note that this concept is distinct from the C++ standard library type + traits is_integral and is_arithmetic. These + latter fullfill the requirement of the concept Numeric. But there are + types T which fullfill this concept for which + is_arithmetic<T>::value == false. For example see + safe_signed_integer<int>.

+
+
+

+Notation

+
+

Table 1. Notation

+
++++ + + + + + + + + + + +
T, U, VA type that is a model of the Numeric
t, u, vAn object of type modeling Numeric
+
+
+
+
+

+Associated Types

+
+

Table 2. Associated Types

+
++++ + + + + +
std::numeric_limits<T>The numeric_limits class template provides a C++ program + with information about various properties of the implementation’s + representation of the arithmetic types. See C++ standard + 18.3.2.2.
+
+
+
+
+

+Valid Expressions

+

In addition to the expressions defined in Assignable the + following expressions must be valid.

+

Any operations which result in integers which cannot be represented + as some Numeric type will throw an exception.

+
+

Table 3. General

+
++++ + + + + + + + + + + + + + + + + + + +
ExpressionReturn Value
std::numeric_limits<T>.is_bounded + true
std::numeric_limits<T>.is_integertrue
std::numeric_limits<T>.is_specialized + true
+
+


+
+

Table 4. Unary Operators

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExpressionReturn TypeSemantics
-tTInvert sign
+tTunary plus - a no op
t--Tpost decrement
t++Tpost increment
--tTpredecrement
++tTpreincrement
~Tcomplement
+
+
+

Table 5. Binary Operators

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExpressionReturn TypeSemantics
t - uVsubtract u from t
t + uVadd u to t
t * uVmultiply t by u
t / uTdivide t by u
t % uTt modulus u
t << uTshift t left u bits
t >> uTshift t right by ubits
t < ubooltrue if t less than u, false otherwise
t <= ubooltrue if t less than or equal to u, false otherwise
t > ubooltrue if t greater than u, false otherwise
t >= ubooltrue if t greathan or equal to u, false otherwise
t == ubooltrue if t equal to u, false otherwise
t != ubooltrue if t not equal to u, false otherwise
t & uVand of t and u padded out max # bits in t, u
t | uVor of t and u padded out max # bits in t, u
t ^ uVexclusive or of t and u padded out max # bits in t, + u
t = uTassign value of u to t
t += uTadd u to t and assign to t
t -= uTsubtract u from t and assign to t
t *= uTmultiply t by u and assign to t
t /= uTdivide t by u and assign to t
t &= uTand t with u and assign to t
t <<= uTleft shift the value of t by u bits
t >>= uTright shift the value of t by u bits
t &= uTand the value of t with u and assign to t
t |= uTor the value of t with u and assign to t
t ^= uTexclusive or the value of t with u and assign to t
+
+
+
+
+

+Header

+

#include + <safe_numerics/include/concepts/numeric.hpp>

+
+
+

+Models

+

int, safe_signed_integer<int>, + safe_signed_range<int>, etc.

+
+
-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/functions.html b/doc/html/functions.html index 46373c1..ad1231f 100644 --- a/doc/html/functions.html +++ b/doc/html/functions.html @@ -6,39 +6,271 @@ - - + + - +
pre-boost HomeLibrariesLibraries People FAQ More
-PrevUpHomeNext +PrevUpHomeNext

Functions

-
safe_cast<T, U>
-
safe_compare<T, U>
-
overflow
+
safe_cast<T, U>
+
safe_compare<T, U>
+
overflow
+
+

+safe_cast<T, U>

+
+
Synopsis
+
Description
+
Type requirements
+
Preconditions
+
Complexity
+
Header
+
Example of use
+
+
+

+Synopsis

+
template<class T, class U>
+T safe_cast(const U & u);
+
+
+

+Description

+

Converts one Numeric + type to another. Throws an std::out_of_range exception if + such a conversion is not possible without changing the value.

+
+
+

+Type requirements

+
++++ + + + + + + + + + + + + + + +
TypeRequirements
TNumeric
U Numeric
+
+
+

+Preconditions

+

The value of u must be representabl by the type T. If + this is not true, an std::out_of_range exception will be + thrown.

+
+
+

+Complexity

+

Constant - O(0).

+
+
+

+Header

+

#include + <boost/numeric/safe_cast.hpp>

+
+
+

+Example of use

+
#include <boost/numeric/safe_cast.hpp> 
+#include <boost/numeric/safe_integer.hpp> 
+
+void f(){
+    safe_integer<char> i;
+    unsigned char j;
+    i = 1;
+    j = safe_cast<unsigned char>(i);  // ok
+    i = -1;
+    j = safe_cast<unsigned char>(i);  // throws std::out_of_range exception
+    i = 1024;
+    j = safe_cast<unsigned char>(i);  // throws std::out_of_range exception
+}
+
+
+
+

+safe_compare<T, U>

+
+
Synopsis
+
Description
+
Type requirements
+
Header
+
Example of use
+
+
+

+Synopsis

+

safe_compare is several functions:.

+
template<class T, class U>
+bool safe_compare::less_than(const T & lhs, const U & rhs);
+
+template<class T, class U>
+bool safe_compare::less_than_equal(const T & lhs, const U & rhs);
+
+template<class T, class U>
+bool safe_compare::greater_than(const T & lhs, const U & rhs);
+
+template<class T, class U>
+bool safe_compare::greater_than_equal(const T & lhs, const U & rhs);
+
+template<class T, class U>
+bool safe_compare::equal(const T & lhs, const U & rhs);
+
+template<class T, class U>
+bool safe_compare::not_equal(const T & lhs, const U & rhs);
+
+
+

+Description

+

With normal comparison operators, comparison of unsigned types to + signed types will be done by converting the unsigned type to a signed type + before comparing. Unfortunately this is not always possible. Most C++ + compilers will emit an warning message when this is possible but won't + check that an error is made in the conversion. This function guarentees a + correct result regardless of the types of the arguments.

+
+
+

+Type requirements

+
++++ + + + + + + + + + + + + + + +
TypeRequirements
TNumeric
U Numeric
+
+
+

+Header

+

#include + <boost/numeric/safe_compare.hpp>

+
+
+

+Example of use

+
#include <boost/numeric/safe_compare.hpp>
+
+void f(){
+    unsigned char i = 129;
+    unsigned int j = 1;
+    assert(j < i); // program traps because expression is false. But this is a surprise because 1 < 129
+    assert( safe_compare::less_than(j,i)); // expression is true as we would expect
+}
+
+// safe_compare is used to implement comparison operators for safe types.  So we can do this:
+void g(){
+    safe<unsigned char> int i = 0x129;
+    safe<int> j = 1;
+    assert(j < i); // program works as expected
+}
+
+
+
+

+overflow

+
+
Synopsis
+
Description
+
Header
+
Example of use
+
See Also
+
+
+

+Synopsis

+

This function is invoked by the library whenever it is not possible + to produce a result for an arithmetic operation.

+
void overflow(char const * const msg);
+
+
+

+Description

+

If evironment supports C++ exceptions, this function throws the + exception .

+

If the environment does not support C++ exceptions, the user should + implement this function and expect it to be called when appropriate. + Otherwise, function is implemented by the library so that it throws the + standard library exception std::out_of_range(msg).

+

boost/config.hpp defines BOOST_NO_EXCEPTIONS + when the environment doesn't support exceptions. It is by checking for the + definition of this macro that the system determines whether or not + exceptions are supported.

+
+
+

+Header

+

#include + <boost/safe_numerics/overflow.hpp>

+
+
+

+Example of use

+
#include <cstdio>
+
+void overflow(char const * const msg){
+    std::fputs("safe_numerics overflow error:, std::stderr);
+    std::fputs(msg, std::stderr);
+    std::fputc('\n', std::stderr);
+}
+
+
+

+See Also

+

See rationale for more + information on this function

+
+
-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/images/alert.png b/doc/html/images/alert.png deleted file mode 100644 index b4645bc..0000000 Binary files a/doc/html/images/alert.png and /dev/null differ diff --git a/doc/html/images/callouts/1.png b/doc/html/images/callouts/1.png deleted file mode 100644 index 6003ad3..0000000 Binary files a/doc/html/images/callouts/1.png and /dev/null differ diff --git a/doc/html/images/callouts/10.png b/doc/html/images/callouts/10.png deleted file mode 100644 index 0426f51..0000000 Binary files a/doc/html/images/callouts/10.png and /dev/null differ diff --git a/doc/html/images/callouts/11.png b/doc/html/images/callouts/11.png deleted file mode 100644 index 821afc4..0000000 Binary files a/doc/html/images/callouts/11.png and /dev/null differ diff --git a/doc/html/images/callouts/12.png b/doc/html/images/callouts/12.png deleted file mode 100644 index 7cec727..0000000 Binary files a/doc/html/images/callouts/12.png and /dev/null differ diff --git a/doc/html/images/callouts/13.png b/doc/html/images/callouts/13.png deleted file mode 100644 index 5b41e02..0000000 Binary files a/doc/html/images/callouts/13.png and /dev/null differ diff --git a/doc/html/images/callouts/14.png b/doc/html/images/callouts/14.png deleted file mode 100644 index de5bdbd..0000000 Binary files a/doc/html/images/callouts/14.png and /dev/null differ diff --git a/doc/html/images/callouts/15.png b/doc/html/images/callouts/15.png deleted file mode 100644 index 3fd6ac3..0000000 Binary files a/doc/html/images/callouts/15.png and /dev/null differ diff --git a/doc/html/images/callouts/2.png b/doc/html/images/callouts/2.png deleted file mode 100644 index f7c1578..0000000 Binary files a/doc/html/images/callouts/2.png and /dev/null differ diff --git a/doc/html/images/callouts/3.png b/doc/html/images/callouts/3.png deleted file mode 100644 index 3ff0a93..0000000 Binary files a/doc/html/images/callouts/3.png and /dev/null differ diff --git a/doc/html/images/callouts/4.png b/doc/html/images/callouts/4.png deleted file mode 100644 index 6aa29fc..0000000 Binary files a/doc/html/images/callouts/4.png and /dev/null differ diff --git a/doc/html/images/callouts/5.png b/doc/html/images/callouts/5.png deleted file mode 100644 index 36e7858..0000000 Binary files a/doc/html/images/callouts/5.png and /dev/null differ diff --git a/doc/html/images/callouts/6.png b/doc/html/images/callouts/6.png deleted file mode 100644 index c943676..0000000 Binary files a/doc/html/images/callouts/6.png and /dev/null differ diff --git a/doc/html/images/callouts/7.png b/doc/html/images/callouts/7.png deleted file mode 100644 index 20940de..0000000 Binary files a/doc/html/images/callouts/7.png and /dev/null differ diff --git a/doc/html/images/callouts/8.png b/doc/html/images/callouts/8.png deleted file mode 100644 index d8e34d4..0000000 Binary files a/doc/html/images/callouts/8.png and /dev/null differ diff --git a/doc/html/images/callouts/9.png b/doc/html/images/callouts/9.png deleted file mode 100644 index abe6360..0000000 Binary files a/doc/html/images/callouts/9.png and /dev/null differ diff --git a/doc/html/images/next_disabled.png b/doc/html/images/next_disabled.png old mode 100644 new mode 100755 diff --git a/doc/html/images/prev_disabled.png b/doc/html/images/prev_disabled.png old mode 100644 new mode 100755 diff --git a/doc/html/images/smiley.png b/doc/html/images/smiley.png deleted file mode 100644 index 30a77f7..0000000 Binary files a/doc/html/images/smiley.png and /dev/null differ diff --git a/doc/html/images/up_disabled.png b/doc/html/images/up_disabled.png old mode 100644 new mode 100755 diff --git a/doc/html/index.html b/doc/html/index.html index 888e63f..4439e39 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -11,7 +11,7 @@ - + @@ -27,41 +27,18 @@

Copyright © 2012 Robert Ramey

Table of Contents

Introduction
-
-
Problem
-
Solution
-
Requirements
-
Tutorial
-
-
Problem: Arithmetic operations can yield in correct - results.
-
Problem: Undetected overflow
-
Problem: Implicit conversions change data values
-
Notes
Concepts
-
Numeric<T>
Types
-
-
safe_unsigned_range<MIN, MAX>
-
safe_signed_range<boost::intmax_t MIN, - boost::intmax_tMAX>
-
safe<T>
-
Functions
-
-
safe_cast<T, U>
-
safe_compare<T, U>
-
overflow
-
Rationale
Change Log
Acknowledgements
@@ -70,7 +47,7 @@
pre-boost HomeLibrariesLibraries People FAQ More
- +

Last revised: ,

Last revised: $Date
diff --git a/doc/html/introduction.html b/doc/html/introduction.html index 51550f2..4057d12 100644 --- a/doc/html/introduction.html +++ b/doc/html/introduction.html @@ -7,38 +7,85 @@ - + - +
pre-boost HomeLibrariesLibraries People FAQ More
-PrevUpHomeNext +PrevUpHomeNext

Introduction

-
Problem
-
Solution
-
Requirements
+
Problem
+
Solution
+
Requirements
+
+

+Problem

+

Arithmetic operations in C++ are NOT guarenteed to yield a correct + mathematical result. This feature is inherited from the early days of C. + The behavior of int, unsigned int and others + were designed to map closely to the underlying hardware. Computer hardware + implements these types as a fixed number of bits. When the result of + arithmetic operations exceeds this number of bits, the result is undefined + and usually not what the programmer intended. It is incumbent up the C/C++ + programmer to guarentee that this behavior does not result in incorrect + behavior of the program. There are no language facilities which do this. + They have to be explicitly addressed in the program code. This is + exceeding tedious and laborious for a programmer to do. Besides, adding + this code would introduce another source of errors.

+
+
+

+Solution

+

This library implements special versions of int, unsigned, etc. + which behave exactly like the original ones EXCEPT that the results of + these operations are checked to be sure any possible errors resulting from + undefined arithmetic behavior are trapped at compile time (if possible) or + at runtime.

+

In addition to eliminating undefined behavior from primitive integer + types, we define new data types safe_signed_range<MIN, + MAX> and safe_unsigned_range<MIN, MAX> which + will throw an exception if an attempt is made to store a result which is + outside the closed range [MIN, MAX].

+
+
+

+Requirements

+

This library is is composed entirely of C++ Headers. I requires a + compiler compatible with the C++11 standard.

+

The following Boost Libraries must be installed in order to use this + library

+
    +

  • mpl

    • +

  • integer

    • +

  • limits

    • +

  • config

    • +

  • concept checking

    • +

  • type traits

    • +

  • integer traits

    • +
+
-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/introduction/problem.html b/doc/html/introduction/problem.html deleted file mode 100644 index 2239422..0000000 --- a/doc/html/introduction/problem.html +++ /dev/null @@ -1,51 +0,0 @@ - - - -Problem - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-Problem

-

Arithmetic operations in C++ are NOT guarenteed to yield a correct - mathematical result. This feature is inherited from the early days of C. - The behavior of int, unsigned int and others - were designed to map closely to the underlying hardware. Computer hardware - implements these types as a fixed number of bits. When the result of - arithmetic operations exceeds this number of bits, the result is undefined - and usually not what the programmer intended. It is incumbent up the C/C++ - programmer to guarentee that this behavior does not result in incorrect - behavior of the program. There are no language facilities which do this. - They have to be explicitly addressed in the program code. This is - exceeding tedious and laborious for a programmer to do. Besides, adding - this code would introduce another source of errors.

-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/introduction/requirements.html b/doc/html/introduction/requirements.html deleted file mode 100644 index 24899ff..0000000 --- a/doc/html/introduction/requirements.html +++ /dev/null @@ -1,52 +0,0 @@ - - - -Requirements - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-Requirements

-

This library is is composed entirely of C++ Headers. I requires a - compiler compatible with the C++11 standard.

-

The following Boost Libraries must be installed in order to use this - library

-
    -

  • mpl

    • -

  • integer

    • -

  • limits

    • -

  • config

    • -

  • concept checking

    • -

  • type traits

    • -

  • integer traits

    • -
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/introduction/solution.html b/doc/html/introduction/solution.html deleted file mode 100644 index 2f577d3..0000000 --- a/doc/html/introduction/solution.html +++ /dev/null @@ -1,49 +0,0 @@ - - - -Solution - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-Solution

-

This library implements special versions of int, unsigned, etc. - which behave exactly like the original ones EXCEPT that the results of - these operations are checked to be sure any possible errors resulting from - undefined arithmetic behavior are trapped at compile time (if possible) or - at runtime.

-

In addition to eliminating undefined behavior from primitive integer - types, we define new data types safe_signed_range<MIN, - MAX> and safe_unsigned_range<MIN, MAX> which - will throw an exception if an attempt is made to store a result which is - outside the closed range [MIN, MAX].

-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/notes.html b/doc/html/notes.html index 846824c..469eb92 100644 --- a/doc/html/notes.html +++ b/doc/html/notes.html @@ -6,21 +6,21 @@ - + - +
pre-boost HomeLibrariesLibraries People FAQ More
-PrevUpHomeNext +PrevUpHomeNext

@@ -55,12 +55,12 @@

-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/numeric.html b/doc/html/numeric.html deleted file mode 100644 index 968ba78..0000000 --- a/doc/html/numeric.html +++ /dev/null @@ -1,363 +0,0 @@ - - - -Numeric<T> - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-Numeric<T>

-
-
Description
-
Notation
-
Associated Types
-
Valid Expressions
-
Header
-
Models
-
-
-

-Description

-

A type is Numeric if it has the properties of a number.

-

More specifically, a type T is Numeric if there exists - specialization of std::numeric_limits<T>. See the - documentation for standard library class numeric_limits. The standard - library includes such specializations for all the primitive numeric types. - Note that this concept is distinct from the C++ standard library type - traits is_integral and is_arithmetic. These - latter fullfill the requirement of the concept Numeric. But there are - types T which fullfill this concept for which - is_arithmetic<T>::value == false. For example see - safe_signed_integer<int>.

-
-
-

-Notation

-
-

Table 1. Notation

-
---- - - - - - - - - - - -
T, U, VA type that is a model of the Numeric
t, u, vAn object of type modeling Numeric
-
-
-
-
-

-Associated Types

-
-

Table 2. Associated Types

-
---- - - - - -
std::numeric_limits<T>The numeric_limits class template provides a C++ program - with information about various properties of the implementation’s - representation of the arithmetic types. See C++ standard - 18.3.2.2.
-
-
-
-
-

-Valid Expressions

-

In addition to the expressions defined in Assignable the - following expressions must be valid.

-

Any operations which result in integers which cannot be represented - as some Numeric type will throw an exception.

-
-

Table 3. General

-
---- - - - - - - - - - - - - - - - - - - -
ExpressionReturn Value
std::numeric_limits<T>.is_bounded - true
std::numeric_limits<T>.is_integertrue
std::numeric_limits<T>.is_specialized - true
-
-


-
-

Table 4. Unary Operators

-
----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExpressionReturn TypeSemantics
-tTInvert sign
+tTunary plus - a no op
t--Tpost decrement
t++Tpost increment
--tTpredecrement
++tTpreincrement
~Tcomplement
-
-
-

Table 5. Binary Operators

-
----- - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExpressionReturn TypeSemantics
t - uVsubtract u from t
t + uVadd u to t
t * uVmultiply t by u
t / uTdivide t by u
t % uTt modulus u
t << uTshift t left u bits
t >> uTshift t right by ubits
t < ubooltrue if t less than u, false otherwise
t <= ubooltrue if t less than or equal to u, false otherwise
t > ubooltrue if t greater than u, false otherwise
t >= ubooltrue if t greathan or equal to u, false otherwise
t == ubooltrue if t equal to u, false otherwise
t != ubooltrue if t not equal to u, false otherwise
t & uVand of t and u padded out max # bits in t, u
t | uVor of t and u padded out max # bits in t, u
t ^ uVexclusive or of t and u padded out max # bits in t, - u
t = uTassign value of u to t
t += uTadd u to t and assign to t
t -= uTsubtract u from t and assign to t
t *= uTmultiply t by u and assign to t
t /= uTdivide t by u and assign to t
t &= uTand t with u and assign to t
t <<= uTleft shift the value of t by u bits
t >>= uTright shift the value of t by u bits
t &= uTand the value of t with u and assign to t
t |= uTor the value of t with u and assign to t
t ^= uTexclusive or the value of t with u and assign to t
-
-
-
-
-

-Header

-

#include - <safe_numerics/include/concepts/numeric.hpp>

-
-
-

-Models

-

int, safe_signed_integer<int>, - safe_signed_range<int>, etc.

-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/rationale.html b/doc/html/rationale.html index 2df101d..94a8aef 100644 --- a/doc/html/rationale.html +++ b/doc/html/rationale.html @@ -6,35 +6,35 @@ - + - +
pre-boost HomeLibrariesLibraries People FAQ More
-PrevUpHomeNext +PrevUpHomeNext

Rationale

-
-
1. Why does a binary operation on two +
+
1. Why does a binary operation on two safe<int> values not return another safe type ?
-
2. Why is there no policy driven design for handling +
2. Why is there no policy driven design for handling overflows
-
3. Why is Boost.Convert not used. +
3. Why is Boost.Convert not used.
@@ -43,7 +43,7 @@
-

1.

+

1.

Why does a binary operation on two safe<int> values not return another @@ -64,7 +64,7 @@

-

2.

+

2.

Why is there no policy driven design for handling @@ -78,7 +78,7 @@ unsigned int x = t1 - t2; // which policy should be invoked?

-

3.

+

3.

Why is Boost.Convert not used.

@@ -92,12 +92,12 @@ unsigned int x = t1 - t2; // which policy should be invoked? -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/rationale/overflow.html b/doc/html/rationale/overflow.html deleted file mode 100644 index a67e450..0000000 --- a/doc/html/rationale/overflow.html +++ /dev/null @@ -1,90 +0,0 @@ - - - -overflow - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-overflow

-
-
Synopsis
-
Description
-
Header
-
Example of use
-
See Also
-
-
-

-Synopsis

-

This function is invoked by the library whenever it is not possible - to produce a result for an arithmetic operation.

-
void overflow(char const * const msg);
-
-
-

-Description

-

If evironment supports C++ exceptions, this function throws the - exception .

-

If the environment does not support C++ exceptions, the user should - implement this function and expect it to be called when appropriate. - Otherwise, function is implemented by the library so that it throws the - standard library exception std::out_of_range(msg).

-

boost/config.hpp defines BOOST_NO_EXCEPTIONS - when the environment doesn't support exceptions. It is by checking for the - definition of this macro that the system determines whether or not - exceptions are supported.

-
-
-

-Header

-

#include - <boost/safe_numerics/overflow.hpp>

-
-
-

-Example of use

-
#include <cstdio>
-
-void overflow(char const * const msg){
-    std::fputs("safe_numerics overflow error:, std::stderr);
-    std::fputs(msg, std::stderr);
-    std::fputc('\n', std::stderr);
-}
-
-
-

-See Also

-

See rationale for more - information on this function

-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/references.html b/doc/html/references.html index c68b6b6..8513dd3 100644 --- a/doc/html/references.html +++ b/doc/html/references.html @@ -12,7 +12,7 @@ - + @@ -40,7 +40,7 @@
pre-boost HomeLibrariesLibraries People FAQ More
-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
diff --git a/doc/html/safe.html b/doc/html/safe.html deleted file mode 100644 index ebe7655..0000000 --- a/doc/html/safe.html +++ /dev/null @@ -1,198 +0,0 @@ - - - -safe<T> - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-safe<T>

-
-
Description
-
Notation
-
Template Parameters
-
Model of
-
Valid Expressions
-
Header
-
Example of use
-
Notes
-
See Also
-
-
-

-Description

-

A safe<T> can be used anywhere a type T is used. - When T is used in operation which overflows, a exception is thrown

-
-
-

-Notation

-
---- - - - - - - - - - - - - - - - - - - -
SymbolDescription
T, U, VTypes which model the Numeric concept
t, u, vobjects of types T
stobject of type safe<T>
-
-
-

-Template Parameters

-
----- - - - - - - - - - - -
ParameterType RequirementsDescription
Tboost::is_integer<T>::value - == true

The underlying intrinsic integer type

-
-
-

-Model of

-

Numeric

-

If the resulting type of the operation t op u is V, the resulting - type of the operations st op su, t op su and st op u will be - safe<V>;

-
-
-

-Valid Expressions

-
----- - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExpressionResultDescription
st op usafe<decltype(t - op u)>

op is any valid binary operator for type - T

t op susafe<decltype(t - op u)>

op is any valid binary operator for type - T

st op susafe<decltype(t - op u)>

op is any valid binary operator for type - T

T * Utypeof(T * - U)

The underlying integer type

-
-
-

-Header

-

#include - <boost/safe_numerics/safe_integer.hpp>

-
-
-

-Example of use

-

The following program will emit an error message on a machine where - int is only 16 bits but run without problem on a machine where int is 32 - bits.

-
#include <boost/numeric/safe.hpp>
-#include <iostream>
-void f(){
-    safe<int> i = 400;
-    safe<int> j;
-    try {
-        j = i * i;
-    }
-    catch(...){
-       std::cout << "overflow error" << std::endl;
-    }
-}
-
-
-
-
-

-Notes

-

Footnotes (if any) that are referred to by other parts of the - page.

-
-
-

-See Also

-

Footnotes (if any) that are referred to by other parts of the - page.

-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/safe_cast.html b/doc/html/safe_cast.html deleted file mode 100644 index aaa874a..0000000 --- a/doc/html/safe_cast.html +++ /dev/null @@ -1,120 +0,0 @@ - - - -safe_cast<T, U> - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-safe_cast<T, U>

-
-
Synopsis
-
Description
-
Type requirements
-
Preconditions
-
Complexity
-
Header
-
Example of use
-
-
-

-Synopsis

-
template<class T, class U>
-T safe_cast(const U & u);
-
-
-

-Description

-

Converts one Numeric type - to another. Throws an std::out_of_range exception if such a - conversion is not possible without changing the value.

-
-
-

-Type requirements

-
---- - - - - - - - - - - - - - - -
TypeRequirements
TNumeric
U Numeric
-
-
-

-Preconditions

-

The value of u must be representabl by the type T. If - this is not true, an std::out_of_range exception will be - thrown.

-
-
-

-Complexity

-

Constant - O(0).

-
-
-

-Header

-

#include - <boost/numeric/safe_cast.hpp>

-
-
-

-Example of use

-
#include <boost/numeric/safe_cast.hpp> 
-#include <boost/numeric/safe_integer.hpp> 
-
-void f(){
-    safe_integer<char> i;
-    unsigned char j;
-    i = 1;
-    j = safe_cast<unsigned char>(i);  // ok
-    i = -1;
-    j = safe_cast<unsigned char>(i);  // throws std::out_of_range exception
-    i = 1024;
-    j = safe_cast<unsigned char>(i);  // throws std::out_of_range exception
-}
-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/safe_compare.html b/doc/html/safe_compare.html deleted file mode 100644 index 348c011..0000000 --- a/doc/html/safe_compare.html +++ /dev/null @@ -1,122 +0,0 @@ - - - -safe_compare<T, U> - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-safe_compare<T, U>

-
-
Synopsis
-
Description
-
Type requirements
-
Header
-
Example of use
-
-
-

-Synopsis

-

safe_compare is several functions:.

-
template<class T, class U>
-bool safe_compare::less_than(const T & lhs, const U & rhs);
-
-template<class T, class U>
-bool safe_compare::less_than_equal(const T & lhs, const U & rhs);
-
-template<class T, class U>
-bool safe_compare::greater_than(const T & lhs, const U & rhs);
-
-template<class T, class U>
-bool safe_compare::greater_than_equal(const T & lhs, const U & rhs);
-
-template<class T, class U>
-bool safe_compare::equal(const T & lhs, const U & rhs);
-
-template<class T, class U>
-bool safe_compare::not_equal(const T & lhs, const U & rhs);
-
-
-

-Description

-

With normal comparison operators, comparison of unsigned types to - signed types will be done by converting the unsigned type to a signed type - before comparing. Unfortunately this is not always possible. Most C++ - compilers will emit an warning message when this is possible but won't - check that an error is made in the conversion. This function guarentees a - correct result regardless of the types of the arguments.

-
-
-

-Type requirements

-
---- - - - - - - - - - - - - - - -
TypeRequirements
TNumeric
U Numeric
-
-
-

-Header

-

#include - <boost/numeric/safe_compare.hpp>

-
-
-

-Example of use

-
#include <boost/numeric/safe_compare.hpp>
-
-void f(){
-    int i = -1;
-    unsigned char i = 0x129;
-    unsigned int j = 1;
-    bool result;
-    result = j < i; // incorrect result
-    result = safe_compare::less_than(j < i); // correct result
-}
-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/safe_signed_range.html b/doc/html/safe_signed_range.html deleted file mode 100644 index 3c9a45d..0000000 --- a/doc/html/safe_signed_range.html +++ /dev/null @@ -1,126 +0,0 @@ - - - -safe_signed_range<boost::intmax_t MIN, boost::intmax_tMAX> - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-safe_signed_range<boost::intmax_t MIN, - boost::intmax_tMAX>

-
-
Description
-
Template Parameters
-
Model of
-
Header
-
Example of use
-
See Also
-
-
-

-Description

-

This type holds a integer in the range [MIN, MAX]. It will throw a - std::out_of_range exception for operation which would result - in assigning an integer value outside of this range.

-
-
-

-Template Parameters

-
----- - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequirementsDescription
MINmust be an integer literalThe minimum integer value that this type may hold
MAXmust be an integer literalThe maximum integer value that this type may hold
MIN < MAX 
-
-
-

-Model of

-

Numeric

-

The usage of this type in an arithmetic expression will result in - another type fulfilling the Numeric concept.

-

Operations on safe_signed_range will result in the same

-
-
-

-Header

-

#include - <boost/safe_numerics/safe_range.hpp>

-
-
-

-Example of use

-
#include <safe/numeric/safe_range.hpp>
-
-void f(){
-    boost::numeric::safe_signed_range<7, 24> i;
-    i = 0; // error
-    i = 9; // ok
-    i *= 9; // throws overflow exception
-
-    std::int8_t j = 4;
-    auto k = i + j;
-        // since i can vary between 7 and 24 and j can vary between 0 and 255
-        // the smallest unsigned integer which can hold the result std::int16_t
-        // j will be of type std::int16_t 
-}
-
-
-

-See Also

-

std::out_of_range

-

safe_unsigned_range

-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/safe_unsigned_range.html b/doc/html/safe_unsigned_range.html deleted file mode 100644 index caf3703..0000000 --- a/doc/html/safe_unsigned_range.html +++ /dev/null @@ -1,128 +0,0 @@ - - - -safe_unsigned_range<MIN, MAX> - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-safe_unsigned_range<MIN, MAX>

-
-
Description
-
Template Parameters
-
Model of
-
Header
-
Example of use
-
See Also
-
-
-

-Description

-

This type holds a integer in the range [MIN, MAX]. It will throw a - std::out_of_range exception for any operation which would - result in assigning an integer value outside of this range.

-
-
-

-Template Parameters

-
----- - - - - - - - - - - - - - - - - - - - - - - -
ParameterRequirementsDescription
MINmust be a positive integer literalThe minimum integer value that this type may hold
MAXmust be a positive integer literalThe maximum integer value that this type may hold
MIN < MAX 
-
-
-

-Model of

-

Numeric

-

The usage of this type in an arithmetic expression with another - unsigned type will result in another unsigned type fulfilling the Numeric concept. This will be the - smallest unsigned integer type of sufficient size to hold the result of - the operation.

-
-
-

-Header

-

#include - <safe/numeric/safe_range.hpp>

-
-
-

-Example of use

-
#include <safe/numeric/safe_range.hpp>
-
-void f(){
-    boost::numeric::safe_unsigned_range<7, 24> i;
-    i = 0;  // throws out_of_range exception
-    i = 9;  // ok
-    i *= 9; // throws out_of_range exception
-    i = -1; // throws out_of_range exception
-
-    std::uint8_t j = 4;
-    auto k = i + j;
-        // since i can vary between 7 and 24 and j can vary between 0 and 255
-        // the smallest unsigned integer which can hold the result std::uint16_t
-        // j will be of type std::uint16_t 
-    
-}
-
-
-

-See Also

-

std::out_of_range

-

safe_signed_range

-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/tutorial.html b/doc/html/tutorial.html index b53fce3..4b0793a 100644 --- a/doc/html/tutorial.html +++ b/doc/html/tutorial.html @@ -6,40 +6,216 @@ - - + + - +
pre-boost HomeLibrariesLibraries People FAQ More
-PrevUpHomeNext +PrevUpHomeNext

Tutorial

-
Problem: Arithmetic operations can yield in correct +
Problem: Arithmetic operations can yield in correct results.
-
Problem: Undetected overflow
-
Problem: Implicit conversions change data values
+
Problem: Undetected overflow
+
Problem: Implicit conversions change data values
+
+

+Problem: Arithmetic operations can yield in correct + results.

+

When some operation results in a result which exceeds the capacity + of a data variable to hold it, the result is undefined. This is called + "overflow". Since word size can differ between machines, code which + produces correct results in one set of circumstances may fail when + re-compiled on a machine with different hardware. When this occurs, Most + C++ compilers will continue to execute with no indication that the results + are wrong. It is the programmer's responsabiity to ensure such undefined + behavior is avoided.

+

This program demonstrates this problem. The solution is to replace + instances of char type with safe<char> + type.

+
#include <cassert>
+#include <stdexcept>
+#include <iostream>
+
+#include "../include/safe_integer.hpp"
+//#include "../include/safe_compare.hpp"
+
+void detected_msg(bool detected){
+    std::cout << (detected ? "error detected!" : "error NOT detected! ") << std::endl;
+}
+
+int main(int argc, const char * argv[]){
+    std::cout << "example 1:";
+    std::cout << "undetected erroneous expression evaluation" << std::endl;
+    std::cout << "Not using safe numerics" << std::endl;
+    try{
+        char x = 127;
+        char y = 2;
+        char z;
+        // this produces an invalid result !
+        z = x + y;
+        // it is the wrong result !!!
+        assert(z != 129);
+        // but assert fails to detect it since C++ implicitly
+        // converts variables to int before evaluating he expression!
+        assert(z != x + y);
+        std::cout << static_cast<int>(z) << " != " << x + y << std::endl;
+        detected_msg(false);
+    }
+    catch(...){
+        assert(false); // never arrive here
+    }
+    // solution: replace char with safe<char>
+    std::cout << "Using safe numerics" << std::endl;
+    try{
+        using namespace boost::numeric;
+        safe<char> x = 127;
+        safe<char> y = 2;
+        safe<char> z;
+        // rather than producing and invalid result an exception is thrown
+        z = x + y;
+        assert(false); // never arrive here
+    }
+    catch(std::range_error & e){
+        // which can catch here
+        std::cout << e.what() << std::endl;
+        detected_msg(true);
+    }
+    return 0;
+}
+
+
+
+

+Problem: Undetected overflow

+

A variation of the above is when a value is incremented/decremented + beyond it's domain. This is a common problem with for loops.

+
#include <cassert>
+#include <stdexcept>
+#include <iostream>
+
+#include "../include/safe_integer.hpp"
+//#include "../include/safe_compare.hpp"
+
+void detected_msg(bool detected){
+    std::cout << (detected ? "error detected!" : "error NOT detected! ") << std::endl;
+}
+
+int main(int argc, const char * argv[]){
+    std::cout << "example 3: ";
+    std::cout << "implicit conversions change data values" << std::endl;
+    std::cout << "Not using safe numerics" << std::endl;
+    try{
+        int x = -1000;
+        // the following silently produces an incorrect result
+        char y = x;
+        detected_msg(false);
+    }
+    catch(...){
+        assert(false); // never arrive here
+    }
+    // solution: replace int with safe<int> and char with safe<char>
+    std::cout << "Using safe numerics" << std::endl;
+    try{
+        using namespace boost::numeric;
+        safe<int> x = -1000;
+        // throws exception when conversion change data value
+        safe<char> y = x;
+        assert(false); // never arrive here
+    }
+    catch(std::range_error & e){
+        std::cout << e.what() << std::endl;
+        detected_msg(true);
+    }
+    return 0;
+}
+
+
+
+

+Problem: Implicit conversions change data values

+

A simple assign or arithment expression will generally convert all + the terms to the same type. Sometimes this can silently change values. For + example, when a signed data variable contains a negative type, assigning + to a unsigned type will be permitted by any C/C++ compiler but will be + treated as large unsigned value. Most modern compilers will emit a compile + time warning when this conversion is performed. The user may then decide + to change some data types or apply a static_cast. This is + less than satisfactory for two reasons:

+
    +

  • It may be unwield to change all the types to signed or + unsigned.

    • +

  • Litering one's program with static_cast + makes it more difficult to read.

    • +

  • We may believe that our signed type will never contain a + negative value. If we use a static_cast to suppress the + warning, we'll fail to detect a program error when it is commited. + This is aways a risk with casts.

    • +
+

This solution is the same as the above, Just replace instances of + the int with safe<int>.

+
#include <cassert>
+#include <stdexcept>
+#include <iostream>
+
+#include "../include/safe_integer.hpp"
+//#include "../include/safe_compare.hpp"
+
+void detected_msg(bool detected){
+    std::cout << (detected ? "error detected!" : "error NOT detected! ") << std::endl;
+}
+
+int main(int argc, const char * argv[]){
+    std::cout << "example 2:";
+    std::cout << "undetected overflow in data type" << std::endl;
+    try{
+        int x = INT_MAX;
+        // the following silently produces an incorrect result
+        ++x;
+        std::cout << x << " != " << INT_MAX << " + 1" << std::endl;
+        detected_msg(false);
+    }
+    catch(...){
+        assert(false); // never arrive here
+    }
+    // solution: replace int with safe<int>
+    try{
+        using namespace boost::numeric;
+        safe<int> x = INT_MAX;
+        // throws exception when result is past maximum possible 
+        ++x;
+        assert(false); // never arrive here
+    }
+    catch(std::range_error & e){
+        std::cout << e.what();
+        detected_msg(true);
+    }
+    return 0;
+}
+
+
-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
-PrevUpHomeNext +PrevUpHomeNext
diff --git a/doc/html/tutorial/1.html b/doc/html/tutorial/1.html deleted file mode 100644 index abad8a4..0000000 --- a/doc/html/tutorial/1.html +++ /dev/null @@ -1,102 +0,0 @@ - - - -Problem: Arithmetic operations can yield in correct results. - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-Problem: Arithmetic operations can yield in correct - results.

-

When some operation results in a result which exceeds the capacity - of a data variable to hold it, the result is undefined. This is called - "overflow". Since word size can differ between machines, code which - produces correct results in one set of circumstances may fail when - re-compiled on a machine with different hardware. When this occurs, Most - C++ compilers will continue to execute with no indication that the results - are wrong. It is the programmer's responsabiity to ensure such undefined - behavior is avoided.

-

This program demonstrates this problem. The solution is to replace - instances of char type with safe<char> - type.

-
#include <cassert>
-#include <stdexcept>
-#include <iostream>
-
-#include "../include/safe_integer.hpp"
-//#include "../include/safe_compare.hpp"
-
-void detected_msg(bool detected){
-    std::cout << (detected ? "error detected!" : "error NOT detected! ") << std::endl;
-}
-
-int main(int argc, const char * argv[]){
-    std::cout << "example 1:";
-    std::cout << "undetected erroneous expression evaluation" << std::endl;
-    std::cout << "Not using safe numerics" << std::endl;
-    try{
-        char x = 127;
-        char y = 2;
-        char z;
-        // this produces an invalid result !
-        z = x + y;
-        // it is the wrong result !!!
-        assert(z != 129);
-        // but assert fails to detect it since C++ implicitly
-        // converts variables to int before evaluating he expression!
-        assert(z != x + y);
-        std::cout << static_cast<int>(z) << " != " << x + y << std::endl;
-        detected_msg(false);
-    }
-    catch(...){
-        assert(false); // never arrive here
-    }
-    // solution: replace char with safe<char>
-    std::cout << "Using safe numerics" << std::endl;
-    try{
-        using namespace boost::numeric;
-        safe<char> x = 127;
-        safe<char> y = 2;
-        safe<char> z;
-        // rather than producing and invalid result an exception is thrown
-        z = x + y;
-        assert(false); // never arrive here
-    }
-    catch(std::range_error & e){
-        // which can catch here
-        std::cout << e.what() << std::endl;
-        detected_msg(true);
-    }
-    return 0;
-}
-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/tutorial/2.html b/doc/html/tutorial/2.html deleted file mode 100644 index a6a1e6b..0000000 --- a/doc/html/tutorial/2.html +++ /dev/null @@ -1,81 +0,0 @@ - - - -Problem: Undetected overflow - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-Problem: Undetected overflow

-

A variation of the above is when a value is incremented/decremented - beyond it's domain. This is a common problem with for loops.

-
#include <cassert>
-#include <stdexcept>
-#include <iostream>
-
-#include "../include/safe_integer.hpp"
-//#include "../include/safe_compare.hpp"
-
-void detected_msg(bool detected){
-    std::cout << (detected ? "error detected!" : "error NOT detected! ") << std::endl;
-}
-
-int main(int argc, const char * argv[]){
-    std::cout << "example 3: ";
-    std::cout << "implicit conversions change data values" << std::endl;
-    std::cout << "Not using safe numerics" << std::endl;
-    try{
-        int x = -1000;
-        // the following silently produces an incorrect result
-        char y = x;
-        detected_msg(false);
-    }
-    catch(...){
-        assert(false); // never arrive here
-    }
-    // solution: replace int with safe<int> and char with safe<char>
-    std::cout << "Using safe numerics" << std::endl;
-    try{
-        using namespace boost::numeric;
-        safe<int> x = -1000;
-        // throws exception when conversion change data value
-        safe<char> y = x;
-        assert(false); // never arrive here
-    }
-    catch(std::range_error & e){
-        std::cout << e.what() << std::endl;
-        detected_msg(true);
-    }
-    return 0;
-}
-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/tutorial/3.html b/doc/html/tutorial/3.html deleted file mode 100644 index 66fcba5..0000000 --- a/doc/html/tutorial/3.html +++ /dev/null @@ -1,98 +0,0 @@ - - - -Problem: Implicit conversions change data values - - - - - - - - - - - - - - - -
pre-boostHomeLibrariesPeopleFAQMore
-
-
-PrevUpHomeNext -
-
-

-Problem: Implicit conversions change data values

-

A simple assign or arithment expression will generally convert all - the terms to the same type. Sometimes this can silently change values. For - example, when a signed data variable contains a negative type, assigning - to a unsigned type will be permitted by any C/C++ compiler but will be - treated as large unsigned value. Most modern compilers will emit a compile - time warning when this conversion is performed. The user may then decide - to change some data types or apply a static_cast. This is - less than satisfactory for two reasons:

-
    -

  • It may be unwield to change all the types to signed or - unsigned.

    • -

  • Litering one's program with static_cast - makes it more difficult to read.

    • -

  • We may believe that our signed type will never contain a - negative value. If we use a static_cast to suppress the - warning, we'll fail to detect a program error when it is commited. - This is aways a risk with casts.

    • -
-

This solution is the same as the above, Just replace instances of - the int with safe<int>.

-
#include <cassert>
-#include <stdexcept>
-#include <iostream>
-
-#include "../include/safe_integer.hpp"
-//#include "../include/safe_compare.hpp"
-
-void detected_msg(bool detected){
-    std::cout << (detected ? "error detected!" : "error NOT detected! ") << std::endl;
-}
-
-int main(int argc, const char * argv[]){
-    std::cout << "example 2:";
-    std::cout << "undetected overflow in data type" << std::endl;
-    try{
-        int x = INT_MAX;
-        // the following silently produces an incorrect result
-        ++x;
-        std::cout << x << " != " << INT_MAX << " + 1" << std::endl;
-        detected_msg(false);
-    }
-    catch(...){
-        assert(false); // never arrive here
-    }
-    // solution: replace int with safe<int>
-    try{
-        using namespace boost::numeric;
-        safe<int> x = INT_MAX;
-        // throws exception when result is past maximum possible 
-        ++x;
-        assert(false); // never arrive here
-    }
-    catch(std::range_error & e){
-        std::cout << e.what();
-        detected_msg(true);
-    }
-    return 0;
-}
-
-
- - - -
Copyright © 2012 Robert Ramey

Subject to Boost Software License

-
-
-
-PrevUpHomeNext -
- - diff --git a/doc/html/types.html b/doc/html/types.html index f9c4a82..a554b7e 100644 --- a/doc/html/types.html +++ b/doc/html/types.html @@ -6,40 +6,387 @@ - - + + - +
pre-boost HomeLibrariesLibraries People FAQ More
-PrevUpHomeNext +PrevUpHomeNext

Types

-
safe_unsigned_range<MIN, MAX>
-
safe_signed_range<boost::intmax_t MIN, +
safe_unsigned_range<MIN, MAX>
+
safe_signed_range<boost::intmax_t MIN, boost::intmax_tMAX>
-
safe<T>
+
safe<T>
+
+

+safe_unsigned_range<MIN, MAX>

+
+
Description
+
Template Parameters
+
Model of
+
Header
+
Example of use
+
See Also
+
+
+

+Description

+

This type holds a integer in the range [MIN, MAX]. It will throw a + std::out_of_range exception for any operation which would + result in assigning an integer value outside of this range.

+
+
+

+Template Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequirementsDescription
MINmust be a positive integer literalThe minimum integer value that this type may hold
MAXmust be a positive integer literalThe maximum integer value that this type may hold
MIN < MAX 
+
+
+

+Model of

+

Numeric

+

The usage of this type in an arithmetic expression with another + unsigned type will result in another unsigned type fulfilling the Numeric concept. This will be the + smallest unsigned integer type of sufficient size to hold the result of + the operation.

+
+
+

+Header

+

#include + <safe/numeric/safe_range.hpp>

+
+
+

+Example of use

+
#include <safe/numeric/safe_range.hpp>
+
+void f(){
+    boost::numeric::safe_unsigned_range<7, 24> i;
+    i = 0;  // throws out_of_range exception
+    i = 9;  // ok
+    i *= 9; // throws out_of_range exception
+    i = -1; // throws out_of_range exception
+
+    std::uint8_t j = 4;
+    auto k = i + j;
+        // since i can vary between 7 and 24 and j can vary between 0 and 255
+        // the smallest unsigned integer which can hold the result std::uint16_t
+        // j will be of type std::uint16_t 
+    
+}
+
+
+

+See Also

+

std::out_of_range

+

safe_signed_range

+
+
+
+

+safe_signed_range<boost::intmax_t MIN, + boost::intmax_tMAX>

+
+
Description
+
Template Parameters
+
Model of
+
Header
+
Example of use
+
See Also
+
+
+

+Description

+

This type holds a integer in the range [MIN, MAX]. It will throw a + std::out_of_range exception for operation which would result + in assigning an integer value outside of this range.

+
+
+

+Template Parameters

+
+++++ + + + + + + + + + + + + + + + + + + + + + + +
ParameterRequirementsDescription
MINmust be an integer literalThe minimum integer value that this type may hold
MAXmust be an integer literalThe maximum integer value that this type may hold
MIN < MAX 
+
+
+

+Model of

+

Numeric

+

The usage of this type in an arithmetic expression will result in + another type fulfilling the Numeric concept.

+

Operations on safe_signed_range will result in the same

+
+
+

+Header

+

#include + <boost/safe_numerics/safe_range.hpp>

+
+
+

+Example of use

+
#include <safe/numeric/safe_range.hpp>
+
+void f(){
+    boost::numeric::safe_signed_range<7, 24> i;
+    i = 0; // error
+    i = 9; // ok
+    i *= 9; // throws overflow exception
+
+    std::int8_t j = 4;
+    auto k = i + j;
+        // since i can vary between 7 and 24 and j can vary between 0 and 255
+        // the smallest unsigned integer which can hold the result std::int16_t
+        // j will be of type std::int16_t 
+}
+
+
+

+See Also

+

std::out_of_range

+

safe_unsigned_range

+
+
+
+

+safe<T>

+
+
Description
+
Notation
+
Template Parameters
+
Model of
+
Valid Expressions
+
Header
+
Example of use
+
Notes
+
See Also
+
+
+

+Description

+

A safe<T> can be used anywhere a type T is used. + When T is used in operation which overflows, a exception is thrown

+
+
+

+Notation

+
++++ + + + + + + + + + + + + + + + + + + +
SymbolDescription
T, U, VTypes which model the Numeric concept
t, u, vobjects of types T
stobject of type safe<T>
+
+
+

+Template Parameters

+
+++++ + + + + + + + + + + +
ParameterType RequirementsDescription
Tboost::is_integer<T>::value + == true

The underlying intrinsic integer type

+
+
+

+Model of

+

Numeric

+

If the resulting type of the operation t op u is V, the resulting + type of the operations st op su, t op su and st op u will be + safe<V>;

+
+
+

+Valid Expressions

+
+++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + +
ExpressionResultDescription
st op usafe<decltype(t + op u)>

op is any valid binary operator for type + T

t op susafe<decltype(t + op u)>

op is any valid binary operator for type + T

st op susafe<decltype(t + op u)>

op is any valid binary operator for type + T

T * Utypeof(T * + U)

The underlying integer type

+
+
+

+Header

+

#include + <boost/safe_numerics/safe_integer.hpp>

+
+
+

+Example of use

+

The following program will emit an error message on a machine where + int is only 16 bits but run without problem on a machine where int is 32 + bits.

+
#include <boost/numeric/safe.hpp>
+#include <iostream>
+void f(){
+    safe<int> i = 400;
+    safe<int> j;
+    try {
+        j = i * i;
+    }
+    catch(...){
+       std::cout << "overflow error" << std::endl;
+    }
+}
+
+
+
+
+

+Notes

+

Footnotes (if any) that are referred to by other parts of the + page.

+
+
+

+See Also

+

Footnotes (if any) that are referred to by other parts of the + page.

+
+
-
Copyright © 2012 Robert Ramey

Subject to Boost Software License

+
Copyright © 2012 Robert Ramey

http://www.boost.org/LICENSE_1_0.txt">Subject to Boost Software License
-PrevUpHomeNext +PrevUpHomeNext