[section Tutorial]
-This section is a guide to basic usages of this library.
+This section is a guide to basic usage of this library.
[section Non-Member Functions]
The [funcref boost::contract::function] function returns an RAII object that must always be assigned to a local variable of type [classref boost::contract::check] (otherwise this library will generate a run-time error, see [macroref BOOST_CONTRACT_ON_MISSING_CHECK_DECL]).
[footnote
-The name of this local variable is arbitrary, but `c` is often used in this documentation for ["c]heck or ["c]aminiti [^;-)].
+The name of this local variable is arbitrary, but `c` is often used in this documentation for ["c]heck or ["c]aminiti [^;-)] .
]
Furthermore, C++11 `auto` declarations cannot be used here and the [classref boost::contract::check] type must be explicitly specified (otherwise this library will generate a compile-time error prior C++17 and a run-time error post C++17).
[footnote
*Rationale:*
-C++17 zero-copy guarantee on function return values skips the trick this library uses to force a compile-time error when `auto` is incorrectly used instead of [classref boost::contract::check].
-The library is still able to generate a run-time error in this case on C++17.
+C++17 guaranteed copy elision on function return value voids the trick this library uses to force a compile-time error when `auto` is incorrectly used instead of [classref boost::contract::check].
+The library still generates a run-time error in this case (also on C++17).
In any case, after reading this documentation it should be evident to programmers that `auto` should not be used in [classref boost::contract::check] declarations so this misuse of `auto` should not be an issue in practice.
]
-The function body is programmed right after the declaration of the RAII object.
+The function body is programmed right after the declaration of this RAII object.
[note
In some cases, it might be necessary to program some code before the contract.
[section Preconditions]
-When preconditions are specified, they are programmed using a functor [^['r]] passed to `.precondition(`[^['r]]`)` that can be called with no parameters as [^['r]]`()`.
+When preconditions are specified, they are programmed using a functor [^['r]] passed to `.precondition(`[^['r]]`)` that can be called with no parameters as in [^['r]]`()`.
Contracts that do not have preconditions simply do not call `.precondition(...)`.
Preconditions must appear before postconditions and exception guarantees when these are all present (see __Postconditions__ and __Exception_Guarantees__).
[footnote
In this documentation preconditions often capture variables by reference to avoid extra copies.
]
-In any case, precondition assertions should not modify the value of the captured variables, even when those are captured by reference (see __Constant_Correctness__).
+In any case, programmers should not write precondition assertions that modify the value of the captured variables, even when those are captured by reference (see __Constant_Correctness__).
Any code can be programmed in the precondition functor, but it is recommended to keep this code simple using mainly assertions and if-statements (to avoid programming complex preconditions that might be buggy and also slow to check at run-time).
-It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program precondition assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (this is not a variadic macro, see __No_Macros__):
+It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program precondition assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (note that this is not a variadic macro, see __No_Macros__):
- BOOST_CONTRACT_ASSERT(bool_cond)
- // Or, if `bool_cond` contains commas `,` not already within parenthesis `()`...
- BOOST_CONTRACT_ASSERT((bool_cond)) // ...use extra parenthesis (not a variadic macro).
+ BOOST_CONTRACT_ASSERT(``[^['boolean-condition]]``)
+ // Or, if `boolean-condition` contains commas `,` not already within parenthesis `()`...
+ BOOST_CONTRACT_ASSERT((``[^['boolean-condition]]``)) // ...use extra parenthesis (not a variadic macro).
-This library will automatically call the failure handler [funcref boost::contract::precondition_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false and, more in general, if calling the functor specified via `.precondition(...)` throws any exception.
+This library will automatically call the failure handler [funcref boost::contract::precondition_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false or, more in general, if calling the functor specified via `.precondition(...)` throws any exception.
By default, this failure handler prints an error message to `std::cerr` and terminates the program calling `std::terminate` (see __Throw_on_Failures__ to change the failure handler to throw exceptions, exit the program with an error code, etc.).
[note
[section Postconditions]
-When postconditions are specified, they are programmed using a functor [^['s]] passed to `.postcondition(`[^['s]]`)` that can be called with no parameters as [^['s]]`()`.
+When postconditions are specified, they are programmed using a functor [^['s]] passed to `.postcondition(`[^['s]]`)` that can be called with no parameters as in [^['s]]`()`.
Contracts that do not have postconditions simply do not call `.postcondition(...)`.
Postconditions must appear after preconditions but before exception guarantees when these are all present (see __Preconditions__ and __Exception_Guarantees__).
...
}
-The postcondition functor should capture all variables that it needs to assert the postconditions.
-In general, these variables should be captured by reference and not by value (because postconditions need to access the value that these variables will have at function exit, and not the value these variables had when the postcondition functor was first constructed).
+The postcondition functor should capture all the variables that it needs to assert the postconditions.
+In general, these variables should be captured by reference and not by value (because postconditions need to access the value that these variables will have at function exit, and not the value these variables had when the postcondition functor was first declared).
Postconditions can also capture return and old values (see __Return_Values__ and __Old_Values__).
-In any case, postcondition assertions should not modify the value of the captured variables (see __Constant_Correctness__).
+In any case, programmers should not write postcondition assertions that modify the value of the captured variables, even when those are captured by reference (see __Constant_Correctness__).
Any code can be programmed in the postcondition functor, but it is recommended to keep this code simple using mainly assertions and if-statements (to avoid programming complex postconditions that might be buggy and slow to check at run-time).
-It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program postcondition assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (this is not a variadic macro, see __No_Macros__):
+It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program postcondition assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (note that this is not a variadic macro, see __No_Macros__):
- BOOST_CONTRACT_ASSERT(bool_cond)
- // Or, if `bool_cond` has commas `,` not already within parenthesis `()`...
- BOOST_CONTRACT_ASSERT((bool_cond)) // ...use extra parenthesis (not a variadic macro).
+ BOOST_CONTRACT_ASSERT(``[^['boolean-condition]]``)
+ // Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...
+ BOOST_CONTRACT_ASSERT((``[^['boolean-condition]]``)) // ...use extra parenthesis (not a variadic macro).
-This library will automatically call the failure handler [funcref boost::contract::postcondition_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false and, more in general, if calling the functor specified via `.postcondition(...)` throws any exception.
+This library will automatically call the failure handler [funcref boost::contract::postcondition_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false or, more in general, if calling the functor specified via `.postcondition(...)` throws any exception.
By default, this failure handler prints an error message to `std::cerr` and terminates the program calling `std::terminate` (see __Throw_on_Failures__ to change the failure handler to throw exceptions, exit the program with an error code, etc.).
-For non-void virtual public functions and public function overrides, the functor [^['s]] passed to `.postcondition(`[^['s]]`)` is not a nullary functor, instead it is a unary functor taking a variable holding the return value as its one parameter [^['s]]`(`[^['result]]`)` (this is to properly support subcontracting, see __Virtual_Public_Functions__ and __Public_Function_Overrides__).
+For non-void virtual public functions and non-void public function overrides, the functor [^['s]] passed to `.postcondition(`[^['s]]`)` is not a nullary functor, instead it is a unary functor taking a variable holding the return value as its one parameter [^['s]]`(`[^['result]]`)` (this is to properly support subcontracting, see __Virtual_Public_Functions__ and __Public_Function_Overrides__).
[endsect]
boost::contract::check c = boost::contract::function() // Same for all other contracts.
...
.postcondition([&] { // Also capture `result` reference...
- BOOST_CONTRACT_ASSERT(result ...); // ...but should not modify captures.
+ BOOST_CONTRACT_ASSERT(result == ...); // ...but should not modify captures.
...
})
...
;
- ... // Assign `result` at each return.
+ ...
+ return result = ...; // Assign `result` at each return.
}
At any point where the enclosing function returns, programmers are responsible to assign the result variable to the expression being returned.
This can be done ensuring that /all/ `return` statements in the function are of the form:
- return result = return_expr; // Assign `result` at each return.
+ ``[^['return-type]]`` result;
+ ...
+ return result = ``[^['return-expression]]``; // Assign `result` at each return.
-The functor used to program postconditions should capture the result variable by reference and not by value (because postconditions must access the value the result variable will have at function exit, and not the value the result variable had when the postcondition functor was first constructed).
+The functor used to program postconditions should capture the result variable by reference and not by value (because postconditions must access the value the result variable will have at function exit, and not the value the result variable had when the postcondition functor was first declared).
The return value should never be used in preconditions, old value copies, or exception guarantees (because the return value is not yet correctly evaluated and set when preconditions are checked, old values are copied, or if the function throws an exception).
In any case, programmers should not modify the result variable in the contract assertions (see __Constant_Correctness__).
It is also possible to declared the result variable using `boost::optional` when the function return type does not have a default constructor, or if the default constructor is too expensive or undesirable to execute when first declaring the result variable (see __Optional_Return_Values__).
-Non-void virtual public functions and public function overrides must always declare and use a result variable even when postconditions do not directly use the function return value (this is to properly support subcontracting, see __Virtual_Public_Functions__ and __Public_Function_Overrides__).
+Non-void virtual public functions and non-void public function overrides must always declare and use a result variable even when postconditions do not directly use the function return value (this is to properly support subcontracting, see __Virtual_Public_Functions__ and __Public_Function_Overrides__).
[endsect]
boost::contract::check c = boost::contract::function() // Same for all other contracts.
... // Preconditions shall not use old values.
.postcondition([&] { // Capture by reference...
- BOOST_CONTRACT_ASSERT(*old_var ...); // ...but should not modify captures.
+ BOOST_CONTRACT_ASSERT(*old_var == ...); // ...but should not modify captures.
...
})
.except([&] { // Capture by reference...
[footnote
*Rationale:*
Old values have to be optional values because they need to be left uninitialized when they are not used because both postconditions and exception guarantees are disabled (defining [macroref BOOST_CONTRACT_NO_POSTCONDITIONS] and [macroref BOOST_CONTRACT_NO_EXCEPTS]).
-That is to avoid old value copies when old values are not used, so a pointer, or better a `boost::optional`, could have been used for that.
+That is to avoid old value copies when old values are not used, either a pointer or (better) a `boost::optional` could have been used to achieve that.
In addition, old values need to be pointers internally allocated by this library so that they are never copied twice even when calling an overridden function multiple times to check preconditions, postconditions, etc. to implement subcontracting, so a smart pointer class template was used.
]
The pointed old value type is automatically qualified as `const` (so old values cannot be mistakenly changed by contract assertions, see __Constant_Correctness__).
Old values should not be used in preconditions and this library does not guarantee that old value pointers are always not null when preconditions are checked.
[footnote
-For example, old value pointers might be null in preconditions when postconditions and exception guarantees are disabled defining [macroref BOOST_CONTRACT_NO_POSTCONDITIONS] and [macroref BOOST_CONTRACT_NO_EXCEPTS], but also when checking an overridden virtual public function contract via subcontracting, etc.
+For example, old value pointers might be null in preconditions when postconditions and exception guarantees are disabled defining [macroref BOOST_CONTRACT_NO_POSTCONDITIONS] and [macroref BOOST_CONTRACT_NO_EXCEPTS] (but also when checking an overridden virtual public function contract via subcontracting, etc.).
]
-See __Old_Value_Copies_at_Body__ for delaying the copy of old values until after class invariants (for constructors, destructors, and public functions) and preconditions are checked (this allows to program old value expressions under the simplifying assumption that class invariant and precondition assertions are satisfied already).
+See __Old_Values_Copied_at_Body__ for delaying the copy of old values until after class invariants (for constructors, destructors, and public functions) and preconditions are checked (when necessary, this allows to program old value expressions under the simplifying assumption that class invariant and precondition assertions are satisfied already).
[macroref BOOST_CONTRACT_OLDOF] is a variadic macro and it takes an extra parameter when used in virtual public functions or public function overrides (see __Virtual_Public_Functions__ and __Public_Function_Overrides__).
-C++11 auto declarations can be used with [macroref BOOST_CONTRACT_OLDOF] for brevity `auto `[^old_['variable-name] = BOOST_CONTRACT_OLDOF(['expression])].
+C++11 auto declarations can be used with [macroref BOOST_CONTRACT_OLDOF] for brevity `auto `[^old_['variable-name] = BOOST_CONTRACT_OLDOF(['expression])] (but see also __Old_Value_Requirements__).
See __No_Macros__ to program old values without using [macroref BOOST_CONTRACT_OLDOF] (e.g., on compilers that do not support variadic macros).
[note
[section Exception Guarantees]
-When exception guarantees are specified, they are programmed using a functor [^['e]] passed to `.except(`[^['e]]`)` that can be called with no parameters as [^['e]]`()`.
+When exception guarantees are specified, they are programmed using a functor [^['e]] passed to `.except(`[^['e]]`)` that can be called with no parameters as in [^['e]]`()`.
Contracts that do not have exception guarantees simply do not call `.except(...)`.
Exception guarantees must appear after both preconditions and postconditions when these are all present (see __Preconditions__ and __Postconditions__).
...
}
-The exception guarantee functor should capture all variables that it needs to assert the exception guarantees.
-In general, these variables should be captured by reference and not by value (because exception guarantees need to access the value that these variables will have when the function throws, and not the value these variables had when the exception guarantee functor was first constructed).
-Exception guarantees can also capture old values (see __Old_Values__) but they should not access the function return value instead (because the return value will not be properly set when the function throws an exception).
-In any case, exception guarantee assertions should not modify the value of the captured variables (see __Constant_Correctness__).
+The exception guarantee functor should capture all the variables that it needs to assert the exception guarantees.
+In general, these variables should be captured by reference and not by value (because exception guarantees need to access the value that these variables will have when the function throws, and not the value these variables had when the exception guarantee functor was first declared).
+Exception guarantees can also capture old values (see __Old_Values__) but they should not access the function return value instead (because the return value is not be properly set when the function throws an exception).
+In any case, programmers should not write exception guarantee assertions that modify the value of the captured variables, even when those are captured by reference (see __Constant_Correctness__).
[note
-In real code, it might be difficult to program meaningful exception guarantees without resorting to expensive old value copies that will slow down execution.
+In real production code, it might be difficult to program meaningful exception guarantees without resorting to expensive old value copies that will slow down execution.
Therefore, the authors recognize that exception guarantees, even if supported by this library, might not be used often in practice (and they are not used in most of the examples listed in the rest of this documentation).
-In any case, these performance considerations are ultimately left to programmers and their specific application domain.
+In any case, these performance considerations are ultimately left to programmers and their specific application domains.
]
Any code can be programmed in the exception guarantee functor, but it is recommended to keep this code simple using mainly assertions and if-statements (to avoid programming complex exception guarantees that might be buggy and slow to check at run-time).
-It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program exception guarantee assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (this is not a variadic macro, see __No_Macros__):
+It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program exception guarantee assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (note that this is not a variadic macro, see __No_Macros__):
- BOOST_CONTRACT_ASSERT(bool_cond)
- // Or, if `bool_cond` has commas `,` not already within parenthesis `()`...
- BOOST_CONTRACT_ASSERT((bool_cond)) // ...use extra parenthesis (not a variadic macro).
+ BOOST_CONTRACT_ASSERT(``[^['boolean-condition]]``)
+ // Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...
+ BOOST_CONTRACT_ASSERT((``[^['boolean-condition]]``)) // ...use extra parenthesis (not a variadic macro).
-This library will automatically call the failure handler [funcref boost::contract::except_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false and, more in general, if calling the functor specified via `.except(...)` throws any exception.
+This library will automatically call the failure handler [funcref boost::contract::except_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false or, more in general, if calling the functor specified via `.except(...)` throws any exception.
By default, this failure handler prints an error message to `std::cerr` and terminates the program calling `std::terminate` (see __Throw_on_Failures__ to change the failure handler to exit the program with an error code or to take some other custom action).
[note
[section Class Invariants]
-Public member functions, constructors, and destructors can be programmed to check class invariants.
+Public member functions, constructors, and destructors can be programmed to also check class invariants.
When class invariants are specified, they are programmed in a public `const` function named `invariant` taking no argument and returning `void`.
Classes that do not have invariants, simply do not declare the `invariant` function.
[footnote
-This library uses template meta-programming (SFINAE-based introspection techniques) to check invariants only for classes that declare a member function named [macroref BOOST_CONTRACT_INVARIANT_FUNC].
+This library uses template meta-programming (SFINAE-based introspection techniques) to check invariants only for classes that declare a member function named by [macroref BOOST_CONTRACT_INVARIANT_FUNC].
]
For example:
This library will generate a compile-time error if the `const` qualifier is missing (unless [macroref BOOST_CONTRACT_PERMISSIVE] is defined).
Any code can be programmed in the `invariant` function, but it is recommended to keep this code simple using mainly assertions and if-statements (to avoid programming complex invariants that might be buggy and slow to check at run-time).
-It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program class invariant assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (this is not a variadic macro, see __No_Macros__):
+It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program class invariant assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (note that this is not a variadic macro, see __No_Macros__):
- BOOST_CONTRACT_ASSERT(bool_cond)
- // Or, if `bool_cond` has commas `,` not already within parenthesis `()`...
- BOOST_CONTRACT_ASSERT((bool_cond)) // ...use extra parenthesis (not a variadic macro).
+ BOOST_CONTRACT_ASSERT(``[^['boolean-condition]]``)
+ // Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...
+ BOOST_CONTRACT_ASSERT((``[^['boolean-condition]]``)) // ...use extra parenthesis (not a variadic macro).
-This library will automatically call failure handlers [funcref boost::contract::entry_invariant_failure] or [funcref boost::contract::exit_invariant_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false and, more in general, if the `invariant` function throws an exception when invariants are checked at function entry or exit respectively.
+This library will automatically call failure handlers [funcref boost::contract::entry_invariant_failure] or [funcref boost::contract::exit_invariant_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false or, more in general, if the `invariant` function throws an exception when invariants are checked at function entry or exit respectively.
By default, these handlers print an error message to `std::cerr` and terminate the program calling `std::terminate` (see __Throw_on_Failures__ to change these failure handlers to throw exceptions, exit the program with an error code, etc.).
See __Access_Specifiers__ to avoid making the `invariant` member function `public`.
When static class invariants are specified, they are programmed in a public `static` function named `static_invariant` taking no argument and returning `void`.
Classes that do not have static class invariants, simply do not declare the `static_invariant` function.
[footnote
-This library uses template meta-programming (SFINAE-based introspection techniques) to check static invariants only for classes that declare a member function named [macroref BOOST_CONTRACT_STATIC_INVARIANT_FUNC].
+This library uses template meta-programming (SFINAE-based introspection techniques) to check static invariants only for classes that declare a member function named by [macroref BOOST_CONTRACT_STATIC_INVARIANT_FUNC].
]
For example:
This library will generate a compile-time error if the `static` classifier is missing (unless the [macroref BOOST_CONTRACT_PERMISSIVE] macro is defined).
Any code can be programmed in the `static_invariant` function, but it is recommended to keep this code simple using mainly assertions and if-statements (to avoid programming complex static invariants that might be buggy and slow to check at run-time).
-It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program the assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (this is not a variadic macro, see __No_Macros__):
+It is also recommended to use [macroref BOOST_CONTRACT_ASSERT] to program the assertions because that enables this library to print informative error messages when the asserted conditions are evaluated to be false (note that this is not a variadic macro, see __No_Macros__):
- BOOST_CONTRACT_ASSERT(bool_cond)
- // Or, if condition has commas `,` not already within parenthesis `()`...
- BOOST_CONTRACT_ASSERT((bool_cond)) // ...use extra parenthesis (not a variadic macro).
+ BOOST_CONTRACT_ASSERT(``[^['boolean-condition]]``)
+ // Or, if `boolean-condition` has commas `,` not already within parenthesis `()`...
+ BOOST_CONTRACT_ASSERT((``[^['boolean-condition]]``)) // ...use extra parenthesis (not a variadic macro).
-This library will automatically call failure handlers [funcref boost::contract::entry_invariant_failure] or [funcref boost::contract::exit_invariant_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false and, more in general, if the `static_invariant` function throws an exception when invariants are checked at function entry or exit respectively.
+This library will automatically call failure handlers [funcref boost::contract::entry_invariant_failure] or [funcref boost::contract::exit_invariant_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] conditions are false or, more in general, if the `static_invariant` function throws an exception when invariants are checked at function entry or exit respectively.
By default, these handlers print an error message to `std::cerr` and terminate the program calling `std::terminate` (see __Throw_on_Failures__ to change these failure handlers to throw exceptions, exit the program with an error code, etc.).
See __Access_Specifiers__ to avoid making `static_invariant` member function `public`.
[public_class_end]
It is not possible to specify preconditions using `.precondition(...)` for constructors (this library will generate a compile-time error if `.precondition(...)` is used on the object returned by [funcref boost::contract::constructor]).
-Constructor preconditions are specified using the [classref boost::contract::constructor_precondition] base class instead (but considerations from __Preconditions__ apply also to the precondition functor passed to [classref boost::contract::constructor_precondition]).
+Constructor preconditions are specified using the [classref boost::contract::constructor_precondition] base class instead (same considerations as the ones made in __Preconditions__ apply also to the precondition functor passed to [classref boost::contract::constructor_precondition]).
Programmes should not access the object `*this` from constructor preconditions (because the object does not exists yet before the constructor body is executed).
[footnote
See __No_Lambda_Functions__ to enforce this constraint at compile-time (but not recommended because of extra boiler-plate code).
* It should be specified as the /first/ class in the inheritance list (so constructor preconditions are checked before initializing any other base class or data member).
* Its inheritance access specifier should always be `private` (so this extra base class does not alter the public inheritance tree of its derived classes).
-* It takes the derived class as template parameter (the Curiously Recursive Template Pattern (CRTP) is used here to avoid ambiguity resolution errors with multiple inheritance).
+* It should never be declared as a `virtual` base (because virtual bases are initialized only once across the entire inheritance hierarchy preventing preconditions of other base classes from being checked).
+* It takes the derived class as template parameter.
[footnote
*Rationale:*
-The [classref boost::contract::constructor_precondition] takes the derived class as its template parameter so the instantiated template type is unique for each derived class.
+The [classref boost::contract::constructor_precondition] takes the derived class as its template parameter (using the Curiously Recursive Template Pattern, CRTP) so the instantiated template type is unique for each derived class.
This always avoids base class ambiguity resolution errors even when multiple inheritance is used.
-Note that virtual inheritance could not be used instead of the template parameter here to resolve ambiguities (because virtual bases are initialized only once by the outer-most derived class, and that would not allow to properly check preconditions of all base classes).
+Note that, as already mentioned, virtual inheritance could not be used instead of the template parameter here to resolve ambiguities (because virtual bases are initialized only once by the outer-most derived class, and that would not allow to properly check preconditions of all base classes).
]
[note
[footnote
See __No_Lambda_Functions__ to enforce this constraint at compile-time (but not recommended because of extra boiler-plate code).
]
-It is also possible to specify exceptions guarantees for constructors (see __Exception_Guarantees__), but programmers should not access the object `this` or its old value in constructor exception guarantees (because the object did not exist before executing the constructor body and it was not properly constructed given the constructor body threw an exception).
+It is also possible to specify exceptions guarantees for constructors (see __Exception_Guarantees__), but programmers should not access the object `*this` or its old value in constructor exception guarantees (because the object did not exist before executing the constructor body and it was not properly constructed given the constructor body threw an exception).
[footnote
See __No_Lambda_Functions__ to enforce these constraints at compile-time (but not recommended because of extra boiler-plate code).
]
The [funcref boost::contract::constructor] function returns an RAII object that must always be assigned to a local variable of type [classref boost::contract::check] (otherwise this library will generate a run-time error, see [macroref BOOST_CONTRACT_ON_MISSING_CHECK_DECL]).
Furthermore, C++11 `auto` declarations cannot be used here and the [classref boost::contract::check] type must be explicitly specified (otherwise this library will generate a compile-time error prior C++17 and a run-time error post C++17).
-The constructor body is programmed right after the declaration of the RAII object.
+The constructor body is programmed right after the declaration of this RAII object.
At construction, the [classref boost::contract::check] RAII object for constructors does the following (enclosing constructor entry):
Similar considerations apply to all other constructors automatically generated by C++ (e.g., the move constructor).
]
+[heading Private and Protected Constructors]
+
Private and protected constructors can omit [funcref boost::contract::constructor] (because they are not part of the public interface of the class so they are not required to check class invariants, see __Constructor_Calls__).
They could still use [classref boost::contract::constructor_precondition] to check preconditions before member initializations, and even use [funcref boost::contract::function] (but not [funcref boost::contract::constructor]) to only check postconditions and exception guarantees without checking class invariants and without calling `.precondition(...)` (see __Private_and_Protected_Functions__).
For example:
[public_class_end]
It is not possible to specify preconditions for destructors (this library will generate a compile-time error if `.precondition(...)` is used here and that is because destructors can be called at any time after construction so they have no precondition).
-It is possible to specify postconditions for destructors (see __Postconditions__, and also __Static_Public_Functions__ for an example), but programmers should not access the object `this` in destructor postconditions (because the object no longer exists after the destructor body has been executed).
+It is possible to specify postconditions for destructors (see __Postconditions__, and also __Static_Public_Functions__ for an example), but programmers should not access the object `*this` in destructor postconditions (because the object no longer exists after the destructor body has been executed).
[footnote
See __No_Lambda_Functions__ to enforce this constraint at compile-time (but not recommended because of extra boiler-plate code).
]
-It is also possible to specify exceptions guarantees for destructors (see __Exception_Guarantees__, even if destructors should usually be programmed to not throw exceptions in C++ and in fact they are implicitly declared `noexcept` since C++11).
+It is also possible to specify exceptions guarantees for destructors (see __Exception_Guarantees__, even if destructors should usually be programmed to not throw exceptions in C++, in fact destructors are implicitly declared `noexcept` since C++11).
[footnote
-Exceptions guarantees in destructors can access both the object `this` and its old value because the object exited before executing the destructor body and it still exists given the destructor body failed throwing an exception so the object should still be properly constructed and satisfy its class invariants.
+Exceptions guarantees in destructors can access both the object `*this` and its old value because the object existed before executing the destructor body and it still exists given the destructor body failed throwing an exception so technically the object should still be properly constructed and satisfy its class invariants.
]
The [funcref boost::contract::destructor] function takes `this` as a parameter (because destructors check class invariants, see __Class_Invariants__).
The [funcref boost::contract::destructor] function returns an RAII object that must always be assigned to a local variable of type [classref boost::contract::check] (otherwise this library will generate a run-time error, see [macroref BOOST_CONTRACT_ON_MISSING_CHECK_DECL]).
Furthermore, C++11 `auto` declarations cannot be used here and the [classref boost::contract::check] type must be explicitly specified (otherwise this library will generate a compile-time error prior C++17 and a run-time error post C++17).
-The destructor body is programmed right after the declaration of the RAII object.
+The destructor body is programmed right after the declaration of this RAII object.
At construction, the [classref boost::contract::check] RAII object for destructors does the following (enclosing destructor entry):
Therefore, unless the destructor is not public or it has no postconditions, no exception guarantees, and its class has no invariants, programmers should manually define it using [funcref boost::contract::destructor].
]
+[heading Private and Protected Destructors]
+
Private and protected destructors can omit [funcref boost::contract::destructor] (because they are not part of the public interface of the class so they are not required to check class invariants, see __Destructor_Calls__).
They could use [funcref boost::contract::function] (but not [funcref boost::contract::destructor]) to only check postconditions and exception guarantees without checking class invariants and without calling `.precondition(...)` (see __Private_and_Protected_Functions__).
For example:
The [funcref boost::contract::public_function] function returns an RAII object that must always be assigned to a local variable of type [classref boost::contract::check] (otherwise this library will generate a run-time error, see [macroref BOOST_CONTRACT_ON_MISSING_CHECK_DECL]).
Furthermore, C++11 `auto` declarations cannot be used here and the [classref boost::contract::check] type must be explicitly specified (otherwise this library will generate a compile-time error prior C++17 and a run-time error post C++17).
-The public function body is programmed right after the declaration of the RAII object.
+The public function body is programmed right after the declaration of this RAII object.
At construction, the [classref boost::contract::check] RAII object for public functions does the following (enclosing public function entry):
[footnote
*Rationale:*
The [classref boost::contract::virtual_]`*` parameter is used by this library to determine that a function is virtual (in C++ it is not possible to introspect if a function is declared `virtual`).
-Furthermore, this parameter is internally used by this library to pass result and old values that are evaluated by the overriding function to overridden virtual functions in base classes, and also to check preconditions, postconditions, and exception guarantees of overridden virtual functions to implement subcontracting.
+Furthermore, this parameter is internally used by this library to implement subcontracting (specifically to pass result and old values that are evaluated by the overriding function to the contracts of overridden virtual functions in base classes, and also to check preconditions, postconditions, and exception guarantees of overridden virtual functions in __OR__ and __AND__ with contracts of the overriding virtual function).
]
When called from virtual public functions, the [funcref boost::contract::public_function] function takes `this` as a parameter (because public functions check class invariants, see __Class_Invariants__).
In this case, the library will pass this return value reference to the postcondition functor that must therefore take one single argument matching the return type, otherwise this library will generate a compile-time error (the functor parameter can be a constant reference `const&` to avoid extra copies of the return value):
[footnote
*Rationale:*
-The extra function result parameter taken by the functor passed to `.postcondition(...)` is used by this library to pass the return value evaluated by the overriding function to all its overridden virtual functions when subcontracting.
+The extra function result parameter taken by the functor passed to `.postcondition(...)` is used by this library to pass the return value evaluated by the overriding function to all its overridden virtual functions to support subcontracting.
]
class u {
[section Public Function Overrides (Subcontracting)]
Contracts for public functions are programmed using [funcref boost::contract::public_function].
-In this section, let's consider public functions (virtual or not) that override virtual public functions from one or more public base classes.
+In this section, let's consider public functions (virtual or not) that override virtual public functions from one or more of their public base classes.
For example (see [@../../example/features/public.cpp =public.cpp=]):
[footnote
In this documentation, function overrides are often marked with the code comment `/* override */`.
[public_function_override]
[public_derived_class_end]
-The extra `typedef` declared using [macroref BOOST_CONTRACT_BASE_TYPES] is required by this library for derived classes and it is internally used detect base classes for subcontracting (see __Base_Classes__).
+The extra `typedef` declared using [macroref BOOST_CONTRACT_BASE_TYPES] is required by this library for derived classes and it is internally used to detect base classes for subcontracting (see __Base_Classes__).
+This library will generate a compile-time error if there is no suitable virtual function to override in any of the public base classes for subcontracting.
+[footnote
+The compile-time error generated by the library in this case is similar in principle to the error generated by the C++11 `override` specifier, but it is limited to functions with the extra [classref boost::contract::virtual_]`*` parameter and searched recursively only in `public` base classes passed to [macroref BOOST_CONTRACT_BASE_TYPES] because only those are considered for subcontracting.
+]
When called from public function overrides, the [funcref boost::contract::public_function] function template takes an explicit template argument `override_`[^['function-name]] that must be defined using [macroref BOOST_CONTRACT_OVERRIDE]:
- BOOST_CONTRACT_OVERRIDE(func_name)
+ BOOST_CONTRACT_OVERRIDE(``[^['function-name]]``)
-This can be declared at any point in the public section of the enclosing class (see __Access_Specifiers__ to use [macroref BOOST_CONTRACT_OVERRIDE] in a non-public section of the class instead).
+This can be declared at any point in the public section of the enclosing class (see __Access_Specifiers__ to use [macroref BOOST_CONTRACT_OVERRIDE] also in a non-public section of the class).
[macroref BOOST_CONTRACT_OVERRIDE] is used only once in a class for a given function name and overloaded functions can reuse the same [^override_['function-name]] definition (see __Function_Overloads__).
[macroref BOOST_CONTRACT_NAMED_OVERRIDE] can be used to generate a name different than [^override_['function-name]] (e.g., to avoid generating C++ reserved names containing double underscores "`__`" for function names that already start with an underscore "`_`", see __Named_Overrides__).
For convenience [macroref BOOST_CONTRACT_OVERRIDES] can be used with multiple function names instead of repeating [macroref BOOST_CONTRACT_OVERRIDE] for each function name (on compilers that support variadic macros).
Is equivalent to:
[footnote
-This library does not provider an equivalent of [macroref BOOST_CONTRACT_NAMED_OVERRIDE] that operates on multiple function names at once (simply because programmers will probably not use [macroref BOOST_CONTRACT_NAMED_OVERRIDE] often in the first place).
+There is no equivalent of [macroref BOOST_CONTRACT_NAMED_OVERRIDE] that operates on multiple function names at once ([macroref BOOST_CONTRACT_NAMED_OVERRIDE] is not expected to be used often so it can simply be repeated multiple times when needed).
]
BOOST_CONTRACT_OVERRIDE(f)
BOOST_CONTRACT_OVERRIDE(g)
BOOST_CONTRACT_OVERRIDE(h)
-This library will generate a compile-time error if there is no suitable virtual function to override in any of the public base classes for subcontracting.
-[footnote
-The compile-time error generated by the library in this case is similar in principle to the error generated by the C++11 `override` specifier, but it is limited to functions with the extra [classref boost::contract::virtual_]`*` parameter and searched recursively only in `public` base classes passed to [macroref BOOST_CONTRACT_BASE_TYPES] because only those are considered for subcontracting.
-]
-
-Public function overrides must always list the extra trailing parameter of type [classref boost::contract::virtual_]`*` with default value `0` (i.e., `nullptr`), even when they are not declared `virtual` (because this parameter is present in the signature of the virtual function being overridden from base classes).
+Public function overrides must always list the extra trailing parameter of type [classref boost::contract::virtual_]`*` with default value `0` (i.e., `nullptr`), even when they are not declared `virtual`, if this parameter is present in the signature of the virtual function being overridden from base classes.
Programmers must pass the extra virtual parameter as the very first argument to all [macroref BOOST_CONTRACT_OLDOF] and [funcref boost::contract::public_function] calls in the public function override definition (see __Virtual_Public_Functions__).
-When called from public function overrides, the [funcref boost::contract::public_function] function takes a pointer to the enclosing function, the object `this` (because public function overrides check class invariants, see __Class_Invariants__), and references to each function argument in the order they appear in the function declaration.
+When called from public function overrides, the [funcref boost::contract::public_function] function takes a pointer to the enclosing function, the object `*this` (because public function overrides check class invariants, see __Class_Invariants__), and references to each function argument in the order they appear in the function declaration.
[footnote
*Rationale:*
The object `this` is passed after the function pointer to follow `std::bind`'s syntax.
-The function pointer and references to all function arguments are needed for public function overrides because this library has to call overridden virtual public functions to check their contracts for subcontracting (even if this library will not actually execute the bodies of the overridden functions).
+The function pointer and references to all function arguments are needed for public function overrides because this library has to internally call overridden virtual public functions to check their contracts for subcontracting (even if this library will not actually execute the bodies of the overridden functions).
]
For public function overrides returning `void`:
...
}
-
BOOST_CONTRACT_OVERRIDE(f)
...
As for non-overriding virtual public functions, also public function overrides use the extra return value parameter to pass it to the overridden functions when subcontracting.
In the case of public function overrides, this library has the function pointer so it will generate a compile-time error if the function is non-void and programmers forget to specify the extra return value parameter (this extra error checking is not possible instead for non-overriding virtual public functions because their contracts do not take the function pointer as a parameter, see __Virtual_Public_Functions__).
]
-In this case, the library will pass this return value reference to the postcondition functor that must therefore take one single argument matching the return type, otherwise this library will generate a compile-time error (the functor parameter can be a constant reference `const&` to avoid extra copies of the return value):
+In this case, the library will pass this return value reference to the postcondition functor that must therefore take one single argument matching the return type, otherwise this library will generate a compile-time error (the functor parameter can be a constant reference `const&` to avoid extra copies of the return value, similarly to non-overriding non-void __Virtual_Public_Functions__):
class u {
public:
... // Assign `result` at each return.
}
-
BOOST_CONTRACT_OVERRIDE(f)
...
This library will throw [classref boost::contract::bad_virtual_result_cast] if programmers specify return values for public function overrides in derived classes that are not consistent with the return types of the virtual public functions being overridden in the base classes.
[footnote
*Rationale:*
-The `boost::bad_any_cast` exception could not used here because it does not print the from- and to- type names (so it is not descriptive enough).
+The `boost::bad_any_cast` exception was not used here because it does not print the from- and to- type names (so it is not descriptive enough).
]
[important
This library cannot always generate compile-time errors if programmers fail to do so (but in general this will prevent the library from correctly checking contracts at run-time).
*Mnemonics:*
-[:When `override_...` is present, always pass it as template parameter to [funcref boost::contract::public_functioon].]
+[:When `override_...` is present, always pass it as template parameter to [funcref boost::contract::public_function].]
[:When `v` is present, always pass it as the first argument to [funcref boost::contract::public_function] and [macroref BOOST_CONTRACT_OLDOF].]
[:Always pass `result` to [funcref boost::contract::public_function] right after `v` for non-void functions.]
]
# Else:
# Check exception guarantees for all overridden base functions and for the overriding derived function in __AND__ with each other, by calling the nullary functors [^['e_1]]`()` __AND__... [^['e_n]]`()` __AND__ [^['e]]`()` passed to `.except(`[^['e_1]]`)`, ... `.except(`[^['e_n]]`)`, `.except(`[^['e]]`)` for all of the overridden and overriding functions respectively.
-This ensures that public function override contracts and subcontracts are correctly checked at run-time (see __Public_Function_Calls__).
+This ensures that contracts and subcontracts of public function overrides are correctly checked at run-time in accordance with the __substitution_principle__ (see __Public_Function_Calls__).
For the rest, considerations made in __Virtual_Public_Functions__ apply to public function overrides as well.
[import ../example/features/base_types.cpp]
[base_types]
-For convenience, a local macro named `BASES` can be used to avoid repeating the base list twice (first in the derived class declaration `class `[^['class-name]]` : `[^['base-list]] and then again when invoking `BOOST_CONTRACT_BASE_TYPES(`[^['base-list]]`)`).
-Being a local macro, `BASES` must be undefined using `#undef BASES` after it has been used to declare `base_types` (to avoid name clashes and macro redefinition errors).
+For convenience, a /local macro/ named `BASES` can be used to avoid repeating the base list twice (first in the derived class declaration `class `[^['class-name]]` : `[^['base-list]] and then again when invoking `BOOST_CONTRACT_BASE_TYPES(`[^['base-list]]`)`).
+Being a local macro, `BASES` must be undefined using `#undef BASES` after it is used to declare the `base_types` `typedef` (to avoid name clashes and macro redefinition errors).
[footnote
The name of this local macro is arbitrary, but `BASES` is often used in this documentation.
]
[footnote
*Rationale:*
This library explicitly requires the inheritance access level because derived classes must subcontract only from public bases, but not from protected or private bases (see __Public_Function_Calls__).
-[macroref BOOST_CONTRACT_BASE_TYPES] inspects each inheritance access level using preprocessor meta-programming and removes non-public bases from the list of bases inspected for subcontracting.
+[macroref BOOST_CONTRACT_BASE_TYPES] inspects each inheritance access level using preprocessor meta-programming and removes non-public bases from the list of bases internally used for subcontracting.
However, this library cannot always detect when programmers forget to specify the inheritance access level because, when commas are used to separate template parameters passed to base classes, the preprocessor will not be able to correctly use commas to identify the next base class token in the inheritance list (the preprocessor cannot distinguish between commas that are not protected by round parenthesis, like the ones used in templates).
-Therefore, this library relies on inheritance access levels to program the preprocessor to correctly identify the next base class token in the inheritance list (thus inheritance access levels must always be explicit specified by programmers).
+Therefore, this library uses the inheritance access level keyword `public`, `protected`, or `private` instead of commas `,` for the preprocessor to correctly find the next base class token in the inheritance list (thus inheritance access levels must always be explicit specified by programmers for each base).
]
It is the responsibility of the programmers to make sure that all bases passed to [macroref BOOST_CONTRACT_BASE_TYPES] explicitly specify their inheritance access level (inheritance access levels are instead optional in C++ because `private` is implicitly assumed for `class` types and `public` for `struct` types).
[static_public]
It is possible to specify preconditions, postconditions, and exception guarantees for static public functions (see __Preconditions__, __Postconditions__, and __Exception_Guarantees__).
-When called from static public functions, [funcref boost::contract::public_function] cannot take the object `this` as a parameter (because there is no object `this` in static member functions) so the enclosing class type is is specified as an explicit template parameter (the class type is required to check static class invariants, see __Class_Invariants__):
+When called from static public functions, [funcref boost::contract::public_function] cannot take the object `this` as a parameter (because there is no object `this` in static member functions) so the enclosing class type is specified via an explicit template parameter as in [funcref boost::contract::public_function][^<['class-type]>] (the class type is required to check static class invariants, see __Class_Invariants__):
class u {
public:
The [funcref boost::contract::public_function] function returns an RAII object that must be assigned to a local variable of type [classref boost::contract::check] (otherwise this library will generate a run-time error, see [macroref BOOST_CONTRACT_ON_MISSING_CHECK_DECL]).
Furthermore, C++11 `auto` declarations cannot be used here and the [classref boost::contract::check] type must be explicitly specified (otherwise this library will generate a compile-time error prior C++17 and a run-time error post C++17).
-The static public functions body is programmed right after the declaration of the RAII object.
+The static public functions body is programmed right after the declaration of this RAII object.
At construction, the [classref boost::contract::check] RAII object for static public functions does the following (enclosing static public function entry):
projects / platform / upstream / boost.git / blobdiff