From 6f0710109c93bb18dfd3344857588bee5399d056 Mon Sep 17 00:00:00 2001 From: Robert Ramey Date: Sat, 3 Jun 2017 13:58:48 -0700 Subject: [PATCH] documentation updates for improved exception/error management --- doc/boostbook/acknowledgements.xml | 52 +- doc/boostbook/automatic.xml | 22 +- doc/boostbook/bibliography.xml | 668 +++++++++----------- doc/boostbook/checked.xml | 29 +- doc/boostbook/checked_result.xml | 28 +- doc/boostbook/cpp.xml | 39 +- doc/boostbook/eliminate_runtime_penalty.xml | 50 +- doc/boostbook/exception.xml | 232 +++++++ doc/boostbook/exception_policy.xml | 255 ++++++++ doc/boostbook/exception_policy_concept.xml | 157 +++-- doc/boostbook/exception_type.xml | 137 ---- doc/boostbook/faq.xml | 18 +- doc/boostbook/integer_concept.xml | 15 +- doc/boostbook/interval.xml | 15 +- doc/boostbook/native.xml | 28 +- doc/boostbook/numeric_concept.xml | 19 +- doc/boostbook/promotion_policy_concept.xml | 22 +- doc/boostbook/safe.xml | 44 +- doc/boostbook/safe_literal.xml | 16 +- doc/boostbook/safe_numeric_concept.xml | 15 +- doc/boostbook/safe_numerics.xml | 43 +- doc/boostbook/safe_range.xml | 24 +- doc/boostbook/throw_exception.xml | 48 -- examples/example81.cpp | 4 +- examples/example82.cpp | 2 +- include/checked.hpp | 12 +- include/exception.hpp | 9 +- include/exception_policies.hpp | 10 +- 28 files changed, 1162 insertions(+), 851 deletions(-) create mode 100644 doc/boostbook/exception.xml create mode 100644 doc/boostbook/exception_policy.xml delete mode 100644 doc/boostbook/exception_type.xml delete mode 100644 doc/boostbook/throw_exception.xml diff --git a/doc/boostbook/acknowledgements.xml b/doc/boostbook/acknowledgements.xml index db0337b..a738903 100644 --- a/doc/boostbook/acknowledgements.xml +++ b/doc/boostbook/acknowledgements.xml @@ -15,8 +15,8 @@ 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 it to - the "next level". + 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 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 interest and effort, I - do not believe the library would have progressed beyond its initial + 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 interest and effort, I do not + believe the library would have progressed beyond its initial stages. @@ -43,7 +43,43 @@ As always, the Boost Developer's mailing list has been the source of many useful observations from potential users and - constructive criticism from very knowledgeable developers. + constructive criticism from very knowledgeable developers. During + the Boost formal review, reviews and comments were posted by the + following persons: + + + + Paul A. Bristow + + + + Steven Watanabe + + + + John Maddock + + + + Antony Polukhin + + + + Barrett Adair + + + + Vicente J. Botet Escriba + + + + John McFarlane + + + + Peter Dimov + + diff --git a/doc/boostbook/automatic.xml b/doc/boostbook/automatic.xml index 8804f60..00e1f5d 100644 --- a/doc/boostbook/automatic.xml +++ b/doc/boostbook/automatic.xml @@ -87,13 +87,6 @@ linkend="safe_numerics.promotion_policy">PromotionPolicy -
- Header - - #include - <boost/safe_numerics/automatic.hpp> -
-
Example of use @@ -106,15 +99,24 @@ int main(){ using namespace boost::numeric; - // use automatic promotion policy where C++ standard arithmetic might lead to incorrect results + // use automatic promotion policy where C++ standard arithmetic + // might lead to incorrect results using safe_t = safe<std::int8_t, automatic>; // 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 guaranteed correct without any runtime overhead or exception. - + // z is guaranteed correct without any runtime overhead or exception. + auto z = x + y; return 0; }
+ +
+ Header + + #include + <boost/numeric/safe_numerics/automatic.hpp> + +
diff --git a/doc/boostbook/bibliography.xml b/doc/boostbook/bibliography.xml index 6f1b7b7..edda7c1 100644 --- a/doc/boostbook/bibliography.xml +++ b/doc/boostbook/bibliography.xml @@ -3,487 +3,423 @@ "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd">
Bibliography + + + + Zack - - - Zack + Coker + - Coker - + + Samir - - Samir + Hasan + - Hasan - + + Jeffrey - - Jeffrey + Overbey + - Overbey - + + Munawar - - Munawar + Hafiz + - Hafiz - + + Christian - - Christian + Kästner + - Kästner - + <ulink + url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"><ulink + url="https://www.cs.cmu.edu/~ckaestne/pdf/csse14-01.pdf">Integers In C: + An Open Invitation To Security Attacks?</ulink></ulink> - - <ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"> - <ulink - url="https://www.cs.cmu.edu/~ckaestne/pdf/csse14-01.pdf">Integers In - C: An Open Invitation To Security Attacks?</ulink> - </ulink> - + JTC1/SC22/WG21 - The C++ + Standards Committee - ISOCPP - - JTC1/SC22/WG21 - - The C++ Standards Committee - ISOCPP - + January 15, 2012 - January 15, 2012 + Coker + - Coker - + + + Lawrence - - - Lawrence + Crowl + - Crowl - + <ulink + url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"><ulink + url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html">C++ + Binary Fixed-Point Arithmetic</ulink></ulink> - - <ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"> - <ulink - url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html">C++ - Binary Fixed-Point Arithmetic</ulink> - </ulink> - + JTC1/SC22/WG21 - The C++ + Standards Committee - ISOCPP - - JTC1/SC22/WG21 - - The C++ Standards Committee - ISOCPP - + January 15, 2012 - January 15, 2012 + Crowl + - Crowl - + + + Lawrence Crowl + - - - Lawrence Crowl - + + Thorsten Ottosen + - - Thorsten Ottosen - + <ulink + url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"><ulink + url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1962.html">Proposal + to add Contract Programming to C++</ulink></ulink> - - <ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"> - <ulink - url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1962.html">Proposal - to add Contract Programming to C++</ulink> - </ulink> - + WG21/N1962 and J16/06-0032 + - The C++ Standards Committee - ISOCPP - - WG21/N1962 and - J16/06-0032 - The C++ Standards Committee - ISOCPP - + February 25, 2006 - February 25, 2006 + Crowl & Ottosen + - Crowl & Ottosen - + + + Will Dietz + - - - Will Dietz - + + Peng Li + - - Peng Li - + + John Regehr + - - John Regehr - + + Vikram Adve + - - Vikram Adve - - - - <ulink + <title><ulink url="http://www.cs.utah.edu/~regehr/papers/overflow12.pdf">Understanding - Integer Overflow in C/C++</ulink> - + Integer Overflow in C/C++ - - Proceedings of the 34th International Conference on Software Engineering (ICSE), - Zurich, Switzerland - + Zurich, Switzerland - June 2012 + June 2012 - Dietz - + Dietz + - - - J. Daniel Garcia - + + + J. Daniel Garcia + - - <ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"> - <ulink - url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4293.pdf">C++ - language support for contract programming</ulink> - </ulink> - + <ulink + url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"><ulink + url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2014/n4293.pdf">C++ + language support for contract programming</ulink></ulink> - - WG21/N4293 - The - C++ Standards Committee - ISOCPP - + WG21/N4293 - The C++ + Standards Committee - ISOCPP - December 23, 2014 + December 23, 2014 - Garcia - + Garcia + - - - Omer Katz - + + + Omer Katz + - - <ulink + <title><ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?">SafeInt - code proposal</ulink> - + code proposal - - Boost - Developer's List - + Developer's List - Katz + Katz - - Posts of various authors regarding a proposed SafeInt library for - boost - - + + Posts of various authors regarding a proposed SafeInt library + for boost + + - - + + + + David + + Keaton + + + + Thomas + + Plum + + + + Robert + + C. + + Seacord + + + + David + + Svoboda + + + + Alex + + Volkovitsky + + + + Timothy + + Wilson + + + + <ulink + url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"><ulink + url="http://resources.sei.cmu.edu/asset_files/TechnicalNote/2009_004_001_15074.pdf">As-if + Infinitely Ranged Integer Model</ulink></ulink> + + Software Engineering + Institute + + CMU/SEI-2009-TN-023 + + + Presents a model for addressing integer overflow errors. + + + + - David - - Keaton + David LeBlanc - - Thomas - - Plum - - - - Robert - - C. - - Seacord - - - - David - - Svoboda - - - - Alex - - Volkovitsky - - - - Timothy - - Wilson - - - - - <ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"> - <ulink - url="http://resources.sei.cmu.edu/asset_files/TechnicalNote/2009_004_001_15074.pdf">As-if - Infinitely Ranged Integer Model</ulink> - </ulink> - - - - Software Engineering - Institute - - - CMU/SEI-2009-TN-023 - - - Presents a model for addressing integer overflow errors. - - - - - - David LeBlanc - - - - <ulink + <title><ulink url="https://msdn.microsoft.com/en-us/library/ms972705.aspx">Integer - Handling with the C++ SafeInt Class</ulink> - + Handling with the C++ SafeInt Class - - Microsoft Developer Network - + Microsoft Developer + Network - January 7, 2004 + January 7, 2004 - LeBlanc - + LeBlanc + - - - David LeBlanc - + + + David LeBlanc + - - <ulink url="https://safeint.codeplex.com">SafeInt</ulink> - + <ulink url="https://safeint.codeplex.com">SafeInt</ulink> - - CodePlex - + CodePlex - Dec 3, 2014 + Dec 3, 2014 - LeBlanc - + LeBlanc + - - - Jacques-Louis Lions - + + + Jacques-Louis Lions + - - <ulink + <title><ulink url="https://en.wikisource.org/wiki/Ariane_501_Inquiry_Board_report">Ariane - 501 Inquiry Board report</ulink> - + 501 Inquiry Board report - - Wikisource - + Wikisource - July 19, 1996 + July 19, 1996 - Lions - + Lions + - - - Hubert Matthews - + + + Hubert Matthews + - - <ulink url="https://accu.org/index.php/journals/324">CheckedInt: A - Policy-Based Range-Checked Integer</ulink> - + <ulink url="https://accu.org/index.php/journals/324">CheckedInt: + A Policy-Based Range-Checked Integer</ulink> - - Overload Journal #58 - + Overload Journal + #58 - December 2003 + December 2003 - Matthews - + Matthews + - - - Jad Mouawad - + + + Jad Mouawad + - - <ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"> - <ulink - url="http://www.nytimes.com/2015/05/01/business/faa-orders-fix-for-possible-power-loss-in-boeing-787.html?_r=0">F.A.A - Orders Fix for Possible Power Loss in Boeing 787</ulink> - </ulink> - + <ulink + url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"><ulink + url="http://www.nytimes.com/2015/05/01/business/faa-orders-fix-for-possible-power-loss-in-boeing-787.html?_r=0">F.A.A + Orders Fix for Possible Power Loss in Boeing 787</ulink></ulink> - New York Times + New York Times - April 30, 2015 + April 30, 2015 - - Federal regulators will order operators of Boeing 787 Dreamliners - to shut down the plane’s electrical power periodically after Boeing - discovered a software error that could result in a total loss of - power. - - + + Federal regulators will order operators of Boeing 787 + Dreamliners to shut down the plane’s electrical power periodically + after Boeing discovered a software error that could result in a total + loss of power. + + - - - Daniel Plakosh - + + + Daniel Plakosh + - - <ulink + <title><ulink url="https://buildsecurityin.us-cert.gov/bsi/articles/knowledge/coding/312-BSI.html">Safe - Integer Operations</ulink> - + Integer Operations - - U.S. Department of - Homeland Security - + U.S. + Department of Homeland Security - May 10, 2013 + May 10, 2013 - Plakosh - + Plakosh + - - - Robert C. Seacord - + + + Robert C. Seacord + - - <ulink + <title><ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?">Secure - Coding in C and C++</ulink> - + Coding in C and C++ - 2nd Edition + 2nd Edition - Addison-Wesley Professional + Addison-Wesley Professional - April 12, 2013 + April 12, 2013 - 978-0321822130 + 978-0321822130 - Seacord - + Seacord + - - - Robert C. Seacord - + + + Robert C. Seacord + - - <ulink + <title><ulink url="https://www.securecoding.cert.org/confluence/display/seccode/INT32-C.+Ensure+that+operations+on+signed+integers+do+not+result+in+overflow?showComments=false">INT30-C. - Ensure that operations on unsigned integers do not wrap</ulink> - + Ensure that operations on unsigned integers do not wrap - - Software Engineering Institute, - Carnegie Mellon University - + Software Engineering + Institute, Carnegie Mellon University - August 17, 2014 + August 17, 2014 - INT30-C - + INT30-C + - - - Robert C. Seacord - + + + Robert C. Seacord + - - <ulink + <title><ulink url="https://www.securecoding.cert.org/confluence/display/c/INT30-C.+Ensure+that+unsigned+integer+operations+do+not+wrap">INT32-C. Ensure that operations on signed integers do not result in - overflow</ulink> - + overflow - - Software Engineering Institute, - Carnegie Mellon University - + Software Engineering + Institute, Carnegie Mellon University - August 17, 2014 + August 17, 2014 - INT32-C - + INT32-C + - - - Bjarn + + + Bjarn - Stroustrup - + Stroustrup + - The C++ Programming Language Fourth Edition + The C++ Programming Language Fourth Edition - - Addison-Wesley - + Addison-Wesley - - 2014 by Pearson Education, Inc. - + + 2014 by Pearson Education, Inc. + - January 15, 2012 + January 15, 2012 - Stroustrup - + Stroustrup + - - - Forum Posts - + + + Forum Posts + - - <ulink url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"> - <ulink - url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html">C++ - Binary Fixed-Point Arithmetic</ulink> - </ulink> - + <ulink + url="http://www.cert.org/secure-coding/publications/books/secure-coding-c-c-second-edition.cfm?"><ulink + url="http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2012/n3352.html">C++ + Binary Fixed-Point Arithmetic</ulink></ulink> - - ISO - C++ Standard Future Proposals - + C++ Standard Future Proposals - Forum + Forum - - Posts of various authors regarding proposal to add safe integer to - C++ standard libraries - - + + Posts of various authors regarding proposal to add safe integer + to C++ standard libraries + + +
diff --git a/doc/boostbook/checked.xml b/doc/boostbook/checked.xml index 0771273..d209538 100644 --- a/doc/boostbook/checked.xml +++ b/doc/boostbook/checked.xml @@ -89,20 +89,12 @@ checked::bitwise_xor(const T & t, const U & u); Each function performs one and only one arithmetic operation. -
- Header - - #include "checked.hpp" -
-
Example of use - [A code fragment that illustrates how to use the function.] + #include <boost/numeric/safe_numerics/checked.hpp> - #include "checked.hpp" - -checked_result<result_base_type> r = checked::multiply<int>(24, 42); +checked_result<int> r = checked::multiply<int>(24, 42);
@@ -110,11 +102,11 @@ 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 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 - in this library. + 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 in this library.
@@ -124,4 +116,11 @@ checked_result<result_base_type> r = checked::multiply<int>(24, 42); linkend="safenumerics.checked_result">checked_result<typename R>
+ +
+ Header + + #include + <boost/numeric/safe_numerics/checked.hpp> +
diff --git a/doc/boostbook/checked_result.xml b/doc/boostbook/checked_result.xml index efc6d27..34ee534 100644 --- a/doc/boostbook/checked_result.xml +++ b/doc/boostbook/checked_result.xml @@ -9,11 +9,11 @@
Description - 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 - users because it has some unsafe behavior. + 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 users because it has some unsafe behavior.
@@ -106,7 +106,7 @@ e An instance of type exception_type + linkend="safe_numerics.safe_numerics_error">safe_numerics_error @@ -228,16 +228,10 @@
-
- Header - - #include "checked_result.hpp" -
-
Example of use - #include "checked_result.hpp" + #include <boost/numeric/safe_numerics/checked_result.hpp> template<class R> checked_result<R> @@ -261,4 +255,12 @@ constexpr modulus( ExceptionPolicy
+ +
+ Header + + #include + <boost/numeric/safe_numerics/checked_result.hpp> + +
diff --git a/doc/boostbook/cpp.xml b/doc/boostbook/cpp.xml index 242cb0e..68efcd4 100644 --- a/doc/boostbook/cpp.xml +++ b/doc/boostbook/cpp.xml @@ -8,10 +8,9 @@ Description This policy is used to promote safe types in arithmetic expressions - 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. + 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 programs which use C++ portable integer types but which are destined to run on an architecture @@ -94,13 +93,6 @@ linkend="safe_numerics.promotion_policy">PromotionPolicy -
- Header - - #include - <boost/safe_numerics/cpp.hpp> -
-
Example of Use @@ -108,9 +100,9 @@ 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, - make changes and try again. This is a crude method which is usually the - one used. But it can be quite time consuming. + - 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. Consider an alternative. Build and compile your code in testable modules. For each module write a test which exercises all the code and @@ -121,11 +113,11 @@ 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 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 - has to work. This is a huge time saver and confidence builder. The + 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 has to work. This is a huge time saver and confidence builder. The following code is taken from a real project which has used this method. @@ -150,7 +142,7 @@ template <typename T> // T is char, int, etc data type using safe_t = boost::numeric::safe< T, pic16_promotion, - boost::numeric::trap_exception // use for compiling and running tests + boost::numeric::loose_trap_policy // use for compiling and running tests >; using int8 = safe_t<std::int8_t>; @@ -186,4 +178,11 @@ uint16 get_stopping_distance(LEMPARAMETER velocity){ being refined. Hopefully this will be available by the time you read this.
+ +
+ Header + + #include + <boost/numeric/safe_numerics/cpp.hpp> +
diff --git a/doc/boostbook/eliminate_runtime_penalty.xml b/doc/boostbook/eliminate_runtime_penalty.xml index b3123c4..d764cf9 100644 --- a/doc/boostbook/eliminate_runtime_penalty.xml +++ b/doc/boostbook/eliminate_runtime_penalty.xml @@ -15,7 +15,7 @@ The first step is to determine what parts of a program might invoke exceptions. The following program is similar to previous examples but uses a special exception policy: trap_exception. + linkend="safe_numerics.exception_policies.loose_trap_policy">loose_trap_policy. Now, @@ -59,28 +59,27 @@ 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 and compile time switch - settings, such cases may result in some sort of run time - exception. + settings, such cases may result in some sort of run time exception. The complete signature for a safe integer type is: template < class T, // underlying integer type class P = native, // type promotion policy class - class E = throw_exception // error handling policy class + class E = default_exception_policy // error handling policy class > safe; The promotion rules implemented in the default native - type promotion policy are consistent with those of standard C++ + linkend="safe_numerics.promotion_policies.native">native + type promotion policy are consistent with those of standard C++ Up until now, we've focused on detecting when this happens and invoking an exception or other kind of error handler. But now we look at another option. Using the automatic + linkend="safe_numerics.promotion_policies.automatic">automatic type promotion policy, we can change the rules of C++ arithmetic for safe types to something like the following: @@ -110,16 +109,16 @@ long z = (long)x + (long)y; // can never overflow One could do this by editing his code manually, but such a task would be tedious, error prone, and leave the resulting code hard to read and verify. Using the automatic + linkend="safe_numerics.promotion_policies.automatic">automatic type promotion policy will achieve the equivalent result without these problems. 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 the - trap_exception + is no need to check for errors - they can't happen!!! The usage of + the loose_trap_policy exception policy enforces this guarantee. @@ -150,7 +149,7 @@ long z = (long)x + (long)y; // can never overflow generated. Depending on the application, it should be rare to generate error checking code, and even more rare to actually invoke it. Any such instances are detected at compile time by the trap_exception + linkend="safe_numerics.exception_policies.loose_trap_policy">loose_trap_policy exception policy. This small example illustrates how to use automatic type promotion @@ -172,20 +171,20 @@ z = <long>[-4294967296,4294967294] = 2147483649 that: the automatic + linkend="safe_numerics.promotion_policies.automatic">automatic type promotion policy has rendered the result of the sum of two integers as a long type. our program compiles without error - even when using the trap_exception + linkend="safe_numerics.exception_policies.loose_trap_policy">loose_trap_policy exception policy - We do not need to use the try/catch idiom to handle - arithmetic errors - we will have none. + We do not need to use the try/catch idiom to + handle arithmetic errors - we will have none. @@ -206,7 +205,7 @@ z = <long>[-4294967296,4294967294] = 2147483649 a correct result. But since we trust no one, and since the program could change and the expressions be replaced with other ones, we'll still use the trap_exception + linkend="safe_numerics.exception_policies.loose_trap_policy">loose_trap_policy exception policy to verify at compile time that what we "know" to be true is in fact true. @@ -229,9 +228,10 @@ z = <long>[-4294967296,4294967294] = 2147483649 - The usage of trap_exception will mean that any - assignment to z which could be outside the legal range will result - in a compile time error. + The usage of loose_trap_policy + will mean that any assignment to z which could be outside the legal + range will result in a compile time error. @@ -263,9 +263,9 @@ 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 the automatic + linkend="safe_numerics.promotion_policies.automatic">automatic type promotion policy as well as the trap_exception + linkend="safe_numerics.exception_policies.loose_trap_policy">loose_trap_policy exception policy to enforce elimination of runtime penalties. @@ -295,8 +295,10 @@ z = <signed char>[-24,82] = 77 determined at compile time that construction of an instance of a safe_t from an input_safe_t can never fail. Hence, no try/catch block is necessary. The usage - of the trap_exception policy for safe_t - types guarantees this to be true at compile time. + of the loose_trap_policy + policy for safe_t types guarantees this to be true at + compile time. Here is the output from the program when values 12 and 32 are input from the console: diff --git a/doc/boostbook/exception.xml b/doc/boostbook/exception.xml new file mode 100644 index 0000000..85c6c7d --- /dev/null +++ b/doc/boostbook/exception.xml @@ -0,0 +1,232 @@ + + +
+ exception + +
+ Description + + Here we describe the data types used to refer to exceptional + conditions which might occur. Note that when we use the word "exception", + we don't mean the C++ term which refers to a data type, but rather the + colloquial sense of a anomaly, irregularity, deviation, special case, + isolated example, peculiarity, abnormality, oddity; misfit, aberration or + out of the ordinary occurrence. This concept of "exception" is more + complex that one would thing and hence is not manifested by a single + simple type. A small number of types work together to implement this + concept within the library. + + We've leveraged on the std::error_code + which is part of the standard library. We don't use all the facilities + that it offers but it's not an exact match, but it's useful for our + purposes. +
+ +
+ enum class safe_numerics_error + + The following values are those which a numeric result might return. + They resemble the standard error codes used by C++ standard exceptions. + This resemblance is coincidental and they are wholly unrelated to any + codes of similar names. The reason for the resemblance is that the library + started it's development using the standard library codes. But as + development progressed it became clear that the original codes weren't + sufficient so now they stand on their own. Here are a list of error codes. + The description of what they mean is + + + + + + + + + + Symbol + + Description + + + + + + success + + successful operation - no error returned + + + + positive_overflow_error + + A positive number is too large to be represented by the + data type + + + + negative_overflow_error + + The absolute value of a negative number is too large to + be represented by the data type. + + + + underflow_error + + A number is too close to zero to be represented by the + data type. + + + + range_error + + an argument to a function or operator is outside the + legal range - e.g. sqrt(-1). + + + + domain_error + + the result of an operation is outside the legal range of + the result. + + + + implementation_defined_behavior + + operation may or may not return the expected + result. + + + + undefined_behavior + + According to the C++ standard, the result is undefined. + e.g. 10 << 80 shifts bits off the left and returns an + unexpected result of 0 on most machines. + + + + uninitialized_value + + According to the C++ standard, the result may be defined + by the application. e.g. 16 >> 10 will result the expected + result of 0 on most machines. + + + + + + The above listed codes can be transformed to a instance of type + std::error_code + with the function: + + std::error_code make_error_code(safe_numerics_error e) + + This object can be +
+ +
+ enum class safe_numerics_actions + + The above error codes are classified into groups according to how + such exceptions should be handled. The following table shows the possible + actions that an error could be mapped to. + + + + + + + + + + Symbol + + Description + + + + + + no_action + + successful operation - no action action required + + + + uninitialized_value + + report attempt to use an uninitialized value - not + currently used + + + + arithmetic_error + + report an arithmetic error + + + + implementation_defined_behavior + + report an operation which the C++ standard permits but + fails to specify + + + + undefined_behavior + + report an operation whose result is undefined by the C++ + standard. + + + + + + Translation of a safe_numerics_error into the + corresponding safe_numerics_action can be accomplished with + the following function: + + constexpr enum safe_numerics_actions +make_safe_numerics_action(const safe_numerics_error & e); +
+ +
+ See Also + + + + Boost System Library This is the + official documentation for the Boost System Library which includes the + description of boost::system::error_code used by this library + + + + C++ Standard + Library version The Boost System Library has been incorporated + into the standard library as part of the C++ standard error handling + utilities. Except for the substitution of std:: for the + boost::system:: namespace, the libraries are identical. + This link points to the standard library documentation which may be + used in addition to the boost version. + + + + Thinking + Asynchronously in C++ Another essential reference on the + design and usage of the error_code + + +
+ +
+ Header + + #include + <boost/numeric/safe_numerics/exception.hpp> +
+
diff --git a/doc/boostbook/exception_policy.xml b/doc/boostbook/exception_policy.xml new file mode 100644 index 0000000..e4fa1c4 --- /dev/null +++ b/doc/boostbook/exception_policy.xml @@ -0,0 +1,255 @@ + + +
+ exception_policy<AE, IDB, UB, UV> + +
+ Description + + Create a valid exception policy from 4 function objects. This + specifies the actions to be taken for different types of invalid + results. +
+ +
+ Template Parameters + + + + + + + + + + + + Parameter + + Type Requirements + + Description + + + + + + AE + + Must be a function object callable with the expression + AE(e, message) + + invoked when operation produces an invalid arithmetic + result. + + + + IDB + + Must be a function object callable with the expression + IDB(e, message) + + invoked when operation produces an invalid arithmetic + result. + + + + UB + + Must be a function object callable with the expression + UB(e, message) + + invoked when operation produces an invalid arithmetic + result. + + + + UV + + Must be a function object callable with the expression + UV(e, message) + + invoked when operation produces an invalid arithmetic + result. + + + + +
+ +
+ Model of + + ExceptionPolicy +
+ +
+ Inherited Valid Expressions + + This class implements all the valid operations from the type + requirements ExceptionPolicy. Aside + from these, there are no other operations implemented. +
+ +
+ Function Objects + + In order to create an exception policy, one needs some function + objects. The library includes some appropriate examples of these: + + + + + + + + + + Name + + Description + + + + + + ignore_exception + + Ignore any runtime exception and just return - thus + propagating the error. This is what would happen with unsafe data + types + + + + throw_exception + + throw an exception of type std::system_error + + + + trap_exception + + Invoke a function which is undefined. Compilers will + include this function if and only if there is a possibility of a + runtime error. Conversely, This will create a compile time error + if there is any possibility that the operation will fail at + runtime. Use the action to guarantee that your application will + never produce an invalid result. Any operation invoke + + + + + + But of course one is free to provide his own. + + // log an exception condition but continue processing as though nothing has happened +// this would emulate the behavior of an unsafe type. +struct log_runtime_exception { + log_runtime_exception(const safe_numerics_error & e, const char * message){ + std::cout << "Caught system_error with code " << e.code() + << " meaning " << e.what() << '\n'; + } +}; + +
+ +
+ Policies Provided by the library + + The above function object can be composed into an exception policy + by this class. The library provides common policies all ready to use. In + the table below, the word "loose" is used to indicate that implementation + defined and undefined behavior is not considered an exceptional condition, + while "strict" means the opposite. The word "exception" means that a + runtime exception will be thrown. The word "trap" means that the mere + possibility of an error condition will result in a compile time + error. + + + + + + + + + + Name + + Description + + + + + + loose_exception_policy + + Throws runtime exception on any arithmetic error. + Undefined and implementation defined behavior is permitted as + long as it does not produce an arithmetic error. + + + + loose_trap_policy + + Invoke a compile time error in any case where it's + possible to result in an arithmetic error. + + + + strict_exception_policy + + Throws runtime exception on any arithmetic error. Any + undefined or implementation defined behavior also results in + throwing an exception. + + + + strict_trap_policy + + Invoke a compile time error in any case where it's + possible to result in an arithmetic error, undefined behavior or + implementation defined behavior + + + + default_exception_policy + + an alias for strict_exception_policy + + + + If none of the above suit your needs, you're free to + create your own. Here is one where use the logging function object defined + above as a component in a loose exception policy which logs any arithmetic + errors and ignores any other types of errors. + + // logging policy +// log arithmetic errors but ignore them and continue to execute +// implementation defined and undefined behavior is just executed +// without logging. + +using logging_exception_policy = exception_policy< + log_runtime_exception, // arithmetic error + ignore_exception, // implementation defined behavior + ignore_exception, // undefined behavior + ignore_exception // uninitialized value +>; + +
+ +
+ Header + + #include + <boost/numeric/safe_numerics/concept/exception_policy.hpp> +
+
diff --git a/doc/boostbook/exception_policy_concept.xml b/doc/boostbook/exception_policy_concept.xml index 0de9da6..26fc2d0 100644 --- a/doc/boostbook/exception_policy_concept.xml +++ b/doc/boostbook/exception_policy_concept.xml @@ -10,9 +10,9 @@ Description The exception policy specifies what is to occur when a safe - operation cannot return a valid arithmetic result. A type is an - ExceptionPolicy if it has functions for handling exceptional events that - occur in the course of safe numeric operations. + operation cannot return a valid result. A type is an ExceptionPolicy if it + has functions for handling exceptional events that occur in the course of + safe numeric operations.
@@ -32,6 +32,12 @@ ExceptionPolicy + + e + + A code from safe_numerics_error + + message @@ -46,14 +52,16 @@
Valid Expressions - Any operations which result in integers which cannot be represented - as some Numeric type will throw an exception. + Whenever an operation yield an invalid result, one of the following + functions will be invoked. + + - + - + @@ -67,56 +75,41 @@ - EP::no_error(const char * message) + EP::on_arithmetic_error(e, message) void - Unused. + when operation produces arithmetically incorrect + result - EP::uninitialized_error(const char * + EP::on_implementation_defined_behavior(e, message) void - Argument uninitialized. + when result is defined by the particular C++ + implementation - EP::overflow_error(const char * + EP::on_undefined_behavior(e, message) void - + when result is undefined - EP::underflow_error(const char * + EP::on_uninitialized_value(e, message) void - - - - - EP::range_error(const char * - message) - - void - - Divide by zero. - - - - EP::domain_error(const char * - message) - - void - - Argument outside permitted range. + when an uninitialized variable is used - currently not + implemented @@ -124,56 +117,96 @@
- Header + dispatch<EP>(const safe_numerics_error & e, const char * + msg) - #include - <safe_numerics/include/concepts/exception_policy.hpp> - + This function is used to invoke the exception handling policy for a + particular exception code. + +
+ Synopsis + + template<class EP> +constexpr void +dispatch<EP>(const boost::numeric::safe_numerics_error & e, char const * const & msg); +
+ +
+ Example of use + + #include <boost/safe_numerics/exception_policies.hpp" + +dispatch<boost::numeric::loose_exception_policy>( + boost::numeric::safe_numerics_error::positive_overflow_error, + "operation resulted in overflow" +); +
Models The library header <safe_numerics/include/exception_policies.hpp> + url="../../include/exception_policies.hpp"><boost/numerics/safe_numerics/exception_policies.hpp> contains a number of pre-made exception policies: - - boost::numeric::throw_exception + + boost::numeric::loose_exception_policy - If an exceptional condition is detected at runtime throw the - exception. Safe types use this exception policy as the default if no - other policy is specified. + Throw on arithmetic errors, ignore other errors. Some + applications ignore these issues and still work and we don't want to + update them. - - boost::numeric::ignore_exception + + boost::numeric::loose_trap_policy - Emulate the normal C/C++ behavior of permitting overflows, - underflows etc. + Same as above in that it doesn't check for various undefined + behaviors but traps at compile time for hard arithmetic errors. This + policy would be suitable for older embedded systems which depend on + bit manipulation operations to work. - - template<void (*F)(const char *), void (*G)(const char - *), void (*H)(const char *)> + + boost::numeric::strict_exception_policy - boost::numeric::no_exception_support - - If you want to specify specific behavior for particular - exception types, use this policy. The most likely situation is where - you don't have exception support and you want to trap "exceptions" by - calling your own special functions. + Permit just about anything, throw at runtime on any kind of + error. Recommended for new code. Check everything at compile time if + possible and runtime if necessary. Trap or Throw as appropriate. + Should guarantee code to be portable across architectures. - - boost::numeric::trap_exception + + boost::numeric::strict_trap_policy - Use this policy to trap at compile time any operation which - would otherwise trap at runtime. Hence expressions such as i/j will - trap at compile time unless j can be guaranteed to not be zero. + Same as above but requires code to be written in such a way as + to make it impossible for errors to occur. This naturally will require + extra coding effort but might be justified for embedded and/or safety + critical systems. + + + + boost::numeric::default_exception_policy + + Alias for strict_exception_policy, One would use + this first. After experimentation, one might switch to one of the + above policies or perhaps use a custom policy.
+ +
+ Header + + #include + <boost/numeric/safe_numerics/concepts/exception_policy.hpp> + +
diff --git a/doc/boostbook/exception_type.xml b/doc/boostbook/exception_type.xml deleted file mode 100644 index 16b57ae..0000000 --- a/doc/boostbook/exception_type.xml +++ /dev/null @@ -1,137 +0,0 @@ - - -
- exception_type - - - -
- Description - - This enum holds the information regarding a failed - operation. -
- -
- Notation - - - - - - - - - - Symbol - - Description - - - - - - EP - - ExceptionPolicy - type - - - - e - - enum class exception_type value - - - - msg - - const char * - pointer to static string with - error message - - - - -
- -
- Valid Expressions - - - - - - - - - - Expression - - Semantics - - - - - - - exception_type::no_exception - - exception_type::everflow_error - - exception_type::underflow_error - - exception_type::range_error - - exception_type::domain_error - - exception_type::uninitialized - - - enum values which describe various type of error - conditions - - - - dispatch<EP>(e, msg); - - invoke the exception handling policy for a particular - exception_type - - - - -
- -
- dispatch<EP>(const exception_type & e, const char * - msg) - - This function is used to invoke the exception handling policy for a - particular exception_type. - -
- Synopsis - - template<class EP> -constexpr void -dispatch<EP>(const exception_type & e, const char * msg); -
- -
- Example of use - - #include "exception_policy.hpp" - -dispatch<boost::numeric::throw_exception>(overflow_error, "operation resulted in overflow"); -
-
- -
- See Also - - ExceptionPolicy -
-
diff --git a/doc/boostbook/faq.xml b/doc/boostbook/faq.xml index cc7f69b..6bab218 100644 --- a/doc/boostbook/faq.xml +++ b/doc/boostbook/faq.xml @@ -55,11 +55,11 @@ - 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 - the library addressed is. + 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 the library addressed is. @@ -71,8 +71,8 @@ Actually, I believe that this can/should be applied to any type - T which satisfies the type requirement Numeric type as defined in - the documentation. So there should be specializations + 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 version of the library only addresses integer types. Hopefully the @@ -198,7 +198,7 @@ #ifdef TEST // using C++ on test platform #include <cstdint> -#include <safe_integer.hpp> +#include <boost/numeric/safe_numerics/safe_integer.hpp> #include <cpp.hpp> using pic16_promotion = boost::numeric::cpp< 8, // char @@ -212,7 +212,7 @@ template <typename T> // T is char, int, etc data type using safe_t = boost::numeric::safe< T, pic16_promotion, - boost::numeric::throw_exception // use for compiling and running tests + boost::numeric::default_exception_policy // use for compiling and running tests >; typedef safe_t<std::int_least16_t> int16_t; typedef safe_t<std::int_least32_t> int32_t; diff --git a/doc/boostbook/integer_concept.xml b/doc/boostbook/integer_concept.xml index b5fc8b1..03540a7 100644 --- a/doc/boostbook/integer_concept.xml +++ b/doc/boostbook/integer_concept.xml @@ -199,17 +199,18 @@ -
- Header - - #include - <safe_numerics/include/concepts/integer.hpp> -
-
Models int, safe<int>, safe_unsigned_range<0, 11>, etc.
+ +
+ Header + + #include + <boost/numeric/safe_numerics/concepts/integer.hpp> + +
diff --git a/doc/boostbook/interval.xml b/doc/boostbook/interval.xml index e132782..64dddd7 100644 --- a/doc/boostbook/interval.xml +++ b/doc/boostbook/interval.xml @@ -306,19 +306,13 @@ -
- Header - - #include "interval.hpp" -
-
Example of use #include <iostream> #include <cstdint> #include <cassert> -#include <boost/numeric/interval.hpp> +#include <boost/numeric/safe_numerics/interval.hpp> int main(){ std::cout << "test1" << std::endl; @@ -332,4 +326,11 @@ int main(){ return 0; }
+ +
+ Header + + #include + <boost/numeric/safe_numerics/interval.hpp> +
diff --git a/doc/boostbook/native.xml b/doc/boostbook/native.xml index 7f0d7d3..c5fb0b9 100644 --- a/doc/boostbook/native.xml +++ b/doc/boostbook/native.xml @@ -1,7 +1,7 @@ -
+
native
@@ -42,14 +42,6 @@ void int f(safe_int x, safe_int y){ }
-
- Header - - #include - <boost/safe_numerics/include/native.hpp> - -
-
Example of use @@ -60,11 +52,12 @@ void int f(safe_int x, safe_int y){ using native is not necessary. #include <cassert> -#include <boost/safe_numerics/safe_integer.hpp> -#include <boost/safe_numerics/native.hpp> +#include <boost/numeric/safe_numerics/safe_integer.hpp> +#include <boost/numeric/safe_numerics/native.hpp> int main(){ using namespace boost::numeric; - // use native promotion policy where C++ standard arithmetic might lead to incorrect results + // use native promotion policy where C++ standard arithmetic + // might lead to incorrect results using safe_int8 = safe<std::int8_t, native>; try{ safe_int8 x = 127; @@ -79,7 +72,8 @@ int main(){ std::cout << e.what() << std::endl; } - // When result is an int, C++ promotion rules guarentee that there will be no incorrect result. + // When result is an int, C++ promotion rules guarentee + // that there will be no incorrect result. // In such cases, there is no runtime overhead from using safe types. safe_int8 x = 127; safe_int8 y = 2; @@ -95,4 +89,12 @@ int main(){ See Chapter 5, Expressions, C++ Standard
+ +
+ Header + + #include + <boost/numeric/safe_numerics/native.hpp> + +
diff --git a/doc/boostbook/numeric_concept.xml b/doc/boostbook/numeric_concept.xml index 1ddbc9c..18a4600 100644 --- a/doc/boostbook/numeric_concept.xml +++ b/doc/boostbook/numeric_concept.xml @@ -13,8 +13,8 @@ More specifically, a type T is Numeric if there exists a specialization of std::numeric_limits<T>. See the - documentation for the standard library class numeric_limits. The - standard library includes such specializations for all the built-in + 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 is_arithmetic. These latter fulfill the requirement of the @@ -375,17 +375,18 @@
-
- Header - - #include - <safe_numerics/include/concepts/numeric.hpp> -
-
Models int, float, safe_signed_integer<int>, safe_signed_range<int>, etc.
+ +
+ Header + + #include + <boost/numeric/safe_numerics/concepts/numeric.hpp> + +
diff --git a/doc/boostbook/promotion_policy_concept.xml b/doc/boostbook/promotion_policy_concept.xml index eb2d1d4..1c69616 100644 --- a/doc/boostbook/promotion_policy_concept.xml +++ b/doc/boostbook/promotion_policy_concept.xml @@ -57,9 +57,9 @@ auto z = x + ythe type of z will be an
Valid Expressions - Any operations which result in integers which cannot be represented + Any operations which result in integers which cannot be represented as some Numeric type will throw an exception.These expressions return a - type which can be used as the basis create a SafeNumeric type. + type which can be used as the basis create a SafeNumeric type. @@ -134,15 +134,6 @@ auto z = x + ythe type of z will be an
-
- Header - - #include - <safe_numerics/include/concepts/promotion_policy.hpp> - -
-
Models @@ -207,4 +198,13 @@ auto c = a + b; // c will be a safe type with a range [3,8] and cannot overflow
+ +
+ Header + + #include + <boost/numeric/safe_numerics/concepts/promotion_policy.hpp> + +
diff --git a/doc/boostbook/safe.xml b/doc/boostbook/safe.xml index 99c6479..e7467cf 100644 --- a/doc/boostbook/safe.xml +++ b/doc/boostbook/safe.xml @@ -110,7 +110,7 @@ linkend="safe_numerics.promotion_policy">PromotionPolicy<PP> Default value is boost::numeric::native + linkend="safe_numerics.promotion_policies.native">boost::numeric::native @@ -121,7 +121,7 @@ Policy<EP> Default value is boost::numeric::throw_exception + linkend="safe_numerics.exception_policies.default_exception_policy">boost::numeric::default_exception_policy @@ -149,13 +149,6 @@ upon the specific promotion policy template parameter. -
- Header - - #include - <boost/safe_numerics/safe_integer.hpp> -
-
Examples of use @@ -226,10 +219,12 @@ int main(){
Guarantee correct behavior at compile time. - 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. + 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 loose_trap_policy + rather than the default_exception_policy. The following program will emit a compile error at any statement which might possibly result in incorrect behavior. @@ -261,16 +256,20 @@ void f(){ 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 - 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 - no checking for exceptions is necessary (input is of course an - exception). The following example illustrates this. + 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 - no checking for exceptions is necessary (input + is of course an exception). The following example illustrates + this. #include <boost/numeric/safe.hpp> #include <iostream> void f(){ - using safe_int = safe<int, boost::numeric::automatic, boost::numeric::throw_exception>; + using safe_int = safe< + int, boost::numeric::automatic, + boost::numeric::default_exception_policy + >; safe_int i; std::cin >> i; // might throw exception auto j = i * i; // won't ever trap - result type can hold the maximum value of i * i @@ -282,4 +281,11 @@ void f(){ }
+ +
+ Header + + #include + <boost/numeric/safe_numerics/safe_integer.hpp> +
diff --git a/doc/boostbook/safe_literal.xml b/doc/boostbook/safe_literal.xml index 34468ee..4ed3924 100644 --- a/doc/boostbook/safe_literal.xml +++ b/doc/boostbook/safe_literal.xml @@ -120,19 +120,19 @@ anywhere a SafeNumeric type can be used. -
- Header - - #include - <safe/numeric/safe_literal.hpp> -
-
Example of use - #include <safe/numeric/safe_literal.hpp> + #include <boost/numeric/safe_numerics/safe_literal.hpp> constexpr boost::numeric::safe_signed_literal<42> x;
+ +
+ Header + + #include + <boost/numeric/safe_numerics/safe_literal.hpp> +
diff --git a/doc/boostbook/safe_numeric_concept.xml b/doc/boostbook/safe_numeric_concept.xml index c3290a7..b0a8f67 100644 --- a/doc/boostbook/safe_numeric_concept.xml +++ b/doc/boostbook/safe_numeric_concept.xml @@ -277,14 +277,6 @@ int main(){ implementation should return an arithmetically incorrect result. -
- Header - - #include - <safe_numerics/include/concepts/safe_numeric.hpp> -
-
Models @@ -296,4 +288,11 @@ int main(){ safe_literal<4>
+ +
+ Header + + #include + <boost/numeric/safe_numerics/concepts/safe_numeric.hpp> +
diff --git a/doc/boostbook/safe_numerics.xml b/doc/boostbook/safe_numerics.xml index eb16165..c23e495 100644 --- a/doc/boostbook/safe_numerics.xml +++ b/doc/boostbook/safe_numerics.xml @@ -25,7 +25,7 @@ Safe integer operations - Numerics + Numerics + + + +
Promotion Policies @@ -83,22 +89,6 @@
- -
- Exception Policies - - - - - - - - -
@@ -143,8 +133,8 @@ 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 the constexpr - facility of C++14. + implemented in the "interval.hpp" header file using the + constexpr facility of C++14. @@ -179,9 +169,6 @@ - - @@ -192,12 +179,12 @@
Performance Tests - 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 taken - precautions to avoid doing this, the only real way to know is to create - and run some tests. + 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 + taken precautions to avoid doing this, the only real way to know is to + create and run some tests. To Do
diff --git a/doc/boostbook/safe_range.xml b/doc/boostbook/safe_range.xml index bb2120a..afbac2a 100644 --- a/doc/boostbook/safe_range.xml +++ b/doc/boostbook/safe_range.xml @@ -14,8 +14,8 @@ [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 to - trap in some way. + of these types is guaranteed to return an arithmetically correct value or + to trap in some way.
@@ -130,7 +130,7 @@ linkend="safe_numerics.promotion_policy">PromotionPolicy<PP> Default value is boost::numeric::native + linkend="safe_numerics.promotion_policies.native">boost::numeric::native @@ -141,7 +141,7 @@ Policy<EP> Default value is boost::numeric::throw_exception + linkend="safe_numerics.exception_policies.default_exception_policy">boost::numeric::default_exception_policy @@ -167,17 +167,10 @@ upon the specific promotion policy template parameter.
-
- Header - - #include - <safe/numeric/safe_range.hpp> -
-
Example of use - #include <safe/numeric/safe_range.hpp> + #include <boost/numeric/safe_numerics/safe_range.hpp> void f(){ using namespace boost::numeric; @@ -198,4 +191,11 @@ void f(){ static_assert(std::is_same<decltype(k), safe<unsigned int>); }
+ +
+ Header + + #include + <boost/numeric/safe_numerics/safe_range.hpp> +
diff --git a/doc/boostbook/throw_exception.xml b/doc/boostbook/throw_exception.xml deleted file mode 100644 index c0458fe..0000000 --- a/doc/boostbook/throw_exception.xml +++ /dev/null @@ -1,48 +0,0 @@ - - -
- throw_exception - -
- Description - - 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. -
- -
- Model of - - ExceptionPolicy -
- -
- Header - - #include - <boost/safe_numerics/exception_policies.hpp> - -
- -
- Example of use - - This example is somewhat contrived as throw_exception is the default - for safe types. Hence it usually is not necessary to request it - explicitly. - - #include "../../include/safe_integer.hpp" -#include "../../include/exception_policies" // exception policies -#include "../../include/native" // native promotion policy - -int main(){ - using namespace boost::numeric; - safe<int, native, throw_exception> i; - int j = 0; - i /= j; // throws exception -} -
-
diff --git a/examples/example81.cpp b/examples/example81.cpp index 33f0f27..15496b1 100644 --- a/examples/example81.cpp +++ b/examples/example81.cpp @@ -1,12 +1,12 @@ #include #include "../include/safe_integer.hpp" -#include "../include/exception.hpp" // include exception policies +#include "../include/exception_policies.hpp" // include exception policies using safe_t = boost::numeric::safe< int, boost::numeric::native, - boost::numeric::trap_exception // note use of "trap_exception" policy! + boost::numeric::loose_trap_policy // note use of "loose_trap_exception" policy! >; int main(int argc, const char * argv[]){ diff --git a/examples/example82.cpp b/examples/example82.cpp index 29dacee..de5491e 100644 --- a/examples/example82.cpp +++ b/examples/example82.cpp @@ -1,7 +1,7 @@ #include #include "../include/safe_integer.hpp" -#include "../include/exception.hpp" +#include "../include/exception_policies.hpp" #include "../include/automatic.hpp" #include "safe_format.hpp" // prints out range and value of any type diff --git a/include/checked.hpp b/include/checked.hpp index 129c256..112b934 100644 --- a/include/checked.hpp +++ b/include/checked.hpp @@ -642,7 +642,7 @@ constexpr checked_left_shift( // behavior is undefined return checked_result( safe_numerics_error::undefined_behavior, - "shifting more bits than available is undefined behavior" + "shifting left more bits than available is undefined behavior" ); } return t << u; @@ -691,14 +691,14 @@ constexpr checked_result left_shift( if(u < 0){ return checked_result( safe_numerics_error::implementation_defined_behavior, - "shifting negative amount is undefined behavior" + "shifting negative amount is implementation defined behavior" ); } if(u > std::numeric_limits::digits){ // behavior is undefined return checked_result( safe_numerics_error::implementation_defined_behavior, - "shifting more bits than available is undefined behavior" + "shifting more bits than available is implementation defined behavior" ); } if(t == 0) @@ -744,7 +744,7 @@ constexpr checked_right_shift( // defined" rather than "undefined". return checked_result( safe_numerics_error::implementation_defined_behavior, - "shifting a negative value is undefined behavior" + "shifting a negative value is implementation defined behavior" ); } @@ -767,14 +767,14 @@ constexpr checked_result right_shift( if(u < 0){ return checked_result( safe_numerics_error::implementation_defined_behavior, - "shifting negative amount is undefined behavior" + "shifting negative amount is implementation defined behavior" ); } if(u > std::numeric_limits::digits){ // behavior is undefined return checked_result( safe_numerics_error::implementation_defined_behavior, - "shifting more bits than available is undefined behavior" + "shifting more bits than available is implementation defined behavior" ); } if(t == 0) diff --git a/include/exception.hpp b/include/exception.hpp index 4e98048..22442ab 100644 --- a/include/exception.hpp +++ b/include/exception.hpp @@ -86,6 +86,7 @@ public: } } safe_numerics_error_category ; +// constexpr - damn, can't use constexpr due to std::error_code std::error_code make_error_code(safe_numerics_error e){ return std::error_code(static_cast(e), safe_numerics_error_category); } @@ -94,7 +95,7 @@ std::error_code make_error_code(safe_numerics_error e){ // error_condition in order to do this. I'm not sure this is a good // idea or not. -enum safe_numerics_actions { +enum class safe_numerics_actions { no_action = 0, uninitialized_value, arithmetic_error, @@ -130,7 +131,7 @@ public: ) const noexcept { if(code.category() != safe_numerics_error_category) return false; - switch (condition){ + switch (static_cast(condition)){ case safe_numerics_actions::no_action: return code == safe_numerics_error::success; case safe_numerics_actions::uninitialized_value: @@ -160,7 +161,7 @@ make_error_condition(safe_numerics_actions e){ } // given an error code - return the action code which it corresponds to. -constexpr safe_numerics_actions +constexpr enum safe_numerics_actions make_safe_numerics_action(const safe_numerics_error & e){ // we can't use standard algorithms since we want this to be constexpr // this brute force solution is simple and pretty fast anyway @@ -182,7 +183,7 @@ make_safe_numerics_action(const safe_numerics_error & e){ } } -// given an error code - return the action code which it corresponds to. +// given an error code - return the error_condition which it corresponds to. std::error_condition make_error_condition(safe_numerics_error e){ return std::error_condition(make_safe_numerics_action(e)); diff --git a/include/exception_policies.hpp b/include/exception_policies.hpp index 05cdd2e..776f97a 100644 --- a/include/exception_policies.hpp +++ b/include/exception_policies.hpp @@ -102,8 +102,8 @@ using loose_trap_policy = exception_policy< // - throw at runtime on any kind of error // recommended for new code. Check everything at compile time // if possible and runtime if necessary. Trap or Throw as -// appropriate. Should guarentee code to be portable accross -// archtectures. +// appropriate. Should guarantee code to be portable across +// architectures. using strict_exception_policy = exception_policy< throw_exception, throw_exception, @@ -112,8 +112,10 @@ using strict_exception_policy = exception_policy< >; // strict trap -// same as above but requires code to be written in such a way as -// to make exceptions impossible +// Same as above but requires code to be written in such a way as to +// make it impossible for errors to occur. This naturally will require +// extra coding effort but might be justified for embedded and/or +// safety critical systems. using strict_trap_policy = exception_policy< trap_exception, trap_exception,