From 1d283ac69e9aa2a508c434d7aabc9db1d9157b85 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 11:27:13 -0800 Subject: [PATCH 01/37] Update README.md Fixed some typos. --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index dfcae81..95f90a3 100644 --- a/README.md +++ b/README.md @@ -1,7 +1,7 @@ safe_numerics ============= -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++ programmer to guarentee that this behavior does not result in incorrect behavior of the program. This library implements special versions of these data types which behave exactly like the original ones EXCEPT that the results of these operations are checked to be sure that an exception will be thrown anytime an attempt is made to store the result of an undefined operation. +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 upon the C++ programmer to guarantee that this behavior does not result in incorrect behavior of the program. This library implements special versions of these data types which behave exactly like the original ones EXCEPT that the results of these operations are checked to be sure that an exception will be thrown anytime an attempt is made to store the result of an undefined operation. Additionally, we define data types safe_signed_range and safe_unsigned_range which will throw an exception if an attempt is made to store a result which is outside the closed range [MIN, MAX] From 039d2a58e372abfba4ac478c8ef3987b7c5cebaa Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 11:49:14 -0800 Subject: [PATCH 02/37] Update safe_introduction.xml --- doc/boostbook/safe_introduction.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/boostbook/safe_introduction.xml b/doc/boostbook/safe_introduction.xml index 8766f6e..36acb4c 100644 --- a/doc/boostbook/safe_introduction.xml +++ b/doc/boostbook/safe_introduction.xml @@ -101,8 +101,8 @@ safe<int> f(safe<int> x, safe<int> y){ - Library code in this document resides in the name space - boost::numeric. This name space has generally been + Library code in this document resides in the namespace + boost::numeric. This namespace has generally been eliminated from text, code and examples in order to improve readability of the text. The addition expression is checked at runtime or (if possible) at @@ -214,7 +214,7 @@ safe<int> f(safe<int> x, safe<int> y){ - Enforce of other program requirements using ranged integer + Enforce other program requirements using ranged integer types. The library includes the types safe_range<Min, Max> and safe_literal<N>. These types can be used to improve program correctness and performance. From 82e4ad1d40eee031f1d47f519814efc1b9fc1c4b Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 12:01:27 -0800 Subject: [PATCH 03/37] Update tutorial.xml --- doc/boostbook/tutorial.xml | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/doc/boostbook/tutorial.xml b/doc/boostbook/tutorial.xml index aaee84a..e704811 100644 --- a/doc/boostbook/tutorial.xml +++ b/doc/boostbook/tutorial.xml @@ -20,15 +20,11 @@ responsibility to ensure such undefined behavior is avoided. This program demonstrates this problem. The solution is to replace - instances of char type with safe<char> + instances of int type with safe<int> type. - - Note that I've used char types in this example to make - the problem and solution easier to see. The exact same example could have - been done with int types albeit with different values.
From 8b3769f1d7370db8a662e47f7029e48c43f5015e Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 12:58:36 -0800 Subject: [PATCH 04/37] Update example1.cpp --- examples/example1.cpp | 11 ++++------- 1 file changed, 4 insertions(+), 7 deletions(-) diff --git a/examples/example1.cpp b/examples/example1.cpp index 35f9ba1..0c6cd5f 100644 --- a/examples/example1.cpp +++ b/examples/example1.cpp @@ -15,10 +15,7 @@ int main(int argc, const char * argv[]){ int z; // this produces an invalid result ! z = x + y; - // 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(z) << " != " << x + y << std::endl; + std::cout << z << " != " << x + y << std::endl; std::cout << "error NOT detected!" << std::endl; } catch(std::exception){ @@ -28,14 +25,14 @@ int main(int argc, const char * argv[]){ std::cout << "Using safe numerics" << std::endl; try{ using namespace boost::numeric; - safe x = 127; + safe x = INT_MAX; safe y = 2; safe z; - // rather than producing and invalid result an exception is thrown + // rather than producing an invalid result an exception is thrown z = x + y; } catch(std::exception & e){ - // which can catch here + // which we can catch here std::cout << e.what() << std::endl; } return 0; From 78a52fce0038ee3effe986242831252ab5843c1f Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 13:09:08 -0800 Subject: [PATCH 05/37] Update tutorial.xml --- doc/boostbook/tutorial.xml | 23 +++++++++++------------ 1 file changed, 11 insertions(+), 12 deletions(-) diff --git a/doc/boostbook/tutorial.xml b/doc/boostbook/tutorial.xml index e704811..f44a8b8 100644 --- a/doc/boostbook/tutorial.xml +++ b/doc/boostbook/tutorial.xml @@ -31,7 +31,7 @@ Arithmetic Operations Can Overflow Silently A variation of the above is when a value is incremented/decremented - beyond it's domain. This is a common problem with for loops. + beyond its domain. This is a common problem with for loops. @@ -44,9 +44,8 @@
Implicit Conversions Can Lead to Erroneous Results - At CPPCon 2016 Jon Kalb gave a very entertaining (and disturbing - example) lightening talk + At CPPCon 2016 Jon Kalb gave a very entertaining (and disturbing) lightning talk related to C++ expressions. The talk included a very, very simple example similar to the @@ -58,7 +57,7 @@ A normal person reads the above code and has to be dumbfounded by this. The code doesn't do what the text - according to the rules of algebra - says it does. But C++ doesn't follow the rules of algebra - it - has it's own rules. There is generally no compile time error. You can get + has its own rules. There is generally no compile time error. You can get a compile time warning if you set some specific compile time switches. The explanation lies in reviewing how C++ reconciles binary expressions (a < b is an expression here) where operands are different @@ -67,7 +66,7 @@ Determines the "best" common type for the two operands. In - this case, application the the rules in the C++ standard dictate + this case, application of the rules in the C++ standard dictate that this type will be an unsigned int. @@ -79,7 +78,7 @@ - Performs the calculation - in this case it's, + Performs the calculation - in this case it's <, the "less than" operation. Since 1 is less than 4294967295 the program prints "b is less than a". @@ -89,21 +88,21 @@ should be pretty familiar with the implicit conversion rules of the C++ standard. These are available in a copy of the standard and also in the canonical reference book The C++ - Programming Language . (both are over 1200 pages + Programming Language (both are over 1200 pages long!). Even experienced programmers won't spot this issue and know to take precautions to avoid it. And this is a relatively easy one to spot. In the more general case this will use integers which don't correspond to easily recognizable numbers and/or will be buried as a part of some more complex expression. - This example generated a good amount of web traffic along with every - one's pet suggestions. See for example This example generated a good amount of web traffic along with + everyone's pet suggestions. See for example a blog - post with every one's favorite "solution". All the proposed + post with everyone's favorite "solution". All the proposed "solutions" have disadvantages and attempts to agree on how handle this are ultimately fruitless in spite of, or maybe because of, the emotional - content. Our solution is by far the simplest: Just use the safe + content. Our solution is by far the simplest: just use the safe numerics library as shown in the example above. Note that in this particular case, there is absolutely no extra From e07f2548618d2a466f506ca422dbd29839f825f7 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 13:09:49 -0800 Subject: [PATCH 06/37] Update example4.cpp --- examples/example4.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/example4.cpp b/examples/example4.cpp index 845e2dd..eab4ea1 100644 --- a/examples/example4.cpp +++ b/examples/example4.cpp @@ -24,7 +24,7 @@ int main(){ std::cout << "error detected!" << std::endl; } - // solution: replace int with safe and char with safe + // solution: replace int with safe and unsigned int with safe std::cout << "Using safe numerics" << std::endl; try{ using namespace boost::numeric; From d9fe05b7c544bd0c206ce79d231419bd4d6ca733 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 13:29:02 -0800 Subject: [PATCH 07/37] Update tutorial.xml --- doc/boostbook/tutorial.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/boostbook/tutorial.xml b/doc/boostbook/tutorial.xml index f44a8b8..f6ed1b4 100644 --- a/doc/boostbook/tutorial.xml +++ b/doc/boostbook/tutorial.xml @@ -130,7 +130,7 @@ Not using safe numerics Using safe numerics 10000 detected error:converted negative value to unsigned -This solution is simple, Just replace instances of the +This solution is simple, just replace instances of int with safe<int>.
@@ -144,10 +144,10 @@ detected error:converted negative value to unsigned Collections - like standard arrays, vectors do array index checking in some function + like standard arrays and vectors do array index checking in some function calls and not in others so this may not be the best example. However it does illustrate the usage of safe_range<T> for - assigning legal range to variables. This will guarantee that under no + assigning legal ranges to variables. This will guarantee that under no circumstances will the variable contain a value outside of the specified range.
From 8fc48862e98ac2f824e7a51fe6c8c983a79bcd3f Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 13:30:04 -0800 Subject: [PATCH 08/37] Update example6.cpp --- examples/example6.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/example6.cpp b/examples/example6.cpp index 4ed945f..db53d6e 100644 --- a/examples/example6.cpp +++ b/examples/example6.cpp @@ -22,7 +22,7 @@ int main(int argc, const char * argv[]){ std::cout << "error detected!" << std::endl; } - // solution: asign externally retrieved values to safe equivalents + // solution: assign externally retrieved values to safe equivalents std::cout << "Using safe numerics" << std::endl; { using namespace boost::numeric; From af51dbe5859f2476b74e30e619ccb06c9fd62f6a Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 13:33:50 -0800 Subject: [PATCH 09/37] Update tutorial.xml --- doc/boostbook/tutorial.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/boostbook/tutorial.xml b/doc/boostbook/tutorial.xml index f6ed1b4..6343b38 100644 --- a/doc/boostbook/tutorial.xml +++ b/doc/boostbook/tutorial.xml @@ -182,7 +182,7 @@ detected error:converted negative value to unsigned - invocation some configuration functions which convert these + invocation of some configuration functions which convert these hardware events into C++ exceptions It's not all that clear how one would detect and recover @@ -190,7 +190,7 @@ detected error:converted negative value to unsigned ignore the issue which usually results in immediate program termination when this situation occurs. - This library will detect for divide by zero errors before the + This library will detect divide by zero errors before the operation is invoked. Any errors of this nature are handled according to the ErrorPolicy selected by the library user. From a05cdd7ea3167906795d6610cf1c2f3fc9f7cd6e Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 13:36:55 -0800 Subject: [PATCH 10/37] Update example13.cpp --- examples/example13.cpp | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/examples/example13.cpp b/examples/example13.cpp index 3bf7ee9..2e3ce16 100644 --- a/examples/example13.cpp +++ b/examples/example13.cpp @@ -4,9 +4,9 @@ #include "../include/safe_integer.hpp" int main(int argc, const char * argv[]){ - // problem: checking of externally produced value can be overlooked + // problem: cannot recover from arithmetic errors std::cout << "example 7: "; - std::cout << "cannot recover From arithmetic errors" << std::endl; + std::cout << "cannot recover from arithmetic errors" << std::endl; std::cout << "Not using safe numerics" << std::endl; try{ @@ -21,14 +21,14 @@ int main(int argc, const char * argv[]){ std::cout << "error detected!" << std::endl; } - // solution: assign externally retrieved values to safe equivalents + // solution: replace int with safe std::cout << "Using safe numerics" << std::endl; try{ using namespace boost::numeric; safe x = 1; safe y = 0; std::cout << x / y; - std::cout << " error detected!" << std::endl; + std::cout << " error NOT detected!" << std::endl; } catch(std::exception & e){ std::cout << e.what() << std::endl; From a001df0c153ba1340052e1211d9055385211349b Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 13:42:44 -0800 Subject: [PATCH 11/37] Update tutorial.xml --- doc/boostbook/tutorial.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/boostbook/tutorial.xml b/doc/boostbook/tutorial.xml index 6343b38..4eb3fd9 100644 --- a/doc/boostbook/tutorial.xml +++ b/doc/boostbook/tutorial.xml @@ -202,7 +202,7 @@ detected error:converted negative value to unsigned Programming by Contract is Too Slow Programming by Contract is a highly regarded technique. There has - been much written about it has been proposed as an addition to the C++ + been much written about it and it has been proposed as an addition to the C++ language GarciaCrowl & Ottosen. It (mostly) depends upon runtime checking of parameter and object values upon entry to and exit from every function. This can @@ -215,15 +215,15 @@ detected error:converted negative value to unsigned runtime cost. The Safe Numerics Library has facilities which, in many cases, can - check guarantee parameter requirements with little or no runtime overhead. + check guaranteed parameter requirements with little or no runtime overhead. Consider the following example: - In the example above the function convert incurs significant runtime + In the example above, the function convert incurs significant runtime cost every time the function is called. By using "safe" types, this cost - is moved to moment when the parameters are constructed. Depending on how + is moved to the moment when the parameters are constructed. Depending on how the program is constructed, this may totally eliminate extraneous computations for parameter requirement type checking. In this scenario, there is no reason to suppress the checking for release mode and our From 08e365bdbfad0016f8cfee07c15a3d9bc04c41d9 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Thu, 2 Mar 2017 13:46:01 -0800 Subject: [PATCH 12/37] Update example7.cpp --- examples/example7.cpp | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/examples/example7.cpp b/examples/example7.cpp index de5f8ca..0bed2f6 100644 --- a/examples/example7.cpp +++ b/examples/example7.cpp @@ -12,7 +12,7 @@ unsigned int convert( const unsigned int & minutes ) { // check that parameters are within required limits - // invokes a runtime cost EVERYTIME the function is called + // invokes a runtime cost EVERY TIME the function is called // and the overhead of supporting an interrupt. // note high runtime cost! if(minutes > 59) @@ -23,7 +23,7 @@ unsigned int convert( } // Use safe numeric to enforce program contract automatically -// define convient typenames for hours and minutes hh:mm +// define convenient typenames for hours and minutes hh:mm using hours_t = boost::numeric::safe_unsigned_range<0, 23>; using minutes_t = boost::numeric::safe_unsigned_range<0, 59>; @@ -52,9 +52,9 @@ int main(int argc, const char * argv[]){ std::cout << "Using safe numerics" << std::endl; try { - // parameters are guarenteed to meet requirements + // parameters are guaranteed to meet requirements hours_t hours(10); - minutes_t minutes(83); // interrupt thrown here + minutes_t minutes(83); // exception thrown here // so the following will never throw safe_convert(hours, minutes); } @@ -76,7 +76,7 @@ int main(int argc, const char * argv[]){ } try { - // parameters are guarenteed to meet requirements when + // parameters are guaranteed to meet requirements when // implicitly constructed to safe types to match function signature safe_convert(10, 83); } @@ -102,7 +102,7 @@ int main(int argc, const char * argv[]){ convert(hours, minutes); // zero (depending on compiler) runtime overhead // since unsafe types can be implicitly converted to corresponding - // safe types we can just pass the unsafe types. checkin will occur + // safe types we can just pass the unsafe types. checking will occur // when the safe type is constructed. safe_convert(10, 17); // runtime cost in creating parameters From a4753e240100e2ff7d5be54dfe4ac1cbe2d40196 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 06:42:23 -0800 Subject: [PATCH 13/37] Update eliminate_runtime_penalty.xml --- doc/boostbook/eliminate_runtime_penalty.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/boostbook/eliminate_runtime_penalty.xml b/doc/boostbook/eliminate_runtime_penalty.xml index b71e5df..d8be0c9 100644 --- a/doc/boostbook/eliminate_runtime_penalty.xml +++ b/doc/boostbook/eliminate_runtime_penalty.xml @@ -7,7 +7,7 @@ Up until now, we've focused on detecting when incorrect results are produced and handling these occurrences either by throwing an exception or invoking some designated function. We've achieved our goal of detecting and - handling arithmetically incorrect behavior - but at what cost. It is a fact + handling arithmetically incorrect behavior - but at what cost? It is a fact that many C++ programmers will find this trade-off unacceptable. So the question arises as to how we might minimize or eliminate this runtime penalty. From 5fa28071b45f1175bda172b62201a4fab1ef7df2 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 07:15:46 -0800 Subject: [PATCH 14/37] Update example84.cpp --- examples/example84.cpp | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/examples/example84.cpp b/examples/example84.cpp index 4f25809..88768bb 100644 --- a/examples/example84.cpp +++ b/examples/example84.cpp @@ -16,7 +16,7 @@ using safe_t = safe_signed_range< trap_exception >; -// define variables use for input +// define variables used for input using input_safe_t = safe_signed_range< -24, 82, From 78cc93ea8baaf6af88013dc8479bf67a10807a61 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 07:19:04 -0800 Subject: [PATCH 15/37] Update eliminate_runtime_penalty.xml --- doc/boostbook/eliminate_runtime_penalty.xml | 22 ++++++++++----------- 1 file changed, 11 insertions(+), 11 deletions(-) diff --git a/doc/boostbook/eliminate_runtime_penalty.xml b/doc/boostbook/eliminate_runtime_penalty.xml index d8be0c9..b3123c4 100644 --- a/doc/boostbook/eliminate_runtime_penalty.xml +++ b/doc/boostbook/eliminate_runtime_penalty.xml @@ -54,12 +54,12 @@ So the result of the sum of two integer types may result in another integer type. If the values are large, the result can exceed the size that the resulting integer type can hold. This is what we call "overflow". The - C/C++ standard characterises this as undefined behavior and leaves to + C/C++ standard characterizes this as undefined behavior and leaves to compiler implementors the decision as to how such a situation will be handled. Usually, this means just truncating the result to fit into the result type - which sometimes will make the result arithmetically - incorrect. However, depending on the compiler, compile time switch - settings, the such case may result in some sort of run time + incorrect. However, depending on the compiler and compile time switch + settings, such cases may result in some sort of run time exception. The complete signature for a safe integer type is: @@ -77,7 +77,7 @@ safe; type promotion policy are consistent with those of standard C++ Up until now, we've focused on detecting when this happens and - invoking an interrupt or other kind of error handler. + invoking an exception or other kind of error handler. But now we look at another option. Using the automatic @@ -117,7 +117,7 @@ long z = (long)x + (long)y; // can never overflow Since the result type is guaranteed to hold the result, there - is no need to check for errors - they can't happen !!! The usage of + is no need to check for errors - they can't happen!!! The usage of the trap_exception exception policy enforces this guarantee. @@ -173,7 +173,7 @@ z = <long>[-4294967296,4294967294] = 2147483649 the automatic - type promotion policy has rendered the result of the some of two + type promotion policy has rendered the result of the sum of two integers as a long type. @@ -184,7 +184,7 @@ z = <long>[-4294967296,4294967294] = 2147483649 - We do not need to use try/catch idiom to handle + We do not need to use the try/catch idiom to handle arithmetic errors - we will have none. @@ -262,15 +262,15 @@ z = <signed char>[-24,82] = 77 As before, we define a type safe_t to reflect our - view of legal values for this program. This uses automatic - type promotion policy as well as trap_exception exception policy to enforce elimination of runtime penalties. - The function f accepts only arguments of type + The function f accepts only arguments of type safe_t so there is no need to check the input values. This performs the functionality of programming by contract with no @@ -289,7 +289,7 @@ z = <signed char>[-24,82] = 77 - On calling of the function f, arguments of type + On calling of the function f, arguments of type input_safe_t are converted to values of type safe_t . In this particular example, it can be determined at compile time that construction of an instance of a From 82b4609186d1a3d67b76f9be6b4e1b3796e9c08e Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 07:27:37 -0800 Subject: [PATCH 16/37] Update numeric_concept.xml --- doc/boostbook/numeric_concept.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/boostbook/numeric_concept.xml b/doc/boostbook/numeric_concept.xml index 82c7753..1faaef9 100644 --- a/doc/boostbook/numeric_concept.xml +++ b/doc/boostbook/numeric_concept.xml @@ -11,9 +11,9 @@ A type is Numeric if it has the properties of a number. - More specifically, a type T is Numeric if there exists + More specifically, a type T is Numeric if there exists a specialization of std::numeric_limits<T>. See the - documentation for standard library class numeric_limits. The + documentation for the standard library class numeric_limits. The standard library includes such specializations for all the built-in numeric types. Note that this concept is distinct from the C++ standard library type traits is_integral and @@ -42,7 +42,7 @@ t, u - An object of type modeling Numeric + An object of a type modeling Numeric From 8a66edc43e22be71059d29a3d9c775885beebe88 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 07:41:29 -0800 Subject: [PATCH 17/37] Update numeric_concept.xml --- doc/boostbook/numeric_concept.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/boostbook/numeric_concept.xml b/doc/boostbook/numeric_concept.xml index 1faaef9..c5f8f30 100644 --- a/doc/boostbook/numeric_concept.xml +++ b/doc/boostbook/numeric_concept.xml @@ -36,7 +36,7 @@ T, U, V - A type that is a model of the Numeric + A type that is a model of Numeric From ad173c89309757782350fb90a6f941cdbc717dc1 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 07:45:24 -0800 Subject: [PATCH 18/37] Update integer_concept.xml --- doc/boostbook/integer_concept.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/boostbook/integer_concept.xml b/doc/boostbook/integer_concept.xml index 881cc7c..87127d8 100644 --- a/doc/boostbook/integer_concept.xml +++ b/doc/boostbook/integer_concept.xml @@ -9,10 +9,10 @@
Description - A type is fulfills the requirements of an Integer if it has the + A type fulfills the requirements of an Integer if it has the properties of a integer. - More specifically, a type T is Integer if there exists + More specifically, a type T is Integer if there exists a specialization of std::numeric_limits<T> for which std::numeric_limits<T>.is_integer is equal to true. See the documentation for standard library class @@ -20,7 +20,7 @@ specializations for all built-in numeric types. Note that this concept is distinct from the C++ standard library type traits is_integral and is_arithmetic. These latter - fulfill the requirement of the concept Numeric. But there are types which + fulfill the requirements of the concept Numeric. But there are types which fulfill this concept for which is_arithmetic<T>::value == false. For example see safe<int>.
@@ -134,7 +134,7 @@ V - and of t and u padded out max # bits in t, u + and of t and u padded out to max # bits in t, u @@ -142,7 +142,7 @@ V - or of t and u padded out max # bits in t, u + or of t and u padded out to max # bits in t, u @@ -150,7 +150,7 @@ V - exclusive or of t and u padded out max # bits in t, + exclusive or of t and u padded out to max # bits in t, u From 25e2312b9ca1a38f632a43c5e459c32350530e56 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 07:50:42 -0800 Subject: [PATCH 19/37] Update safe_numeric_concept.xml --- doc/boostbook/safe_numeric_concept.xml | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/boostbook/safe_numeric_concept.xml b/doc/boostbook/safe_numeric_concept.xml index fa9edc7..f487838 100644 --- a/doc/boostbook/safe_numeric_concept.xml +++ b/doc/boostbook/safe_numeric_concept.xml @@ -11,7 +11,7 @@ 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 + counterparts in that they are guaranteed not to produce invalid arithmetic results. @@ -175,7 +175,7 @@ unspecified S - construct a instance of S from a value of type T. f + construct an instance of S from a value of type T. If the value t cannot be represented as an instance of type S1, it is an error. @@ -185,7 +185,7 @@ S - construct a uninitialized instance of + construct an uninitialized instance of S. @@ -216,7 +216,7 @@ - Result of any binary operation where one or both of the operands + The result of any binary operation where one or both of the operands is a SafeNumeric type is also a SafeNumeric type. @@ -250,18 +250,18 @@ int main(){ Complexity Guarantees There are no explicit complexity guarantees here. However, it would - be very surprising if any implementation were to be more complex that + be very surprising if any implementation were to be more complex than O(0);
Invariants - The fundamental requirement of a SafeNumeric type is that implements - all C++ operations permitted on it's base type in a way the prevents the + 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..) no implementation should return + concept may handle circumstances which produce such results differently + (throw exception, compile time trap, etc..) no implementation should return an arithmetically incorrect result.
From 86465e9d9906a88fab9940adac22098356981f00 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 07:54:43 -0800 Subject: [PATCH 20/37] Update promotion_policy_concept.xml --- doc/boostbook/promotion_policy_concept.xml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/boostbook/promotion_policy_concept.xml b/doc/boostbook/promotion_policy_concept.xml index c12354c..5e33056 100644 --- a/doc/boostbook/promotion_policy_concept.xml +++ b/doc/boostbook/promotion_policy_concept.xml @@ -16,7 +16,7 @@ char y; auto z = x + ythe type of z will be an int. This is a consequence for the standard rules for type - promotion for C/C++ arithmetic. A key feature of library permits one to + promotion for C/C++ arithmetic. A key feature of the library permits one to specify his own type promotion rules via a PromotionPolicy class. @@ -46,7 +46,7 @@ auto z = x + ythe type of z will be an t, u, v - An object of type modeling Numeric + An object of a type modeling Numeric @@ -174,7 +174,7 @@ char y; auto z = x + y; // could result in overflow safe<int> sx; auto sz = sx + y; // promotes expression type to a safe<long int> which requires no result checking -is guaranteed not to overflow. +// is guaranteed not to overflow. safe_unsigned_range<1, 4> a; safe_unsigned_range<2, 4> b; @@ -182,12 +182,12 @@ auto c = a + b; // c will be of type safe_unsigned_range<3, 8> and cannot Type sz will be a SafeNumeric type - which is guaranteed to hold he result of x + y. In this case that will + which is guaranteed to hold the result of x + y. In this case that will be a long int (or perhaps a long long) depending upon the compiler and machine architecture. In this case, there will be no need for any special checking on the result and there can be no overflow. - Type of c will be a signed character as that type can be + The type of c will be a signed character as that type can be guaranteed to hold the sum so no overflow checking is done. This policy is documented in Date: Sat, 4 Mar 2017 07:58:15 -0800 Subject: [PATCH 21/37] Update exception_policy_concept.xml --- doc/boostbook/exception_policy_concept.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/boostbook/exception_policy_concept.xml b/doc/boostbook/exception_policy_concept.xml index 8e8604a..0de9da6 100644 --- a/doc/boostbook/exception_policy_concept.xml +++ b/doc/boostbook/exception_policy_concept.xml @@ -28,8 +28,8 @@ EP - A type that full fills the requirements of an - ExceptionPollicy + A type that fulfills the requirements of an + ExceptionPolicy @@ -145,7 +145,7 @@ If an exceptional condition is detected at runtime throw the exception. Safe types use this exception policy as the default if no - other one is specified. + other policy is specified. From b9568a8ad82bd222b677b4a9e31afd1b9a000ddb Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 08:10:39 -0800 Subject: [PATCH 22/37] Update safe.xml --- doc/boostbook/safe.xml | 27 +++++++++++++-------------- 1 file changed, 13 insertions(+), 14 deletions(-) diff --git a/doc/boostbook/safe.xml b/doc/boostbook/safe.xml index 046921b..99c6479 100644 --- a/doc/boostbook/safe.xml +++ b/doc/boostbook/safe.xml @@ -11,7 +11,7 @@ A safe<T, PP , EP> can be used anywhere a type T can be used. Any expression which uses this type is guaranteed to return - an arithmetically correct value or trap in some way. + an arithmetically correct value or to trap in some way.
@@ -99,7 +99,7 @@ Integer<T> - The underlying type. Currently only integer types + The underlying type. Currently only integer types are supported @@ -144,7 +144,7 @@ Implements all expressions and only those expressions defined by the SafeNumeric type - requirements. This, the result type of such an expression will be another + requirements. Thus, the result type of such an expression will be another safe type. The actual type of the result of such an expression will depend upon the specific promotion policy template parameter.
@@ -170,7 +170,7 @@ There are two aspects of the operation of this type which can be customized with a policy. The first is the result type of an arithmetic operation. C++ defines the rules which define this result type in terms of - the constituent types of the operation. Here we refer to these rules a + the constituent types of the operation. Here we refer to these rules as "type promotion" rules. These rules will sometimes result in a type which cannot hold the actual arithmetic result of the operation. This is the main motivation for making this library in the first place. One way to @@ -180,7 +180,7 @@
As a Drop-in replacement for standard integer types. - The following program will throw an exception and emit a error + The following program will throw an exception and emit an error message at runtime if any of several events result in an incorrect arithmetic type. Behavior of this program could vary according to the machine architecture in question. @@ -217,7 +217,7 @@ int main(){ creates the possibility of subtle bugs. It conflicts with the purpose of the library in a fundamental way. The library specifies that these conversions are errors that are to be invoked at compile time. If one - wants to switch between save and built-in types via an alias, this type + wants to switch between safe and built-in types via an alias, this type of code will have to be fixed so that implicit conversions to built-in types do not occur. In our view, this will be a net improvement to the code in any case. @@ -226,10 +226,10 @@ int main(){
Guarantee correct behavior at compile time. - In some instance catching an error at run time is not sufficient. + In some instances, catching an error at run time is not sufficient. We want to be sure that the program can never fail. To achieve this, use - the trap_exception exception policy rather than the default throw - exception policy. + the trap_exception exception policy rather than the default + throw_exception policy. The following program will emit a compile error at any statement which might possibly result in incorrect behavior. @@ -255,17 +255,16 @@ void f(){ Adjust type promotion rules. Another way to avoid arithmetic errors like overflow is to promote - types to larger sizes before doing the arithmetic. This can be justified - by the observe + types to larger sizes before doing the arithmetic. Stepping back, we can see that many of the cases of invalid - arithmetic are wouldn't exist if results types were larger. So we can + arithmetic wouldn't exist if the result types were larger. So we can avoid these problems by replacing the C++ type promotion rules for expressions with our own rules. This can be done by specifying a - non-default type promotion policy automatic. The policy stores the + non-default type promotion policy automatic. The policy stores the result of an expression in the smallest size that can accommodate the largest value that an expression can yield. All the work is done at - compile time - checking for exceptions necessary (input is of course an + compile time - no checking for exceptions is necessary (input is of course an exception). The following example illustrates this. #include <boost/numeric/safe.hpp> From 7816108f17781f66cfb34d78640701bb4d99d34a Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 08:14:15 -0800 Subject: [PATCH 23/37] Update safe_range.xml --- doc/boostbook/safe_range.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/boostbook/safe_range.xml b/doc/boostbook/safe_range.xml index 5990f69..bb2120a 100644 --- a/doc/boostbook/safe_range.xml +++ b/doc/boostbook/safe_range.xml @@ -14,7 +14,7 @@ [MIN, MAX]. A safe_signed_range<MIN, MAX, PP, EP> or safe_unsigned_range<MIN, MAX, PP, EP> can be used anywhere an arithmetic type is permitted. Any expression which uses either - of these types is guaranteed to return an arithmetically correct value or + of these types is guaranteed to return an arithmetically correct value or to trap in some way.
@@ -100,7 +100,7 @@ MIN - must be non-integer literal + must be a non-negative literal The minimum non-negative integer value that this type may hold @@ -162,7 +162,7 @@ Implements all expressions and only those expressions defined by the SafeNumeric type - requirements. This, the result type of such an expression will be another + requirements. Thus, the result type of such an expression will be another safe type. The actual type of the result of such an expression will depend upon the specific promotion policy template parameter.
From 0e08284fa79ab64be20d6e8616f50e2db6f42663 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 08:55:27 -0800 Subject: [PATCH 24/37] Update safe_literal.xml --- doc/boostbook/safe_literal.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/boostbook/safe_literal.xml b/doc/boostbook/safe_literal.xml index 314a923..1bde0d5 100644 --- a/doc/boostbook/safe_literal.xml +++ b/doc/boostbook/safe_literal.xml @@ -11,7 +11,7 @@ Description A safe type which holds a literal value. This is required to be able - to initialize other safe type in such a way that exception code is not + to initialize other safe types in such a way that an exception code is not generated. It is also useful when creating constexpr versions of safe types. It contains one immutable value known at compile time and hence can be used in any constexpr expression. @@ -117,7 +117,7 @@ Inherited Valid Expressions SafeLiteral types are immutable. Hence they only inherit those valid - expressions which don't change the value. The excludes assignment, + expressions which don't change the value. This excludes assignment, increment, and decrement operators. Other than that, they can be used anywhere a SafeNumeric type can be used. From 33bbaeacd6357e580f215a00ce87614e27fc45e7 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 09:00:28 -0800 Subject: [PATCH 25/37] Update native.xml --- doc/boostbook/native.xml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/boostbook/native.xml b/doc/boostbook/native.xml index 711b5c0..780d058 100644 --- a/doc/boostbook/native.xml +++ b/doc/boostbook/native.xml @@ -8,11 +8,11 @@ Description This type contains the functions to return a safe type corresponding - to the C++ type resulting for a given arithmetic operation. + to the C++ type resulting from a given arithmetic operation. 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 + 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. @@ -70,12 +70,12 @@ int main(){ safe_int8 x = 127; safe_int8 y = 2; safe_int8 z; - // rather than producing and invalid result an exception is thrown + // rather than producing an invalid result an exception is thrown z = x + y; assert(false); // never arrive here } catch(std::exception & e){ - // which can catch here + // which we can catch here std::cout << e.what() << std::endl; } @@ -84,7 +84,7 @@ int main(){ 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. + z = x + y; // is guaranteed correct without any runtime overhead or exception. return 0; } From 6db5b107384c73696e04b64272b88fa844497e8e Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 09:01:29 -0800 Subject: [PATCH 26/37] Update automatic.xml --- doc/boostbook/automatic.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/boostbook/automatic.xml b/doc/boostbook/automatic.xml index f302342..4a48eb7 100644 --- a/doc/boostbook/automatic.xml +++ b/doc/boostbook/automatic.xml @@ -43,7 +43,7 @@ int main(){ // In such cases, there is no runtime overhead from using safe types. safe_t x = 127; safe_t y = 2; - auto z = x + y; // z is guarenteed correct without any runtime overhead or interrupt. + auto z = x + y; // z is guaranteed correct without any runtime overhead or exception. return 0; } From 63b8b63c74c3ec8dba8ce6ab1bc2d9c0e8d5cc08 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 09:05:57 -0800 Subject: [PATCH 27/37] Update cpp.xml --- doc/boostbook/cpp.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/boostbook/cpp.xml b/doc/boostbook/cpp.xml index 2b575f4..242cb0e 100644 --- a/doc/boostbook/cpp.xml +++ b/doc/boostbook/cpp.xml @@ -8,17 +8,17 @@ Description This policy is used to promote safe types in arithmetic expressions - according the standard rules in the C++ standard. But rather than using + according to the rules in the C++ standard. But rather than using the native C++ standard types supported by the compiler, it uses types whose length in number of bits is specified by the template parameters. - This policy is useful for running test program which use C++ + This policy is useful for running test programs which use C++ portable integer types but which are destined to run on an architecture which is different than the one on which the test program is being built and run. This can happen when developing code for embedded systems. Algorithms developed or borrowed from one architecture but destined for - another can be tested on the desk top. + another can be tested on the desktop.
@@ -108,7 +108,7 @@ uses a very small microprocessor and a very limited C compiler. The chip is so small, you can't print anything from the code, log, debug or anything else. One debugs this code by using the "burn" and "crash" method - - you burn the chip (download the code) run the code, observe the results, + - you burn the chip (download the code), run the code, observe the results, make changes and try again. This is a crude method which is usually the one used. But it can be quite time consuming. @@ -121,7 +121,7 @@ other problems), make our algorithm testing environment differ from our target environment. We can address this by defining INT as a safe integer with a range of 8 bits. By using a custom promotion policy, we can force - the evaluation of C++ expressions test environment to be the same as that + the evaluation of C++ expressions in the test environment to be the same as that in the target environment. Also in our target environment, we can trap any overflows or other errors. So we can write and test our code on our desktop system and download the code to the target knowing that it just @@ -161,7 +161,7 @@ using uint16 = safe_t<std::uint16_t>; using uint32 = safe_t<std::uint32_t>; //////////////////////////////////////////////////////////////// -// Mock defines, functions etc which are in he "real application +// Mock defines, functions etc which are in the "real application" ... From a6e788f167666a154a3115403c576f9c703c7e28 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 09:07:29 -0800 Subject: [PATCH 28/37] Update throw_exception.xml --- doc/boostbook/throw_exception.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/boostbook/throw_exception.xml b/doc/boostbook/throw_exception.xml index 9430e5e..c0458fe 100644 --- a/doc/boostbook/throw_exception.xml +++ b/doc/boostbook/throw_exception.xml @@ -7,7 +7,7 @@
Description - This exception policy throws a an exception derived from + This exception policy throws an exception derived from std::exception any time some operation would result in an incorrect result. This is the default exception handling policy.
@@ -31,7 +31,7 @@ Example of use This example is somewhat contrived as throw_exception is the default - for safe types. Hence it usually is not necessarily to request it + for safe types. Hence it usually is not necessary to request it explicitly. #include "../../include/safe_integer.hpp" From adfee7ba3ddb1148d49f871631ebd3a1e7ef7a0d Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 09:09:03 -0800 Subject: [PATCH 29/37] Update trap_exception.xml --- doc/boostbook/trap_exception.xml | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/doc/boostbook/trap_exception.xml b/doc/boostbook/trap_exception.xml index 6780dfb..d46d67b 100644 --- a/doc/boostbook/trap_exception.xml +++ b/doc/boostbook/trap_exception.xml @@ -7,7 +7,7 @@
Description - This exception policy will trap at compile time any operation + This exception policy will trap at compile time any operation that COULD result in a runtime exception. It can be used in an environment which can tolerate neither arithmetic errors nor runtime overhead. Usage of this policy will @@ -32,8 +32,6 @@
Example of use - The following - #include "../../include/safe_integer.hpp" #include "../../include/automatic.hpp" #include "../../include/exception_policies.hpp" From d0485aa61942f5f72fdb077622aeed45a12170cd Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 09:11:04 -0800 Subject: [PATCH 30/37] Update no_exception_support.xml --- doc/boostbook/no_exception_support.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/boostbook/no_exception_support.xml b/doc/boostbook/no_exception_support.xml index 2f62882..c338b62 100644 --- a/doc/boostbook/no_exception_support.xml +++ b/doc/boostbook/no_exception_support.xml @@ -21,7 +21,7 @@ Template Parameters Function objects to be invoked are specified for each error - condition are specified via template parameters. + condition via template parameters. From 8ba476fbed2f2fbe39a995e7e9938ffb4f8fec69 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 11:35:15 -0800 Subject: [PATCH 31/37] Update safe_numerics.xml --- doc/boostbook/safe_numerics.xml | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/doc/boostbook/safe_numerics.xml b/doc/boostbook/safe_numerics.xml index 573b154..32b7b9d 100644 --- a/doc/boostbook/safe_numerics.xml +++ b/doc/boostbook/safe_numerics.xml @@ -118,7 +118,7 @@ fundamental software components described here. It is not necessary to know about these components to use the library. This information has been included to help those who want to understand how the library works so - they can extend it, correct bugs in it, or understand it's limitations. + they can extend it, correct bugs in it, or understand its limitations. These components are also interesting in their own right. For all these reasons, they are documented here. In general terms, the library works in the following manner: @@ -126,9 +126,9 @@ All unary/binary expressions where one of the operands is a - "safe" type are Overloaded. These overloads are declared and defined + "safe" type are overloaded. These overloads are declared and defined in the header file "safe_integer.hpp". SFINAE - "Substitution Failure - Is Not An Error and std::enable_if are key features of + Is Not An Error" and std::enable_if are key features of C++ used to define these overloads in a correct manner. @@ -143,12 +143,12 @@ Given the ranges of the operands, determine the range of the result of the operation using interval arithmetic. This is - implemented in the "interval.hpp" header file using constexpr + implemented in the "interval.hpp" header file using the constexpr facility of C++14. - if the range of the result type includes the range of the + If the range of the result type includes the range of the result of the operation, no run time checking of the result is necessary. So the operation reduces to the original built-in C/C++ operation. @@ -165,7 +165,7 @@ - if a valid result has been obtained, it is passed to the + If a valid result has been obtained, it is passed to the caller. From b3a86bd247c34d1293f2f713a68eaa929a0cd72b Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 11:38:43 -0800 Subject: [PATCH 32/37] Update interval.xml --- doc/boostbook/interval.xml | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/boostbook/interval.xml b/doc/boostbook/interval.xml index fbeb050..e132782 100644 --- a/doc/boostbook/interval.xml +++ b/doc/boostbook/interval.xml @@ -16,7 +16,7 @@
Template Parameters - R must model the type requirements R must model the type requirements ofNumeric
@@ -59,7 +59,7 @@ l, u - lower and upper Numeric limits of an interval + Lower and upper Numeric limits of an interval @@ -103,7 +103,7 @@
Valid Expressions - Note that all expressions are constexpr . + Note that all expressions are constexpr. From 401f02e5ecf08bba63973d5f651755f5d48f8eb2 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 11:41:46 -0800 Subject: [PATCH 33/37] Update checked_result.xml --- doc/boostbook/checked_result.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/boostbook/checked_result.xml b/doc/boostbook/checked_result.xml index b366a01..925ce36 100644 --- a/doc/boostbook/checked_result.xml +++ b/doc/boostbook/checked_result.xml @@ -9,7 +9,7 @@
Description - checked_result is a wrapper class designed to hold result of some + checked_result is a wrapper class designed to hold the result of some operation. It can hold either the result of the operation or information on why the operation failed to produce a valid result. Note that this type is an internal feature of the library and shouldn't be exposed to library @@ -213,7 +213,7 @@ void - invoke exception in accordance exception_type + invoke exception in accordance with exception_type value From 297a3888f017d7bee3384908324d85b61d75f49f Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 11:52:13 -0800 Subject: [PATCH 34/37] Update checked.xml --- doc/boostbook/checked.xml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/doc/boostbook/checked.xml b/doc/boostbook/checked.xml index 3faa762..0771273 100644 --- a/doc/boostbook/checked.xml +++ b/doc/boostbook/checked.xml @@ -29,7 +29,7 @@ template<class R, class T, class U> constexpr checked_result<R> checked::multiply(const T & t, const U & u); -// safe division on unsafe types +// safe division on primitive types template<class R, class T, class U> constexpr checked_result<R> checked::divide(const T & t, const U & u); @@ -38,7 +38,7 @@ template<class R, class T, class U> constexpr checked_result<R> checked::divide_automatic(const T & t, const U & u); -// safe modulus on unsafe types +// safe modulus on primitive types template<class R, class T, class U> constexpr checked_result<R> checked::modulus(const T & t, const U & u); @@ -86,7 +86,7 @@ checked::bitwise_xor(const T & t, const U & u);
Complexity - Each function performs one and only one arithmetic operation + Each function performs one and only one arithmetic operation.
@@ -110,7 +110,7 @@ checked_result<result_base_type> r = checked::multiply<int>(24, 42); Notes Some compilers have command line switches (e.g. -ftrapv) which - enable special behavior such erroneous integer operations are detected at + enable special behavior such that erroneous integer operations are detected at run time. The library has been implemented in such a way that these facilities are not used. It's possible they might be helpful in particular environment. These could be be exploited by re-implementing some functions From 531cd8a8d67d84f4cdf4c9ade9881bb781af6fdc Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 11:55:22 -0800 Subject: [PATCH 35/37] Update safe_numerics.xml --- doc/boostbook/safe_numerics.xml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/doc/boostbook/safe_numerics.xml b/doc/boostbook/safe_numerics.xml index 32b7b9d..bee4c0d 100644 --- a/doc/boostbook/safe_numerics.xml +++ b/doc/boostbook/safe_numerics.xml @@ -192,10 +192,10 @@
Performance Tests - Our goal creating facilities which make it possible write programs + Our goal is to create facilities which make it possible to write programs known to be correct. But we also want programmers to actually use the facilities we provide here. This won't happen if using these facilities - impacts performance to a significant degree. Although we've take + impacts performance to a significant degree. Although we've taken precautions to avoid doing this, the only real way to know is to create and run some tests. From e4db3d0218824c6766e6111c2070e83060889b82 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 12:04:48 -0800 Subject: [PATCH 36/37] Update faq.xml --- doc/boostbook/faq.xml | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/doc/boostbook/faq.xml b/doc/boostbook/faq.xml index 1a585f4..ed00267 100644 --- a/doc/boostbook/faq.xml +++ b/doc/boostbook/faq.xml @@ -55,7 +55,7 @@ - I used "safe" in large part this is what has been used by other + I used "safe" in large part because this is what has been used by other similar libraries. Maybe a better word might have been "correct" but that would raise similar concerns. I'm not inclined to change this. I've tried to make it clear in the documentation what the problem that @@ -71,7 +71,7 @@ Actually, I believe that this can/should be applied to any type - T which satisfies the type requirement "Numeric" type as defined in + T which satisfies the type requirement Numeric type as defined in the documentation. So there should be specializations safe<float> and related types as well as new types like safe<fixed_decimal> etc. But the current @@ -83,7 +83,7 @@ Isn't putting a defensive check just before any potential - undefined behavior is often considered a bad practice? + undefined behavior often considered a bad practice? @@ -104,7 +104,7 @@ As far as is known as of this writing, the library does not - presume that the underlying hardware is two's compliment. However, + presume that the underlying hardware is two's complement. However, this has yet to be verified in a rigorous way. @@ -118,7 +118,7 @@ safe<T> behaves like a "number" just as int does. It has max, min, etc Any code which uses numeric limits to test - a type T should works with safe<T>. + a type T should work with safe<T>. safe<T> is a drop-in replacement for T so it has to implement all the operations. @@ -141,7 +141,7 @@ arithmetic is not intended, such as array indexes. Finally, the modulus for such an integer would vary depending upon the machine architecture. For these reasons, in the context of this library, an - unsigned integer is considered to a representation of a subset of + unsigned integer is considered to be a representation of a subset of integers. Note that this decision is consistent with INT30-C, “Ensure that unsigned integer operations do not wrap” in the CERT C Secure Coding Standard @@ -163,7 +163,7 @@ meta-programming. But this wasn't enough. It became apparent that the only way to really minimize run-time penalty was to implement compile-time integer range arithmetic - a pretty elaborate sub - library. By doing range arithmetic at compiler-time, I could skip + library. By doing range arithmetic at compile-time, I could skip runtime checking on many/most integer operations. C++11 constexpr wasn't quite enough to do the job. C++14 constexpr can do the job. The library currently relies very heavily on C++14 constexpr. I think that @@ -180,7 +180,7 @@ - C++ has evolved way beyond the original C language. But C++ it's + C++ has evolved way beyond the original C language. But C++ is still (mostly) compatible with C. So most C programs can be compiled with a C++ compiler. The problems of incorrect arithmetic afflict both C and C++. Suppose we have a legacy C program designed for some @@ -207,7 +207,7 @@ using pic16_promotion = boost::numeric::cpp< 16, // long 32 // long long >; -// define safe types used desktop version of the program. +// define safe types used in the desktop version of the program. template <typename T> // T is char, int, etc data type using safe_t = boost::numeric::safe< T, @@ -231,7 +231,7 @@ typedef long int32_t; - Run the tests and change code to address any thrown + Run the tests and change the code to address any thrown exceptions. From 67daf20a43fa79ec907170dc0b80c6c82ea5ac15 Mon Sep 17 00:00:00 2001 From: insideoutclub Date: Sat, 4 Mar 2017 12:08:16 -0800 Subject: [PATCH 37/37] Update acknowledgements.xml --- doc/boostbook/acknowledgements.xml | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/doc/boostbook/acknowledgements.xml b/doc/boostbook/acknowledgements.xml index 1d6fa47..db0337b 100644 --- a/doc/boostbook/acknowledgements.xml +++ b/doc/boostbook/acknowledgements.xml @@ -9,13 +9,13 @@ - David LaBlanc + David LeBlanc This library is inspired by David LeBlanc's SafeInt Library . I found this library very well done in every way - and useful in my embedded systems work. This motivated me to take to + and useful in my embedded systems work. This motivated me to take it to the "next level". @@ -28,11 +28,11 @@ Andrzej Commented and reviewed the library as it was originally posted on the Boost Library Incubator. - The the consequent back and forth motivated me to invest more effort + The consequent back and forth motivated me to invest more effort in developing documentation and examples to justify the utility, indeed the necessity, for this library. He also noted many errors in - code, documentation, and tests. Without his interested and effort, I - do not believe the library would have progressed beyond it's initial + code, documentation, and tests. Without his interest and effort, I + do not believe the library would have progressed beyond its initial stages.