From 7fbaff67baccbbc0cef29cac31fec2968f2246ac Mon Sep 17 00:00:00 2001 From: Robert Ramey Date: Sun, 31 Aug 2014 15:37:28 -0700 Subject: [PATCH] corrected misc documentation errors --- doc/boostbook/makehtml.sh | 0 doc/boostbook/safe_cast.xml | 2 +- doc/boostbook/safe_compare.xml | 2 +- doc/html/boostbook.css | 6 +- doc/html/functions.html | 6 +- doc/html/index.html | 10 ++-- doc/html/notes.html | 8 +-- doc/html/numeric.html | 38 ++++++------- doc/html/rationale.html | 20 +++---- doc/html/rationale/overflow.html | 22 +++---- doc/html/safe.html | 95 +++++++++++++++++++------------ doc/html/safe_cast.html | 34 +++++------ doc/html/safe_compare.html | 47 ++++++++------- doc/html/safe_signed_range.html | 39 ++++++++----- doc/html/safe_unsigned_range.html | 40 ++++++++----- doc/html/tutorial/1.html | 23 ++++++-- doc/html/tutorial/2.html | 34 +++++++---- doc/html/tutorial/3.html | 19 ++++++- doc/html/types.html | 3 +- 19 files changed, 273 insertions(+), 175 deletions(-) mode change 100644 => 100755 doc/boostbook/makehtml.sh diff --git a/doc/boostbook/makehtml.sh b/doc/boostbook/makehtml.sh old mode 100644 new mode 100755 diff --git a/doc/boostbook/safe_cast.xml b/doc/boostbook/safe_cast.xml index 92e0e9e..245e7ff 100644 --- a/doc/boostbook/safe_cast.xml +++ b/doc/boostbook/safe_cast.xml @@ -2,7 +2,7 @@
- safe_cast + safe_cast<T, U>
Synopsis diff --git a/doc/boostbook/safe_compare.xml b/doc/boostbook/safe_compare.xml index 6db8275..ee7aaa7 100644 --- a/doc/boostbook/safe_compare.xml +++ b/doc/boostbook/safe_compare.xml @@ -2,7 +2,7 @@
- safe_compare + safe_compare<T, U>
Synopsis diff --git a/doc/html/boostbook.css b/doc/html/boostbook.css index f106e46..2e15c01 100644 --- a/doc/html/boostbook.css +++ b/doc/html/boostbook.css @@ -205,7 +205,7 @@ Table of contents =============================================================================*/ - .toc + div.toc { margin: 1pc 4% 0pc 4%; padding: 0.1pc 1pc 0.1pc 1pc; @@ -466,7 +466,7 @@ } /* Table of contents */ - .toc + div.toc { border: 1px solid #DCDCDC; } @@ -534,7 +534,7 @@ } /* Table of contents */ - .toc + div.toc { border: 1px solid gray; } diff --git a/doc/html/functions.html b/doc/html/functions.html index bda9f61..46373c1 100644 --- a/doc/html/functions.html +++ b/doc/html/functions.html @@ -7,7 +7,7 @@ - + @@ -26,8 +26,8 @@

Functions

-
safe_cast
-
safe_compare
+
safe_cast<T, U>
+
safe_compare<T, U>
overflow
diff --git a/doc/html/index.html b/doc/html/index.html index 8400a0f..1ad5efe 100644 --- a/doc/html/index.html +++ b/doc/html/index.html @@ -27,7 +27,7 @@

Copyright © 2012 Robert Ramey

@@ -46,13 +46,13 @@
Types
safe_unsigned_range<MIN, MAX>
-
safe_signed_range<MIN, MAX>
+
safe_signed_range<MIN,>
safe<T>
Functions
-
safe_cast
-
safe_compare
+
safe_cast<T, U>
+
safe_compare<T, U>
overflow
Rationale
@@ -63,7 +63,7 @@
- +

Last revised: , at

Last revised: ,

diff --git a/doc/html/notes.html b/doc/html/notes.html index 1c7dc9c..e11e487 100644 --- a/doc/html/notes.html +++ b/doc/html/notes.html @@ -32,13 +32,13 @@ tests for my embedded systems projects on my PC. Still, I had a few issues.

    -

  • I was a lot of code in one header - 6400 lines. Very unwieldy to - understand and modify.

    • +

  • It was a lot of code in one header - 6400 lines. Very unwieldy + to understand and modify.

  • I couldn't find separate documentation other than that in the header file.

    • -

  • I didn't use Boost +

  • It didn't use Boost conventions for naming.

    • -

  • I required porting to different compilers.

    • +

  • It required porting to different compilers.

  • It had a very long license associated with it.

  • The package I downloaded didn't have a test suite

  • I believe the original SafeInt diff --git a/doc/html/numeric.html b/doc/html/numeric.html index 12276e8..4f36747 100644 --- a/doc/html/numeric.html +++ b/doc/html/numeric.html @@ -26,16 +26,16 @@

    Numeric<T>

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

    -Description

    +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 @@ -50,9 +50,9 @@

-Notation

+Notation
-

Table 1. Notation

+

Table 1. Notation

@@ -74,9 +74,9 @@

-Associated Types

+Associated Types
-

Table 2. Associated Types

+

Table 2. Associated Types

@@ -95,13 +95,13 @@

-Valid Expressions

+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

+

Table 3. General

@@ -131,7 +131,7 @@


-

Table 4. Unary Operators

+

Table 4. Unary Operators

@@ -183,7 +183,7 @@

-

Table 5. Binary Operators

+

Table 5. Binary Operators

@@ -199,12 +199,12 @@ - + - + @@ -339,13 +339,13 @@

-Header

+Header

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

-Models

+Models

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

diff --git a/doc/html/rationale.html b/doc/html/rationale.html index dc609f6..3e307ff 100644 --- a/doc/html/rationale.html +++ b/doc/html/rationale.html @@ -26,15 +26,15 @@

Rationale

-
-
1. Why does a binary operation on two - safe<int> values not necessarily return another +
+
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.
t - u VInvert signsubtract u from t
t + u Vunary plus - a no opadd u to t
t * u
@@ -43,10 +43,10 @@ @@ -54,7 +54,7 @@
-

1.

+

1.

Why does a binary operation on two - safe<int> values not necessarily return another + safe<int> values not return another safe type ?

There are a number of

    -

  • it was hard to implement.

    • +

  • it was too hard to implement.

  • it doesn't really seem necessary. We always do SOMETHING with result of the operation. This will result in an assignment or a conversion to some other type where the result will be @@ -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.

diff --git a/doc/html/rationale/overflow.html b/doc/html/rationale/overflow.html index 7fb41c7..612ade8 100644 --- a/doc/html/rationale/overflow.html +++ b/doc/html/rationale/overflow.html @@ -6,7 +6,7 @@ - + @@ -26,22 +26,22 @@

overflow

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

-Synopsis

+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

+Description

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

If the environment does not support C++ exceptions, the user should @@ -55,13 +55,13 @@

-Header

+Header

#include <boost/safe_numerics/overflow.hpp>

-Example of use

+Example of use
#include <cstdio>
 
 void overflow(char const * const msg){
@@ -72,7 +72,7 @@ void overflow(char const * const msg){
 
 

 

-See Also

+See Also

 
See rationale for more
     information on this function

 
diff --git a/doc/html/safe.html b/doc/html/safe.html
index edafc28..cb70f5f 100644
--- a/doc/html/safe.html
+++ b/doc/html/safe.html
@@ -6,7 +6,7 @@
 
 
 
-
+
 
 
 
@@ -26,26 +26,49 @@
 

 safe<T>

 

-
Description

-
Template Parameters

-
Model of

-
Derived From

-
Notation

-
Header

-
Example of use

-
Notes

-
See Also

+
Description

+
Notation

+
Template Parameters

+
Model of

+
Valid Expressions

+
Header

+
Example of use

+
Notes

+
See Also

 

 

 

-Description

+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

 
 

 

-Template Parameters

-

+Notation

+

++++
+
+
+
+
+
+
+
+
+
+
+
+
+
+
+




SymbolDescription
T, U, VTypes which model the Numeric concept
t, u, vobjects of types T and U respectively

+
+

+

+Template Parameters

 
@@ -59,58 +82,60 @@
 
-
-
+
+

 
 

 

 TNumeric
The underlying integer type
boost::is_integer<T>::value
+            == true
The underlying intrinsic integer type

 

 

 

 

 

-Model of

+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>;

 
 

 

-Derived From

-
safe_signed_range<T>
-    (if std::numeric_limits<T>::is_signed == ftrue)

-
safe_unsigned_range<T>
-    (if std::numeric_limits<T>::is_signed == ftrue)

-

-

-

-Notation

+Valid Expressions

 
+
-
+
+
-
-
+
+
+
-
-
+
+
+

 
 
 

 
 
SymbolParameterResult
 Description
 

 
 
TA type that models the Numeric conceptst op usafe<decltype(t
+              op u)>
op is any valid binary operator for types T and
+              U

 

 
tAn object of type T
-T * Utypeof(T *
+              U)
The underlying integer type

 

 
 

 
 

 

-Header

+Header

 
#include
     <boost/safe_numerics/safe_integer.hpp>

 
 

 

-Example of use

+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.

@@ -131,13 +156,13 @@ void f(){
 
 

 

-Notes

+Notes

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

 
 

 

-See Also

+See Also

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

 
diff --git a/doc/html/safe_cast.html b/doc/html/safe_cast.html
index 741724b..3c88394 100644
--- a/doc/html/safe_cast.html
+++ b/doc/html/safe_cast.html
@@ -1,13 +1,13 @@
 
 
 
-safe_cast
+safe_cast<T, U>
 
 
 
 
 
-
+
 
 
 
@@ -24,32 +24,32 @@
 

 

-safe_cast

+safe_cast<T, U>

-
Synopsis

-
Description

-
Type requirements

-
Preconditions

-
Complexity

-
Header

-
Example of use

+
Synopsis

+
Description

+
Type requirements

+
Preconditions

+
Complexity

+
Header

+
Example of use

 

 

-Synopsis

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

 

-Description

+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

+Type requirements

 
 
 
 
 
 
 
 
 
 
@@ -73,27 +73,27 @@ T safe_cast(const U & u);

 

-Preconditions

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

 

-Complexity

+Complexity
[Example:]
O(N log(N)) comparisons (both average and worst-case), where N is
     last - first. [2]

 

-Header

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

 

-Example of use

+Example of use
[A code fragment that illustrates how to use the function.]
#include <boost/numeric/safe_cast.hpp> 
 #include <boost/numeric/safe_integer.hpp> 
diff --git a/doc/html/safe_compare.html b/doc/html/safe_compare.html
index 78f8285..6e31b6a 100644
--- a/doc/html/safe_compare.html
+++ b/doc/html/safe_compare.html
@@ -1,12 +1,12 @@
 
 
 
-safe_compare
+safe_compare<T, U>
 
 
 
 
-
+
 
 
 
@@ -24,27 +24,39 @@
 
 

 

-safe_compare

+safe_compare<T, U>

 

-
Synopsis

-
Description

-
Type requirements

-
Header

-
Example of use

+
Synopsis

+
Description

+
Type requirements

+
Header

+
Example of use

 

 

 

-Synopsis

-
safe_compare is really two functions:.

+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::greater_than(const T & lhs, const U & rhs);

+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::equa(const T & lhs, const U & rhs);
+
+template<class T, class U>
+bool safe_compare::not_equal(const T & lhs, const U & rhs);

 

-Description

+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++
@@ -54,10 +66,7 @@ bool safe_compare::greater_than(const T & lhs, const U & rhs);
 
 

 

-Type requirements

-
[This section lists the requirements that must be satisfied by the
-    function's template parameters. If the function has no template
-    parameters, this section can be skipped. Example:]

+Type requirements

 
 

 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
@@ -81,15 +90,13 @@ bool safe_compare::greater_than(const T & lhs, const U & rhs);

 

-Header

-
[A link to the source code where the function header is
-    defined.]

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

 

-Example of use

+Example of use
#include <boost/numeric/safe_compare.hpp>
 
 void f(){
diff --git a/doc/html/safe_signed_range.html b/doc/html/safe_signed_range.html
index 38d155e..ba53500 100644
--- a/doc/html/safe_signed_range.html
+++ b/doc/html/safe_signed_range.html
@@ -1,7 +1,7 @@
 
 
 
-safe_signed_range<MIN, MAX>
+safe_signed_range<boost::intmax_t MIN, boost::intmax_tMAX>
 
 
 
@@ -24,25 +24,26 @@
 
 

 

-safe_signed_range<MIN, MAX>

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

 

-
Description

-
Template Parameters

-
Model of

-
Header

-
Example of use

-
See Also

+
Description

+
Template Parameters

+
Model of

+
Header

+
Example of use

+
See Also

 

 

 

-Description

+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

+Template Parameters

 

 
 

 
 
 
 
 
 
@@ -75,18 +76,21 @@
 

 

-Model of

+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

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

 

-Example of use

+Example of use
#include <safe/numeric/safe_range.hpp>
 
 void f(){
@@ -94,12 +98,19 @@ void f(){
     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

+See Also
std::out_of_range

+
safe_unsigned_range

 
 

 
 
 
 
 
 
 
 
 
 
 
 
 
 

diff --git a/doc/html/safe_unsigned_range.html b/doc/html/safe_unsigned_range.html
index 4c39116..eacd8bd 100644
--- a/doc/html/safe_unsigned_range.html
+++ b/doc/html/safe_unsigned_range.html
@@ -7,7 +7,7 @@
 
-
+

 
 
 
 
 

@@ -26,23 +26,23 @@
 

 safe_unsigned_range<MIN, MAX>

-
Description

-
Template Parameters

-
Model of

-
Header

-
Example of use

-
See Also

+
Description

+
Template Parameters

+
Model of

+
Header

+
Example of use

+
See Also

 

 

-Description

+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.

+    result in assigning an integer value outside of this range. 

 

-Template Parameters

+Template Parameters

 
 
 
 
 
 
@@ -75,18 +75,22 @@
 

 

-Model of

+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

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

 

-Example of use

+Example of use
#include <safe/numeric/safe_range.hpp>
 
 void f(){
@@ -95,12 +99,20 @@ void f(){
     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

+See Also
std::out_of_range

+
safe_signed_range

 
 

 
 
 
 
 
 
 
 
 
 
 
 
 
 

diff --git a/doc/html/tutorial/1.html b/doc/html/tutorial/1.html
index 16a9d2c..233fb13 100644
--- a/doc/html/tutorial/1.html
+++ b/doc/html/tutorial/1.html
@@ -36,8 +36,21 @@
 
This program demonstrates this problem. The solution is to replace
     instances of char type with safe<char>
     type.

-
void example1(){
-    // problem: undetected erroneous expression evaluation
+
#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;
@@ -49,13 +62,14 @@
         // 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::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;
@@ -67,9 +81,10 @@
     }
     catch(std::range_error & e){
         // which can catch here
-        std::cout << e.what();
+        std::cout << e.what() << std::endl;
         detected_msg(true);
     }
+    return 0;
 }
 

 
diff --git a/doc/html/tutorial/2.html b/doc/html/tutorial/2.html
index 3144e7c..515c6b2 100644
--- a/doc/html/tutorial/2.html
+++ b/doc/html/tutorial/2.html
@@ -27,30 +27,44 @@
 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.

-
void example3(){
-    // problem: undetected overflow in data 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 3: ";
+    std::cout << "implicit conversions change data values" << std::endl;
+    std::cout << "Not using safe numerics" << std::endl;
     try{
-        int x = INT_MAX;
+        int x = -1000;
         // the following silently produces an incorrect result
-        ++x;
-        //std::cout << x << " != " << -1;
+        char y = x;
         detected_msg(false);
     }
     catch(...){
         assert(false); // never arrive here
     }
-    // solution: replace int with safe<int>
+    // 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 = INT_MAX;
-        // throws exception when result is past maximum possible 
-        ++x;
+        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::cout << e.what() << std::endl;
         detected_msg(true);
     }
+    return 0;
 }
 

 
diff --git a/doc/html/tutorial/3.html b/doc/html/tutorial/3.html
index 828f099..25ed365 100644
--- a/doc/html/tutorial/3.html
+++ b/doc/html/tutorial/3.html
@@ -45,13 +45,25 @@
 
 
This solution is the same as the above, Just replace instances of
     the int with safe<int>.

-
void example2(){
-    // problem: undetected overflow in data 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 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 << " != " << -1;
+        std::cout << x << " != " << INT_MAX << " + 1" << std::endl;
         detected_msg(false);
     }
     catch(...){
@@ -69,6 +81,7 @@
         std::cout << e.what();
         detected_msg(true);
     }
+    return 0;
 }
 

 
diff --git a/doc/html/types.html b/doc/html/types.html
index 44becdd..f9c4a82 100644
--- a/doc/html/types.html
+++ b/doc/html/types.html
@@ -27,7 +27,8 @@
 Types
 

 
safe_unsigned_range<MIN, MAX>

-
safe_signed_range<MIN, MAX>

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

 
safe<T>