townforge/contract
1
0
Fork 0
Code Issues Pull Requests Releases Wiki Activity

finished updating docs up to tutorial section

Browse Source
This commit is contained in:
Lorenzo Caminiti 2016-04-08 20:16:02 -07:00
parent 02ed8498ab
commit a5c462ccd2
35 changed files with 1705 additions and 1383 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
Jamroot
View File

@ -13,15 +13,13 @@ use-project boost : $(BOOST_ROOT) ;
project
:
requirements
<include>"./include"
<toolset>gcc:<cxxflags>-std=c++11
<toolset>clang:<cxxflags>-std=c++11
<include>"./include"
<include>$(BOOST_ROOT)
<toolset>msvc:<library-path>$(BOOST_ROOT)/stage.msvc/lib
<toolset>gcc:<library-path>$(BOOST_ROOT)/stage.gcc/lib
<toolset>clang:<library-path>$(BOOST_ROOT)/stage.clang/lib
<library-path>$(BOOST_ROOT)/stage/lib
<toolset>gcc:<library>/boost/system//boost_system
<toolset>clang:<library>/boost/system//boost_system
;
@ -68,7 +66,7 @@ rule subdir-run ( subdir : cpp_fname : requirements * ) {
;
}
rule subdir-run-aliased ( subdir : cpp_fname : requirements * ) {
rule subdir-run-with-no ( subdir : cpp_fname : requirements * ) {
# Aliases explicitly built or implicitly when building all tests...
alias $(subdir)-$(cpp_fname)-no_entryinv : $(subdir)-$(cpp_fname) :
<boost_contract-no>entryinv ;

18
doc/Jamfile.v2
View File

@ -30,18 +30,16 @@ using boostbook ;
# <doxygen:param>ALIASES=" Params=\"<b>Parameters:</b> <table border="0">\" Param{2}=\"<tr><td><b><tt>\\1</tt></b></td><td>\\2</td></tr>\" EndParams=\"</table>\" Returns=\"<b>Returns:</b>\" Note=\"<b>Note:</b>\" Warning=\"<b>Warning:</b>\" SeeAlso=\"<b>See also:</b>\" RefSect{2}=\"\\xmlonly<link linkend='contract__.\\1'>\\2</link>\\endxmlonly\" RefClass{1}=\"\\xmlonly<computeroutput><classname alt='\\1'>\\1</classname></computeroutput>\\endxmlonly\" RefFunc{1}=\"\\xmlonly<computeroutput><functionname alt='\\1'>\\1</functionname></computeroutput>\\endxmlonly\" RefMacro{1}=\"\\xmlonly<computeroutput><macroname alt='\\1'>\\1</macroname></computeroutput>\\endxmlonly\" RefEnum{1}=\"\\xmlonly<computeroutput><enumname alt='\\1'>\\1</enumname></computeroutput>\\endxmlonly\" "
# ;
xml contract
: qbk/contract.qbk
xml contract : contract.qbk
# : <dependency>reference
;
boostbook doc
: contract
:
<location>html
<xsl:param>boost.defaults=Boost
<xsl:param>boost.root=../../
<xsl:param>admon.graphics.path=../../doc/src/images/
<xsl:param>html.stylesheet=../../doc/src/boostbook.css
boostbook doc : contract
:
<location>html
<xsl:param>boost.defaults=Boost
<xsl:param>boost.root=../../
<xsl:param>admon.graphics.path=../../doc/src/images/
<xsl:param>html.stylesheet=../../doc/src/boostbook.css
;

0
doc/qbk/acknowledgments.qbk → doc/acknowledgments.qbk
View File

102
doc/qbk/advanced_topics.qbk → doc/advanced_topics.qbk
View File

@ -12,7 +12,7 @@ It is possible to use `boost::optional` to handle the return value when programm
]
For example (see also [@../../example/features/optional_result.cpp =optional_result.cpp=]):
[import ../../example/features/optional_result.cpp]
[import ../example/features/optional_result.cpp]
[optional_result]
In this example the return type `surface` does not have a default constructor that can be used to initialize `result` when it is first declared.
@ -37,7 +37,7 @@ Similarly, `boost::optional` can be used for return values passed to virtual and
TODO
[import ../../example/features/old.cpp]
[import ../example/features/old.cpp]
[old]
[endsect]
@ -50,7 +50,7 @@ However, in this case contracts are always programmed out-of-line, in the defaul
For example, note how the following `shape::area` default implementation (which is used to program the contract) must be defined out-of-line and therefore outside the `shape` class declaration (see also [@../../example/features/pure_virtual.cpp =pure_virtual.cpp=]):
[import ../../example/features/pure_virtual.cpp]
[import ../example/features/pure_virtual.cpp]
[pure_virtual]
This library will never actually execute the pure virtual function body while it is calling the pure virtual function default implementation to check its contract for subcontracting.
@ -62,74 +62,6 @@ Therefore, no contract is ever programmed for a private or protected pure virtua
[endsect]
[section Static Public Functions]
Contracts for static public member functions are programmed using the [funcref boost::contract::public_function] function.
However, in this case [funcref boost::contract::public_function] takes the enclosing class type as an explicit template parameter instead of taking the object `this` as a function parameter (because there is no object `this` in static member functions):
auto c = boost::contract::public_function<``[^['class-type]]``>()
... // Preconditions and postconditions.
;
For example (see also [@../../example/features/static.cpp =static.cpp=]):
[import ../../example/features/static.cpp]
[static]
Even if they are not present in this example, it is possible to specify both preconditions and postconditions for static public member functions (see also __Preconditions__ and __Postconditions__).
[funcref boost::contract::public_function] takes the class type as a template parameter because static public member functions check static class invariants (but it does not take the object `this` and obviously static public member functions do not check non-static class invariants, see also __Class_Invariants__).
[funcref boost::contract::public_function] returns an RAII object (that can be assigned to a local variable of explicit type [classref boost::contract::guard] when programmers are not using C++11 auto declarations).
The static public member function body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check static class invariants, by calling [^['class-type]]`::static_invariant()` (but never non-static class invariants).
# Check preconditions, by calling the functor [^['f]]`()` passed to `.precondition(`[^['f]]`)`.
At destruction instead:
# Check static class invariants, by calling [^['class-type]]`::static_invariant()` (even if the function body threw and exception, but never non-static class invariants).
# If the function body did not throw an exception:
# Check postconditions, by calling the functor [^['g]]`()` passed to `.postcondition(`[^['g]]`)`.
This ensures that static public member function contracts are correctly checked at run-time (note that static public member functions do not subcontract, see also __Public_Function_Calls__).
[note
A static public member function can avoid calling [funcref boost::contract::public_function] for efficiency but only when it has no precondition and no postconditions, and its class has not static invariant (its class can still have non-static invariants or base classes instead).
]
As already discussed in __Private_and_Protected_Functions__, private and protected member functions never check static or non-static class invariants (not even when they are static member functions).
Therefore, [funcref boost::contract::function] is always used for private and protected member functions, also whey they are static member functions.
[heading Static Class Invariants]
As shown by the example above, when static class invariants are specified, the re programmed in a public `static` member function named `static_invariant` taking no argument and returning `void` (this library will generate a compile-time error if the `static` classifier is missing, unless [macroref BOOST_CONTRACT_CONFIG_PERMISSIVE] is set).
Classes that do not static class invariants, simply do not declare a `static_invariant` member 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 `static_invariant`.
]
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 execute at run-time).
It is also recommended to use the [macroref BOOST_CONTRACT_ASSERT] macro to program the assertions because it enables this library to print very informative error messages when the asserted conditions are evaluated to be false at run-time (this is not a variadic macro, but see also __No_Macros__):
BOOST_CONTRACT_ASSERT(``/boolean-condition/``)
// Or, if condition has commas `,` not already within parenthesis `(...)`.
BOOST_CONTRACT_ASSERT((``/boolean-condition/``))
This library will automatically call [funcref boost::contract::entry_invariant_failed] or [funcref boost::contract::exit_invariant_failed] if any of the [macroref BOOST_CONTRACT_ASSERT] macro conditions are `false` and also if the `static_invariant` function throws an exception (by default, this terminates the program calling `std::terminate`, but see __Throw_on_Failure__ to throw exceptions, exit the program with an error code, etc.).
See __Access__ to avoid making `static_invariant` a public member function (e.g., in cases when all public members of a class must be controlled exactly).
Set the [macroref BOOST_CONTRACT_CONFIG_STATIC_INVARIANT] configuration macro to use a name different from `static_invariant` (e.g., because `static_invariant` clashes with other names in the user-defined class).
[footnote
*Rationale.*
It is not possible to overload a member function in C++ based on the `static` classifier.
Therefore, different function names have to be used for member functions checking static and non-static class invariants (e.g., `invariant` and `static_invariant`).
]
Furthermore, see __Class_Invariants__ and __Volatile_Public_Functions__ for programming non-static and volatile class invariants respectively.
[endsect]
[section Volatile Public Functions]
TODO
@ -142,7 +74,7 @@ Calls to [funcref boost::contract::public_function] from different overloaded fu
Therefore, [macroref BOOST_CONTRACT_OVERRIDE][^(['function-name])] is used only once in a given class even when [^['function-name]] is overloaded.
For example (see also [@../../example/features/override_overload.cpp =override_overload.cpp=]):
[import ../../example/features/override_overload.cpp]
[import ../example/features/override_overload.cpp]
[override_overload]
Note that the function name passed to [macroref BOOST_CONTRACT_OVERRIDE] should never start with an underscore to avoid generating names containing double underscores `override__...` that are reserved by the C++ standard.
@ -158,7 +90,7 @@ It is best to use a different macro name [macroref BOOST_CONTRACT_NAMED_OVERRIDE
This second macro can be used for function names that start with an underscore `_...`, when the name `override_`[^['function-name]] clashes with another name the user class, or in any other case when programmers need to generate a name different than `override_...`.
For example (see also [@../../example/features/named_override.cpp =named_override.cpp=]):
[import ../../example/features/named_override.cpp]
[import ../example/features/named_override.cpp]
[named_override]
[endsect]
@ -179,12 +111,12 @@ At the cost of programmers writing an extra function declaration for the body fu
For example, the following header file only contains function declarations and contract code (see also [@../../example/features/separate_body.hpp =separate_body.hpp=]):
[import ../../example/features/separate_body.hpp]
[import ../example/features/separate_body.hpp]
[separate_body_hpp]
Instead, the code implementing the function bodies is programmed in a separate source file (see also [@../../example/features/separate_body.cpp =separate_body.cpp=]):
[import ../../example/features/separate_body.cpp]
[import ../example/features/separate_body.cpp]
[separate_body_cpp]
The same technique can be used for free, private, and protected functions.
@ -211,7 +143,7 @@ In theory, using C++14 generic lambdas, the [macroref BOOST_CONTRACT_OVERRIDE] m
`invariant`, `static_invariant`, and `base_types` normally need to be `public`, but programmers can declare them in a `private` (or `protected`) section of the class as long as they also declare the [classref boost::contract::access] class as `friend`.
For example (see also [@../../example/features/access.cpp =access.cpp=]):
[import ../../example/features/access.cpp]
[import ../example/features/access.cpp]
[access]
This technique is not used in most examples of this documentation only for brevity, but programmers are encouraged to use it in real code.
@ -222,7 +154,7 @@ See also __Base_Types__, __Class_Invariant__, and __Overloads_and_Named_Override
[section Throw on Failure]
[import ../../example/features/throw_on_failure.cpp]
[import ../example/features/throw_on_failure.cpp]
If a condition checked using [macroref BOOST_CONTRACT_ASSERT] is `false` or if code specified in preconditions, postconditions, and class invariants throw any exception, this library calls the /contract failure handler/ functions [funcref boost::contract::precondition_failed], [funcref boost::contract::postcondition_failed], [funcref boost::contract::entry_invariant_failed], or [funcref boost::contract::exit_invariant_failed] respectively (in fact, [macroref BOOST_CONTRACT_ASSERT] simply expand to code that throw [classref boost::contract::assertion_failure], see also __No_Macros__).
@ -253,6 +185,12 @@ For example (see also [@../../example/features/throw_on_failure.cpp =throw_on_fa
[endsect]
[section Disable Contract Checking]
TODO
[endsect]
[section Assertion Requirements (Call-If)]
In general, assertions can introduce a new set of requirements on the types used by the program: Some of the type requirements might be necessary only to program the assertions and they would not be required by the program otherwise.
@ -268,7 +206,7 @@ However, the full contracts of the `vector<T>::push_back(value)` member function
Programmers can specify this postcondition as-is an let the program fail to compile when users instantiate this template with a type `T` that does not provide an equality operator `==`.
Otherwise, programmers can specify this postcondition using [funcref boost::contract::call_if] so to check the assertion only for types `T` that have an equality operator `==`, and trivially check `true` otherwise (see also [@../../example/features/call_if.cpp =call_if.cpp=]):
[import ../../example/features/call_if.cpp]
[import ../example/features/call_if.cpp]
[call_if]
[funcref boost::contract::call_if] takes a condition template parameter as a boolean meta-function.
@ -300,7 +238,7 @@ TODO
[funcref boost::contract::call_if] is a general-purpose facility and it can be used together with C++14 generic lambdas to implement statements similar to `static if` (at least at function scope, see also [@http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2013/n3613.pdf N3613]).
For example, consider the following implementation of `std::advance` that uses `static if`-like statements implemented via [funcref boost::contract::call_if] (see also [@../../example/features/static_if_cxx14.cpp =static_if_cxx14.cpp=]):
[import ../../example/features/static_if_cxx14.cpp]
[import ../example/features/static_if_cxx14.cpp]
[static_if_cxx14]
This implementation is much more concise, easy to read and maintain than the usual implementation of `std::advance` that uses tag dispatching.
@ -312,7 +250,7 @@ This implementation is much more concise, easy to read and maintain than the usu
[section No Macros (No C++11)]
[import ../../example/features/no_macros.cpp]
[import ../example/features/no_macros.cpp]
This section illustrates how to write contracts without using this library macros and programming the related code manually instead (a part from [macroref BOOST_CONTRACT_OVERRIDE] and [macroref BOOST_CONTRACT_NAMED_OVERRIDE] that cannot be programmed manually).
@ -399,10 +337,10 @@ However, not using C++11 lambda functions comes to the significant cost of havin
For example (see also [@../../example/features/no_lambdas.hpp =no_lambdas.hpp=] and [@../../example/features/no_lambdas.cpp =no_lambdas.cpp=]):
[import ../../example/features/no_lambdas.hpp]
[import ../example/features/no_lambdas.hpp]
[no_lambdas_hpp]
[import ../../example/features/no_lambdas.cpp]
[import ../example/features/no_lambdas.cpp]
[no_lambdas_cpp]
If programmers also want to fully enforce all contract programming constant-correctness requirements at compile-time, they should follow these rules when programming the contract functions (see also __Constant_Correctness__):

0
doc/qbk/bibliography.qbk → doc/bibliography.qbk
View File

111
doc/contract.qbk Normal file
View File

@ -0,0 +1,111 @@
[library Boost.Contract
[quickbook 1.5]
[version 1.0]
[authors [Caminiti <email>lorcaminiti@gmail.com</email>, Lorenzo]]
[copyright 2008-2016 Lorenzo Caminiti]
[license Distributed under the Boost Software License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a copy at [@http://www.boost.org/LICENSE_1_0.txt])]
[/ purpose Contract Programming for C++]
[/ category Correctness and Testing]
]
[template file[dir name] '''<ulink url="../../'''[dir]'''/'''[name]'''">'''[^[name]]'''</ulink>''']
[def __substitution_principle__ [@http://en.wikipedia.org/wiki/Liskov_substitution_principle substitution principle]]
[def __Introduction__ [link boost_contract.introduction Introduction]]
[def __Getting_Started__ [link boost_contract.getting_started Getting Started]]
[def __Contract_Programming_Overview__ [link boost_contract.contract_programming_overview Contract Programming Overview]]
[def __Function_Calls__ [link boost_contract.contract_programming_overview.function_calls Function Calls]]
[def __Public_Function_Calls__ [link boost_contract.contract_programming_overview.public_function_calls Public Function Calls]]
[def __Constructor_Calls__ [link boost_contract.contract_programming_overview.constructor_calls Constructor Calls]]
[def __Destructor_Calls__ [link boost_contract.contract_programming_overview.destructor_calls Destructor Calls]]
[def __Constant_Correctness__ [link boost_contract.contract_programming_overview.constant_correctness Constant-Correctness]]
[def __Specification_and_Implementation__ [link boost_contract.contract_programming_overview.specification_and_implementation Specification and Implementation]]
[def __Tutorial__ [link boost_contract.tutorial Tutorial]]
[def __Non_Member_Functions__ [link boost_contract.tutorial.non_member_functions Non-Member Functions]]
[def __Preconditions__ [link boost_contract.tutorial.preconditions Preconditions]]
[def __Postconditions__ [link boost_contract.tutorial.postconditions Postconditions]]
[def __Return_Value__ [link boost_contract.tutorial.return_value Return Value]]
[def __Old_Values__ [link boost_contract.tutorial.old_values Old Values]]
[def __Class_Invariants__ [link boost_contract.tutorial.class_invariants Class Invariants]]
[def __Static_Class_Invariants__ [link boost_contract.tutorial.class_invariants.static_class_invariants Static Class Invariants]]
[def __Constructors__ [link boost_contract.tutorial.constructors Constructors]]
[def __Destructors__ [link boost_contract.tutorial.destructors Destructors]]
[def __Public_Functions__ [link boost_contract.tutorial.public_functions Public Functions]]
[def __Public_Virtual_Functions__ [link boost_contract.tutorial.public_virtual_functions Public Virtual Functions]]
[def __Base_Classes__ [link boost_contract.tutorial.base_classes__subcontracting_ Base Classes]]
[def __Overriding_Public_Functions__ [link boost_contract.tutorial.overriding_public_functions__subcontracting_ Overriding Public Functions]]
[def __Private_and_Protected_Functions__ [link boost_contract.tutorial.private_and_protected_functions Private and Protected Functions]]
[def __Advanced_Topics__ [link boost_contract.advanced_topics Advanced Topics]]
[def __Optional_Return_Value__ [link boost_contract.advanced_topics.optional_return_value Optional Return Value]]
[def __Old_Values_at_Body__ [link boost_contract.advanced_topics.old_values_at_body Old Values at Body]]
[def __Static_Public_Functions__ [link boost_contract.advanced_topics.static_public_functions Static Public Functions]]
[def __Volatile_Public_Functions__ [link boost_contract.advanced_topics.volatile_public_functions Volatile Public Functions]]
[def __Overloads_and_Named_Overrides__ [link boost_contract.advanced_topics.overloads_and_named_overrides Overloads and Named Overrides]]
[def __Separate_Body_Implementation__ [link boost_contract.advanced_topics.separate_body_implementation Separate Body Implementation]]
[def __Access__ [link boost_contract.advanced_topics.access Access]]
[def __Throw_on_Failure__ [link boost_contract.advanced_topics.throw_on_failure Throw on Failure]]
[def __Disable_Contract_Checking__ [link boost_contract.advanced_topics.disable_contract_checking Disable Contract Checking]]
[def __No_Macros__ [link boost_contract.advanced_topics.no_macros__no_c__11_ No Macros]]
[def __No_Lambda_Functions__ [link boost_contract.advanced_topics.no_lambda_functions__no_c__11_ No Lambda Functions]]
[def __Reference__ [link boost_contract.reference Reference]]
[def __Examples__ [link boost_contract.examples Examples]]
[def __Annexes__ [link boost_contract.annexes Annexes]]
[def __Release_Notes__ [link boost_contract.release_notes Release Notes]]
[def __Bibliography__ [link boost_contract.bibliography Bibliography]]
[def __Acknowledgments__ [link boost_contract.acknowledgments Acknowledgments]]
[def __AND__ [link and_anchor [^['AND]]]]
[def __OR__ [link or_anchor [^['OR]]]]
[def __Bright04__ [link Bright04_anchor \[Bright04\]]]
[def __Bright04b__ [link Bright04b_anchor \[Bright04b\]]]
[def __C2__ [link C2_anchor \[C2\]]]
[def __Chrome02__ [link Chrome02_anchor \[Chrome02\]]]
[def __Cline90__ [link Cline90_anchor \[Cline90\]]]
[def __CodeContracts__ [link CodeContracts_anchor \[CodeContracts\]]]
[def __iContract__ [link iContract_anchor \[iContract\]]]
[def __Hoare73__ [link Hoare73_anchor \[Hoare73\]]]
[def __Jcontract__ [link Jcontract_anchor \[Jcontract\]]]
[def __Lindrud04__ [link Lindrud04_anchor \[Lindrud04\]]]
[def __Maley99__ [link Maley99_anchor \[Maley99\]]]
[def __Meyer97__ [link Meyer97_anchor \[Meyer97\]]]
[def __Mitchell02__ [link Mitchell02_anchor \[Mitchell02\]]]
[def __N1613__ [link N1613_anchor \[N1613\]]]
[def __N1866__ [link N1866_anchor \[N1866\]]]
[def __N1962__ [link N1962_anchor \[N1962\]]]
[def __N2081__ [link N2081_anchor \[N2081\]]]
[def __N2914__ [link N2914_anchor \[N2914\]]]
[def __SPARKAda__ [link SPARKAda_anchor \[SPARKAda\]]]
[def __SpecSharp__ [link SpecSharp_anchor \[SpecSharp\]]]
[def __Stroustrup97__ [link Stroustrup97_anchor \[Stroustrup97\]]]
[def __Stroustrup94__ [link Stroustrup94_anchor \[Stroustrup94\]]]
[def __Tandin04__ [link Tandin04_anchor \[Tandin04\]]]
[:['["Our field needs more formality, but the profession has not realized it yet.]]]
[:['-- Bertrand Meyer (see __Meyer97__ page 400)]]
This library implements
[@http://en.wikipedia.org/wiki/Design_by_contract Contract Programming] (a.k.a., Design by Contract, DbC)
[footnote
Design by Contract (DbC) is a registered trademark of [@http://en.wikipedia.org/wiki/Eiffel_Software Eiffel Software] and it was first introduced by the Eiffel programming language (see __Meyer97__).
]
for the C++ programming language.
All Contract Programming features are supported by this library: subcontracting, class invariants, postconditions (with old and return values), preconditions, customizable actions on assertion failure, optional assertion compilation, disable assertion checking while already checking other assertions, etc.
[include introduction.qbk]
[include getting_started.qbk]
[include contract_programming_overview.qbk]
[include tutorial.qbk]
[include advanced_topics.qbk]
[include examples.qbk]
[/ xinclude reference.xml]
[include release_notes.qbk]
[include bibliography.qbk]
[include acknowledgments.qbk]

215
doc/qbk/contract_programming_overview.qbk → doc/contract_programming_overview.qbk
View File

@ -4,13 +4,13 @@
[:['["It is absurd to make elaborate security checks on debugging runs, when no trust is put in the results, and then remove them in production runs, when an erroneous result could be expensive or disastrous. What would we think of a sailing enthusiast who wears his life-jacket when training on dry land but takes it off as soon as he goes to sea?]]]
[:['-- Charles Antony Richard Hoare (see __Hoare73__)]]
This section gives an overview of Contract Programming (see __Meyer97__, __Mitchell02__, and __N1613__ for a detailed introduction to Contract Programming).
Readers that already have a basic understanding of Contract Programming can skip this section and come back to it after reading the __Tutorial__ section.
This section gives an overview of Contract Programming (see __Meyer97__, __Mitchell02__, and __N1613__ for a more detailed introduction to Contract Programming).
Readers that already have a basic understanding of Contract Programming can skip this section and come back to it after reading the __Tutorial__.
[note
The objective of this library is /not/ to convince programmers to use Contract Programming.
It is assumed that programmes understand the benefits and trade-offs associated with Contract Programming and they have already decided to use this methodology to code program specifications.
Then, this library aims to be the best Contract Programming library for C++.
Then, this library aims to be the best and more complete Contract Programming library for C++.
]
[section Assertions]
@ -20,9 +20,9 @@ Contract Programming is characterized by the following assertion mechanisms:
# Preconditions: These are logical conditions that programmers expect to be true when the function is called (e.g., to check constraints on the function arguments).
# Postconditions: These are logical conditions that programmers expect to be true when the function exits without throwing an exception (e.g., to check the result and any side effect that a function might have).
Postconditions can usually access the function return value (for non-void functions) and /old values/ that expressions had before the function body was executed.
# Class invariants: These are logical conditions that programmers expect to be true after the constructor exits without throwing an exception, before and after the execution of every public non-static member function (even if they throw exceptions), before the destructor is executed and if the destructor throws an exception (e.g, class invariants can define valid states for all objects of a class).
It is possible to specify a different set of class invariants for volatile member functions, but these /volatile class invariants/ are assumed to be the same as class invariants unless differently specified.
It is also possible to specify /static class invariants/ which are excepted to be true before and after the execution of any public member function (even if static), of constructors, and of the destructor (even when the destructor does not throw an exception).
# Class invariants: These are logical conditions that programmers expect to be true after the constructor exits without throwing an exception, before and after the execution of every public non-static member function (even if they throw exceptions), before the destructor is executed and if the destructor throws an exception (e.g, class invariants can define valid states for all objects of a given class).
It is possible to specify a different set of class invariants for volatile member functions, namely /volatile class invariants/.
It is also possible to specify /static class invariants/ which are excepted to be true before and after the execution of any constructor, destructor (even if it does not throw an exception), and public member function (even if static).
[footnote
*Rationale.*
Static and volatile class invariants were first introduced by this library to reflect the fact that C++ supports both static and volatile member functions.
@ -30,25 +30,27 @@ Static and volatile class invariants are not part of __N1962__.
]
# Subcontracting: Subcontracting is defined according to the __substitution_principle__ and it indicates that preconditions cannot be strengthen, while postconditions and class invariants cannot be weaken.
Furthermore, it is a common requirement for Contract Programming to automatically disable other contracts while a contract assertions is being checked (in order to avoid infinite recursion while checking contract assertions).
Furthermore, it is a common requirement for Contract Programming to automatically disable other contracts while a contract assertions is already being checked (in order to avoid infinite recursion while checking contract assertions).
[note
This library implements this requirement but it should be noted that, in order to globally disable assertions while checking another assertion, some type of global variable needs to be used.
In multi-threaded programs, the [macroref BOOST_CONTRACT_CONFIG_THREAD_SAFE] configuration macro can be defined to protect such a global variable from race conditions, but this will effectively introduce a global lock in the program.
This library implements this requirement but it should be noted that, in order to globally disable assertions while checking another assertion, some type of global variable needs to be used by the library implementation.
This library will automatically protect such a global variable from race conditions in multi-threated programs, but this will effectively introduce a global lock in the program (the [macroref BOOST_CONTRACT_DISABLE_THREADS] macro can be defined to disable this global lock but at the risk of incurring in race conditions).
]
In general, it is recommended to specify different contract conditions using separate assertion statements and not to group them together into a single condition using logical operators (`&&`, `||`, etc.).
This is because if contract conditions are programmed together using a single assertion then it will not be clear which condition actually failed in case the assertion is evaluated to be false at run-time.
A limited form of Contract Programming is the use of the C-style `assert` macro.
Using `assert` is common practice for many programmers but it suffers of the following limitations (that are instead overcome by Contract Programming):
Using `assert` is common practice for many programmers but it suffers of the following limitations:
* `assert` does not distinguish between preconditions and postconditions.
In well-tested production code, postconditions can usually be disabled trusting the correctness of the implementation while preconditions might still need to remain enabled because of possible changes in the calling code.
In well-tested production code, postconditions can usually be disabled trusting the correctness of the implementation while preconditions might still need to remain enabled because of possible changes in the calling code (e.g., postconditions of a given library could be disabled after testing while its preconditions can be kept enabled given the library cannot predict the evolution of user code that will be calling it).
Using `assert` it is not possible to selectively disable only postconditions and all assertions must be disabled at once.
* `assert` requires to manually program extra code to check class invariants (e.g., extra member functions and try blocks).
* `assert` does not support subcontracting.
* `assert` calls are usually scattered throughout the implementation thus the asserted conditions are not immediately visible in their entirety to programmers.
* `assert` calls are usually scattered throughout the implementation thus the asserted conditions are not immediately visible in their entirety by programmers.
These limitation do not apply to Contract Programming instead.
[endsect]
@ -59,20 +61,20 @@ Using `assert` it is not possible to selectively disable only postconditions and
The main use of Contract Programming is to improve software quality.
__Meyer97__ discusses how Contract Programming can be used as the basic tool to write ["correct] software.
__Stroustrup97__ discusses the key importance of class invariants plus advantages and disadvantages of preconditions and postconditions.
The following is a short summary of the benefits associated with Contract Programming mainly taken from __N1613__:
The following is a short summary of the benefits associated with Contract Programming inspired mainly by __N1613__:
# Preconditions and postconditions:
Using function preconditions and postconditions, programmers can give a precise semantic description of what a function requires at its entry and what it ensures under its exit (if it does not throw an exception).
In particular, using postcondition old values, Contract Programming provides a mechanism that allows programmers to compare values of an expression before and after the function body execution.
This mechanism is powerful enough to enable programmers to express many constraints within the code, constraints that would otherwise have to be captured at best only informally in the documentation.
This mechanism is powerful enough to enable programmers to express many correctness constraints within the code itself, constraints that would otherwise have to be captured at best only informally by documentation.
# Class invariants:
Using class invariants, programmers can describe what to expect from a class and the logic dependencies between the class members.
It is the job of the constructor to ensure that the class invariants are satisfied when the object is first created.
Then the implementation of the member functions can be largely simplified as they can be written knowing that the class invariants are satisfied because Contract Programing checks them before and after the execution of every public member function.
Finally, the destructor makes sure that the class invariants hold for the entire life of the object, checking the class invariants one last time before the object is destructed.
Finally, the destructor makes sure that the class invariants held for the entire life of the object checking the class invariants one last time before the object is destructed.
# Self-documenting code:
Contracts are part of the source code, they are checked at run-time so they are always up-to-date with the code itself.
Therefore the specifications, as documented by the contracts, can be trusted to always be up-to-date with the implementation.
Therefore program specifications, as documented by the contracts, can be trusted to always be up-to-date with the implementation.
# Easier debugging:
Contract Programming can provide a powerful debugging facility because, if contracts are well written, bugs will cause contract assertions to fail exactly where the problem first occurs instead than at some later stage of the program execution in an apparently unrelated manner.
Note that a precondition failure points to a bug in the function caller, a postcondition failure points instead to a bug in the function implementation.
@ -83,15 +85,15 @@ For example, consider the validation of a result in postconditions.
Validating the return value might seem redundant, but in this case we actually want that redundancy.
When programmers write a function, there is a certain probability that they make a mistake in implementing the function body.
When programmers specify the result of the function in the postconditions, there is also a certain probability that they make a mistake in writing the contract.
However, the probability that programmers make a mistake twice (in both the body /and/ the contract) is lower than the probability that the mistake is made just once (in either the body or the contract).
However, the probability that programmers make a mistake twice (in both the body /and/ the contract) is in general lower than the probability that the mistake is made just once (in either the body or the contract).
]
# Easier testing:
Contract Programming facilitates testing because a contract naturally specifies what a test should check.
For example, preconditions of a function state which inputs cause the function to fail and postconditions state which outputs are produced by the function on successful exit.
Obviously, Contract Programming should be seen as a tool to complement (and not to replace) testing.
(That said, Contract Programming should be seen as a tool to complement (and obviously not to replace) testing.)
# Formal design:
Contract Programming can serve to reduce the gap between designers and programmers by providing a precise and unambiguous specification language.
Moreover, contracts can make code reviews easier.
Moreover, contracts can make code reviews easier by clarifying some of the semantics and usage of the code.
# Formalized inheritance:
Contract Programming formalizes the virtual function overriding mechanism using subcontracting as justified by the __substitution_principle__.
This keeps the base class programmers in control as overriding functions always have to fully satisfy the base class contracts.
@ -100,25 +102,25 @@ Contract Programming assertions can replace [@http://en.wikipedia.org/wiki/Defen
[heading Costs]
In general, Contract Programming benefits come to the cost of performance as discussed in detail by both __Stroustrup97__ and __Meyer97__.
However, while performance trade-offs should be carefully considered depending on the specific application domain, software quality cannot be sacrificed: It is difficult to see value in software that quickly and efficiently provides the incorrect result.
In general, Contract Programming benefits come at the cost of performance as discussed in detail by both __Stroustrup97__ and __Meyer97__.
However, while performance trade-offs should be carefully considered depending on the specific application domain, software quality cannot be sacrificed: it is difficult to see value in software that quickly and efficiently provides incorrect results.
The run-time performances are negatively impacted by Contract Programming mainly because of extra time require to:
# Check the asserted conditions.
# Call additional functions that specify preconditions, postconditions, class invariants, etc.
# Copy old values and return values when these are used in postconditions.
# Copy old and return values when these are used in postconditions.
To mitigate the run-time performance impact, programmers can selectively disable run-time checking of some of the contract assertions.
Programmers will have to decide based on the performance trade-offs required by their applications, but a reasonable approach often is to:
* Always write contracts to clarify the semantics of the design embedding the specifications directly in the code and making the code self-documenting.
* Enable precondition, postcondition, and class invariant checking during initial testing.
* Enable only precondition (and possibly class invariant) checking during release testing and for the final release (see also [macroref BOOST_CONTRACT_CONFIG_NO_PRECONDITIONS], [macroref BOOST_CONTRACT_CONFIG_NO_POSTCONDITIONS], and [macroref BOOST_CONTRACT_CONFIG_NO_INVARIANTS]).
* Enable preconditions, postconditions, and class invariants checking during initial testing.
* Enable only preconditions (and possibly class invariants) checking during release testing and for the final release (see __Disable_Contract_Checking__).
This approach is usually reasonable because in well-tested production code, validating the function body implementation using postconditions and class invariants is rarely needed since the function has shown itself to be ["correct] during testing.
This approach is usually reasonable because in well-tested production code, validating the function body implementation using postconditions (and often class invariants) is rarely needed since the function has shown itself to be ["correct] during testing.
On the other hand, checking function arguments using preconditions is always needed because of changes that can be made to the calling code (without having to necessarily re-test and re-released to called code).
Furthermore, postconditions are usually computationally more expensive to check (see the __Assertion_Complexity__ section for a mechanism to selectively tag and disable assertions based on their computational complexity).
Furthermore, postconditions are usually computationally more expensive to check than preconditions and class invariants.
[endsect]
@ -126,7 +128,7 @@ Furthermore, postconditions are usually computationally more expensive to check
[heading Free Functions]
A call to a /free function/ (i.e., a function that is not a member function) with contracts executes the following steps (see also [funcref boost::contract::function]):
A call to a non-member function with contracts executes the following steps (see also [funcref boost::contract::function]):
# Check function preconditions.
# Execute the function body.
@ -135,9 +137,9 @@ A call to a /free function/ (i.e., a function that is not a member function) wit
[heading Private and Protected Member Functions]
In Contract Programming, Private and protected member functions do not have to satisfy the class invariants (because these functions are considered part of the implementation of the class).
Furthermore, the __substitution_principle__ does not apply to private and protected member functions (because these functions are not accessible to the user at calling site where the __substitution_principle__ applies).
Furthermore, the __substitution_principle__ does not apply to private and protected member functions (because these functions are not accessible to the user at the calling site where the __substitution_principle__ applies).
Therefore, calls to private and protected member functions with contracts execute the same steps the ones indicated for free functions above (checking only preconditions and postconditions, but without checking class invariants and without subcontracting).
Therefore, calls to private and protected member functions with contracts execute the same steps as the ones indicated for non-member functions above (checking only preconditions and postconditions, but without checking class invariants and without subcontracting).
[endsect]
@ -146,31 +148,31 @@ Therefore, calls to private and protected member functions with contracts execut
[heading Overriding Public Member Functions]
Let's consider a public member function in a derived class that is overriding public virtual functions declared in a number of its base classes (because of multiple inheritance, the function could override from more than one base class).
We refer to the function in the derived class as the /overriding/ function, and to the functions being overridden in the different base classes as the /overridden/ functions.
We refer to the function in the derived class as the /overriding function/, and to the functions being overridden in the different base classes as the /overridden functions/.
Then a call to the overriding public member function with contracts executes the following steps (see also [funcref boost::contract::public_function]):
# Check static class invariants __AND__ non-static class invariants for all overridden bases, __AND__ then check the derived class static __AND__ non-static invariants.
# Check preconditions of overridden public member functions from all overridden bases in __OR__ with each other, __OR__ else check the overriding function preconditions in the derived class.
# Executed the function body.
# Executed the overriding function body.
# Check static class invariants __AND__ non-static class invariants for all overridden bases, __AND__ then check the derived class static __AND__ non-static invariants (even if the body threw an exception).
# If the body did not throw an exception, check postconditions of overridden public member functions from all overridden bases in __AND__ with each other, __AND__ then check the overriding function postconditions in the derived class.
Volatile member functions check static class invariants __AND__ non-static /volatile/ class invariants instead.
Volatile member functions check static class invariants __AND__ volatile class invariants instead.
Preconditions and postconditions of volatile member functions and volatile class invariants access the object as `volatile`.
[note
[#logic_and_anchor] [#logic_or_anchor]
[#and_anchor] [#or_anchor]
In this documentation __AND__ and __OR__ indicate the logic /and/ and /or/ operations evaluated in /short-circuit/.
For example: `p` __AND__ `q` is true if and only if both `p` and `q` are true, but `q` is never evaluated when `p` is false; `p` __OR__ `q` is true if and only if either `p` or `q` are true, but `q` is never evaluated when `p` is true.
]
When subcontracting, overridden functions are searched deeply in the public branches of the inheritance tree (i.e., not just the derived class's direct public parents are inspected, but also all its public grandparents, etc.).
In case of multiple inheritance this search extends widely to all multiple public base classes following their order of declaration in the derived class inheritance list (as usual in C++, this search could result in overriding multiple base functions and therefore in subcontracting from multiple public base classes).
When subcontracting, overridden functions are searched (at compile-time) deeply in the public branches of the inheritance tree (i.e., not just the derived class's direct public parents are inspected, but also all its public grandparents, etc.).
In case of multiple inheritance this search extends widely to all multiple public base classes following their order of declaration in the derived class inheritance list (as usual in C++, this search could result in multiple overridden functions and therefore in subcontracting from multiple public base classes).
Note that only public base classes are considered for subcontracting (because private and protected base classes are not accessible to the user at the calling site where the __substitution_principle__ applies).
Class invariants are checked before preconditions and postconditions so that programming of precondition and postcondition assertions can be simplified by assuming that class invariants are satisfied (e.g., if class invariants assert that a pointer cannot be null then preconditions and postconditions can safety dereference that pointer without additional checking).
Similarly, subcontracting checks contracts of public base classes before checking the derived class contracts so that programming of derived class contract assertions can be simplified by assuming that public base class contracts are satisfied.
Class invariants are checked before preconditions and postconditions so programming of precondition and postcondition assertions can be simplified by assuming that class invariants are satisfied already (e.g., if class invariants assert that a pointer cannot be null then preconditions and postconditions can safety dereference that pointer without additional checking).
Similarly, subcontracting checks contracts of public base classes before checking the derived class contracts so programming derived class contract assertions can be simplified by assuming that public base class contracts are satisfied already.
[heading Non-Overriding Public Member Functions]
@ -182,7 +184,7 @@ A call to a public non-static member function with contracts but that is not ove
# Check the class static __AND__ non-static invariants (even if the body threw an exception, but none of the invariants from base classes).
# If the body did not throw an exception, check function postconditions (but none of the postconditions from functions in base classes).
Volatile member functions check static class invariants __AND__ non-static /volatile/ class invariants instead.
Volatile member functions check static class invariants __AND__ volatile class invariants instead.
Preconditions and postconditions of volatile member functions and volatile class invariants access the object as `volatile`.
Class invariants are checked because this function is part of the class public API.
@ -192,38 +194,36 @@ However, none of the contracts of the base classes are checked because this func
A call to a public static member function with contracts executes the following steps (see also [funcref boost::contract::public_function]):
# Check static class invariants (but not the non-static invariants and none of the invariants base classes).
# Check static class invariants (but not the non-static invariants and none of the invariants from base classes).
# Check function preconditions (but none of the preconditions from function in base classes).
# Executed the function body.
# Check static class invariants (even if the body threw an exception, but not the non-static invariants and none of the invariants from base classes).
# If the body did not throw an exception, check function postconditions (but none of the postconditions from functions in base classes).
Class invariants are checked because this function is part of the class public API, but only static class invariants can be checked (because this is a static function so it cannot access the object that would instead be required to check non-static class invariants).
Furthermore, static functions cannot override any function so the __substitution_principle__ does not apply to them and they do not subcontract.
Furthermore, static functions cannot override any function so the __substitution_principle__ does not apply and they do not subcontract.
Preconditions and postconditions of static member functions and static class invariants cannot access the object (because static member functions cannot access the object).
Preconditions, postconditions, and class invariants of static member functions cannot access the object (because they are `static` members).
[endsect]
[section Constructor Calls]
A call to a constructor with contracts executes the following steps (see also [funcref boost::contract::constructor] and [classref boost::contract::constructor_precondition]):
A call to a constructor with contracts executes the following steps (see also [classref boost::contract::constructor_precondition] and [funcref boost::contract::constructor]):
# Check the constructor preconditions (but these cannot access the object because the object is not constructed yet).
# Check constructor preconditions (but these cannot access the object because the object is not constructed yet).
# Execute the constructor member initialization list (if present).
# Construct any base class (public or not) according with C++ construction mechanism and also check the contracts of these base constructors (according with steps similar to the ones listed here).
# Check the static class invariants (but not the non-static class invariants, because the object is not constructed yet).
# Check static class invariants (but not the non-static or volatile class invariants, because the object is not constructed yet).
# Execute the constructor body.
# Check the static class invariants (even if the body threw an exception).
# Check static class invariants (even if the body threw an exception).
# If the body did not throw an exception:
# Check the non-static class invariants (because the object is now successfully constructed).
# Check the constructor postconditions (but these cannot access the object old value because there was no object before the execution of the constructor body).
# Check non-static __AND__ volatile class invariants (because the object is now successfully constructed).
# Check constructor postconditions (but these cannot access the object old value because there was no object before the execution of the constructor body).
The object is never volatile within constructors so constructors do not check volatile class invariants.
Constructor preconditions are checked before executing the member initialization list so that programming these initializations can be simplified assuming the constructor preconditions are satisfied (e.g., constructor arguments can be validated by the constructor preconditions before they are used to initialize bases and data members).
Constructor preconditions are checked before executing the member initialization list so that programming of these initializations can be simplified by assuming the constructor preconditions are satisfied (e.g., constructor arguments can be validated by the constructor preconditions before they are used to initialize bases and data members).
As indicated in the steps above, C++ object construction mechanism will automatically check base class contracts when these bases are initialized.
As indicated in the steps above, C++ object construction mechanism will automatically check base class contracts when these bases are initialized (no explicit subcontracting behaviour is required).
[endsect]
@ -231,25 +231,23 @@ As indicated in the steps above, C++ object construction mechanism will automati
A call to a destructor with contracts executes the following steps (see also [funcref boost::contract::destructor]):
# Check static class invariants __AND__ non-static class invariants.
# Check static class invariants __AND__ non-static __AND__ volatile class invariants.
# Execute the destructor body (destructors have no parameters and they can be called at any time after object construction so they have no preconditions).
# Check the static class invariants (even if the body threw an exception).
# If the body threw an exception, check the non-static class invariants (because the object was not successfully destructed so it still exists and should satisfy its invariants).
# Check static class invariants (even if the body threw an exception).
# If the body threw an exception, check non-static class invariants (because the object was not successfully destructed so it still exists and should satisfy its invariants).
# If the body did not throw an exception:
# Check the destructor postconditions (but these can only access the class' static members because there is no object after successful execution of the destructor body).
# Check destructor postconditions (but these can only access the class static members because there is no object after successful execution of the destructor body).
[footnote
None of the Contract Programming references that the authors have studied propose postconditions for destructor (neither __N1962__ nor __Meyer97__, but __Eiffel__ has no static data member).
However, in principle there could be uses cases for destructor postconditions (e.g., a class that counts object instances could use destructor postconditions to assert that an instance counter stored in a static data member is decreased of `1` because the object has been destructed) so this library support postconditions for destructors.
Of course, after destructor body execution there is no object anymore so destructor postconditions should only be allowed to access the class' static members.
None of the Contract Programming references that the authors have studied propose postconditions for destructor (neither __N1962__ nor __Meyer97__ (but Eiffel does not support static data members also)).
However, in principle there could be uses cases for destructor postconditions (e.g., a class that counts object instances could use destructor postconditions to assert that an instance counter stored in a static data member is decreased by `1` because the object has been destructed) so this library supports postconditions for destructors.
Of course, after destructor body execution there is no object anymore so destructor postconditions should only access the class' static members.
]
# Destroy any base class (public or not) according with C++ destruction mechanism and also check the contracts of these base destructors (according with steps similar to the ones listed here).
The object is never volatile within destructors so destructors do not check volatile class invariants.
As indicated in the steps above, C++ object destruction mechanism will automatically check base class contracts when the destructor exits without throwing an exception.
As indicated in the steps above, C++ object destruction mechanism will automatically check base class contracts when the destructor exits without throwing an exception (no explicit subcontracting behaviour is required).
[note
Given that C++ allows destructors to throw, this library handles the cases when destructor bodies throw exceptions.
Given that C++ allows destructors to throw, this library handles the cases when destructor bodies throw exceptions as indicated above.
However, in order to comply with STL exception safety guarantees and good C++ programming practices, users should program destructor bodies to never throw.
]
@ -260,11 +258,11 @@ However, in order to comply with STL exception safety guarantees and good C++ pr
Contracts are only responsible to check the program state in oder to ensure its compliance with the specifications.
Therefore, contracts should only have access to the object, function arguments, function return value, old values, and all other program variables in `const` context (via `const&`, `const* const`, etc.).
Whenever possible (e.g., class invariants and postcondition old values), this library enforces this constant-correctness constraint at compile-time.
However, this library cannot automatically enforce this constraint at compile-time for all contract assertions.
It is the responsibility of the users to program assertions that do /not/ change program variables (the same limitation exists with the C-style `assert` mechanism).
Whenever possible (e.g., class invariants and postcondition old values), this library automatically enforces this constant-correctness constraint at compile-time using `const`.
However, this library cannot automatically enforce this constraint in all cases (e.g., for preconditions and postconditions of mutable member functions, for global variables, etc.).
Ultimately, it is the responsibility of the users to program assertions that do /not/ change program variables (the same limitation exists with the C-style `assert` mechanism).
See the __Constant_Correct_Functors__ section for information on how to use this library to always enforce the constant-correctness constraint at compile-time (but these methods require a significant amount of boiler-plate code, so they are not recommended).
See __No_Lambda_Functions__ for information on how to use this library to always enforce the constant-correctness constraint at compile-time (but these methods require a significant amount of boiler-plate code to be programmed manually so they are not recommended).
[endsect]
@ -274,25 +272,25 @@ Contracts are part of the program specification and not of its implementation.
Therefore, contracts should ideally be programmed within C++ declarations, and not within definitions.
In general, this library cannot satisfy this requirement but even when the contracts are programmed together with the body in the function definition, it is still very easy for users to identify and read just the contract portion of the function definition (because that must always appear at the very top of the function code).
See the __Separating_Body_Implementation__ section for information on how to separate contract specification from body implementation at the cost of programming one extra function (for applications were this is truly important).
See __Separate_Body_Implementation__ for information on how to separate contract specification from body implementation at the cost of programming an extra function (for applications were this requirement is truly important).
Furthermore, contracts are most useful when they assert conditions only using public members. In most cases, the need of using non-public members to check contracts indicates an error in the design of the class.
Furthermore, contracts are most useful when they assert conditions only using public members (in most cases, the need of using non-public members to check contracts indicates an error in the design of the class).
For example, the caller of a public member function cannot in general make sure that the function preconditions are satisfied if these preconditions use private members that are not accessible by the caller (therefore, a failure in the preconditions will not necessarily indicate a bug in the caller given that the caller was not able to fully check the preconditions before calling the member function).
However, given that C++ provides programmers ways around access level restrictions (`friend`, function pointers, etc.), this library leaves it up to the programmers to make sure that only public members are used in contract assertions (__N1962__ follows the same approach not forcing contracts to only use public members, __Eiffel__ instead generates a compiler error if preconditions use non-public members).
For example, the caller of a public member function cannot in general make sure that the function preconditions are satisfied if the precondition assertions use private members that are not callable by the caller (therefore, a failure in the preconditions will not necessarily indicate a bug in the caller given that the caller was made unable to fully check the preconditions in the first place).
However, given that C++ provides programmers ways around access level restrictions (`friend`, function pointers, etc.), this library leaves it up to the programmers to make sure that only public members are used in contract assertions (__N1962__ follows the same approach not restricting contracts to only use public members, Eiffel instead generates a compiler error if precondition assertions use non-public members).
[footnote
*Rationale.*
In theory, if C++ [@http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#45 defect 45] did not get fixed, this library could have been used in a way that generated a compile-time error for preconditions that use non-public members (but even in that case at the expense of programmers writing extra boiler-plate code).
In theory, if C++ [@http://www.open-std.org/jtc1/sc22/wg21/docs/cwg_defects.html#45 defect 45] did not get fixed, this library could have been implemented in a way that generates a compile-time error when precondition assertions use non-public members (but still at the expense of programmers writing extra boiler-plate code).
]
[endsect]
[section On Contract Failure]
If preconditions, postconditions, or class invariants throw an exception or their assertions are checked to be false at run-time then special failure handler functions are automatically called by this library.
If either preconditions, postconditions, or class invariants throw exceptions or their assertions are checked to be false at run-time then specific failure handler functions are automatically invoked by this library.
By default, these failure handler functions print a text message to the standard error `std::cerr` (with detailed information about the failure) and they terminate the program calling `std::terminate`.
However, user-defined failure handlers can be programmed to take any other action (throw an exception, exit the program with an error code, etc.) using [funcref boost::contract::set_precondition_failed], [funcref boost::contract::set_postcondition_failed], [funcref boost::contract::set_invariant_failed], etc. (see the __Contract_Failure_Handlers__ section for an example).
By default, these failure handler functions print a text message to the standard error `std::cerr` (with detailed information about the failure) and then terminate the program calling `std::terminate`.
However, using [funcref boost::contract::set_precondition_failure], [funcref boost::contract::set_postcondition_failure], [funcref boost::contract::set_invariant_failure], etc. programmers can define their own failure handler functions that can take any desired action (throw an exception, exit the program with an error code, etc., see __Throw_on_Failure__).
[footnote
*Rationale.*
This customizable failure handling mechanism is similar to the one used by `std::terminate` and also proposed by __N1962__.
@ -302,13 +300,13 @@ This customizable failure handling mechanism is similar to the one used by `std:
[section Features]
The Contract Programming features supported by this library are largely based on __N1962__ and on the __Eiffel__ programming language (see __Meyer97__).
The Contract Programming features supported by this library are largely based on __N1962__ and on the Eiffel programming language.
The following table compares this library features with the __N1962__ proposal for adding Contract Programming to the C++ standard,
[footnote
The __N1962__ was unfortunately rejected because the standard committee did not considered important to add Contract Programming to the core language (the __N1962__ proposal itself is sound).
The __N1962__ was unfortunately rejected because the standard committee did not considered important to add Contract Programming to the core language (but the __N1962__ proposal itself is sound).
In any case, this library will allow C++ programmers to still use Contract Programming even if the standard committee never decides to add it as a language feature.
]
the __Eiffel__ programming language (see __Meyer97__), and the __D__ programming language (see __Bright04__).
the Eiffel programming language (see __Meyer97__), and the D programming language (see __Bright04__).
[table
[
@ -322,21 +320,21 @@ the __Eiffel__ programming language (see __Meyer97__), and the __D__ programming
[
Specifiers: `precondition`, `postcondition`, `invariant`, `static_invariant`, and `base_types`.
(These last 3 specifiers appear in user-defined classes so their names can be changed using [macroref BOOST_CONTRACT_CONFIG_INVARIANT], [macroref BOOST_CONTRACT_CONFIG_STATIC_INVARIANT], and [macroref BOOST_CONTRACT_CONFIG_BASE_TYPES] respectively to avoid name clashes in user code.)
(The last three specifiers appear in user code so their names can be changed using [macroref BOOST_CONTRACT_INVARIANT], [macroref BOOST_CONTRACT_STATIC_INVARIANT], and [macroref BOOST_CONTRACT_BASE_TYPEDEF] macros respectively to avoid name clashes in user code.)
]
[Keywords: `precondition`, `postcondition`, `oldof`, and `invariant`.]
[Keywords: =require=, =require else=, =ensure=, =ensure then=, =old=, =result=, =do=, and =invariant=.]
[Keywords: =in=, =out=, =assert=, and =invariant=.]
][
[['On contract failure]]
[Call `std::terminate` (but can be customized to throw exceptions, exit with an error code, etc.).]
[Print an error to `std::cerr` and call `std::terminate` (but can be customized to throw exceptions, exit with an error code, etc.).]
[Call `std::terminate` (but can be customized to throw exceptions, exit with an error code, etc.).]
[Throw exceptions.]
[Throw exceptions.]
][
[['Result value in postconditions]]
[Yes, captured by or passed as a parameter to (for virtual functions) the postcondition functor.]
[Yes, `postcondition (`[^['result-variable-name]]`)`.]
[Yes, `postcondition(`[^['result-variable-name]]`)`.]
[Yes, =result= keyword.]
[No.]
][
@ -348,21 +346,21 @@ Specifiers: `precondition`, `postcondition`, `invariant`, `static_invariant`, an
][
[['Class invariants]]
[
Checked at constructor exit, at destructor entry, and at public member function entry, exit, and throw.
Checked at constructor exit, at destructor entry and throw, and at public member function entry, exit, and throw.
Same for volatile class invariants.
Static class invariants checked at entry and exit of constructor, destructor, and any (also `static`) public member function.
]
[
Checked at constructor exit, at destructor entry, and at public member function entry, exit, and throw.
Checked at constructor exit, at destructor entry and throw, and at public member function entry, exit, and throw.
Volatile and static class invariants not supported.
]
[
Checked at constructor exit, and around public member functions.
Volatile and static class invariants do not apply to __Eiffel__.
(Volatile and static class invariants do not apply to Eiffel.)
]
[
Checked at constructor exit, at destructor entry, and around public member functions.
Volatile and static class invariants not supported (`volatile` was deprecated all together from __D__).
Volatile and static class invariants not supported (`volatile` was deprecated all together in D).
]
][
[['Subcontracting]]
@ -374,9 +372,9 @@ Yes, also support subcontracting for multiple inheritance. Only base classes can
[footnote
*Rationale.*
The authors of __N1962__ decided to forbid derived classes from subcontracting preconditions because they found such a feature rarely if ever used (see [@http://lists.boost.org/Archives/boost/2010/04/164862.php Re: \[boost\] \[contract\] diff n1962]).
Still, it should be noted that even in __N1962__ if a derived class overrides two functions with preconditions coming from two different base classes via multiple inheritance, the overriding function contract will check preconditions from its two base function in __OR__ (so even in __N1962__ preconditions can actually be subcontracted by the derived class when multiple inheritance is used).
Still, it should be noted that even in __N1962__ if a derived class overrides two functions with preconditions coming from two different base classes via multiple inheritance, the overriding function contract will check preconditions from its two base function in __OR__ (so even in __N1962__ preconditions can indirectly be subcontracted by the derived class when multiple inheritance is used).
The authors of this library found that confusing about __N1962__.
Furthermore, subcontracting preconditions is soundly defined by the __substitution_principle__ and it is supported by __Eiffel__ so this library allows to subcontract preconditions (users can alway avoid using such a feature if they have no need for it).
Furthermore, subcontracting preconditions is soundly defined by the __substitution_principle__ so this library allows to subcontract preconditions as Eiffel does (users can alway avoid using such a feature if they have no need for it).
(This is essentially the only feature on which this library deliberately differ from __N1962__.)
]
]
@ -390,34 +388,35 @@ Furthermore, subcontracting preconditions is soundly defined by the __substituti
[No (but planned).]
][
[['Arbitrary code in contracts]]
[Yes (but users are generally recommended to only program assertions using [macroref BOOST_CONTRACT_ASSERT] and if-guard statements within contracts, so to avoid introducing bugs and expensive code in contracts, and also to only use public functions to program preconditions).]
[Yes (but users are generally recommended to only program assertions using [macroref BOOST_CONTRACT_ASSERT] and if-guard statements within contracts to avoid introducing bugs and expensive code in contracts, and also to only use public functions to program preconditions).]
[No, assertions only.]
[No, assertions only. In addition only public members can be used in preconditions.]
[Yes.]
][
[['Constant-correctness]]
[Enforced only for class invariants and old values (making also preconditions and postconditions constant-correct is possible but requires users to program a fare amount of boiler-plate code, see also the __Constant_Correct_Functors__ section).]
[Enforced only for class invariants and old values (making also preconditions and postconditions constant-correct is possible but requires users to program a fare amount of boiler-plate code, see __No_Lambda_Functions__).]
[Yes.]
[Yes.]
[No.]
][
[['Function code ordering]]
[Preconditions and postconditions in any order, but always before body.]
[Preconditions, postconditions, body.]
[Preconditions, postconditions, body.]
[Preconditions, body, postconditions.]
[Preconditions, postconditions, body.]
][
[['Disable assertion checking within assertions checking (to avoid infinite recursion when checking contracts)]]
[
Yes (but use [macroref BOOST_CONTRACT_CONFIG_PRECONDITIONS_DISABLE_NO_ASSERTION] to disable no assertion while checking preconditions).
Yes, but use [macroref BOOST_CONTRACT_PRECONDITIONS_DISABLE_NO_ASSERTION] to disable no assertion while checking preconditions.
[footnote
*Rationale.*
Theoretically, it can be shown that an incorrect argument might be passed to the function body when assertion checking is disabled while checking preconditions (see [@http://lists.boost.org/Archives/boost/2010/04/164862.php Re: \[boost\] \[contract\] diff n1962]).
Therefore, __N1962__ does not disable any assertion while checking preconditions.
However, that makes it possible to have infinite recursion while checking preconditions, plus __Eiffel__ disables assertion checking also while checking preconditions.
Therefore, this library by default disables assertion checking also while checking preconditions, but it also provides the [macroref BOOST_CONTRACT_CONFIG_PRECONDITIONS_DISABLE_NO_ASSERTION] configuration macro so users can change that behaviour if they need to.
However, that makes it possible to have infinite recursion while checking preconditions, plus Eiffel disables assertion checking also while checking preconditions.
Therefore, this library by default disables assertion checking also while checking preconditions, but it also provides the [macroref BOOST_CONTRACT_PRECONDITIONS_DISABLE_NO_ASSERTION] configuration macro so users can change this behaviour if needed.
]
(In multi-threaded programs this introduces a global lock, see also the [macroref BOOST_CONTRACT_DISABLE_THREADS] macro.)
]
Use [macroref BOOST_CONTRACT_CONFIG_THREAD_SAFE] to make the implementation of this feature thread-safe in multi-threaded programs (but this will introduce a global lock).]
[Yes for class invariants and postconditions, but preconditions disable no assertion.]
[Yes.]
[No.]
@ -427,8 +426,8 @@ Therefore, this library by default disables assertion checking also while checki
Disable nothing.
[footnote
*Rationale.*
Older versions of this library defined a data member in the user class that was automatically used to disable checking of class invariants within nested member function calls (similarly to __Eiffel__).
However, this feature was required by older revisions of __N1962__ but it is no longer required by __N1962__.
Older versions of this library defined a data member in the user class that was automatically used to disable checking of class invariants within nested member function calls (similarly to Eiffel).
This feature was also required by older revisions of __N1962__ but it is no longer required by __N1962__.
Furthermore, in multi-threaded programs this feature would introduce a lock that synchronizes all member functions calls for a given object.
Therefore, this feature was removed in the current revision of this library.
]
@ -439,8 +438,8 @@ Therefore, this feature was removed in the current revision of this library.
][
[['Disable contract checking]]
[
Yes, contract checking can be skipped at run-time by defining any combination of the macros [macroref BOOST_CONTRACT_CONFIG_NO_PRECONDITIONS], [macroref BOOST_CONTRACT_CONFIG_NO_POSTCONDITIONS], and [macroref BOOST_CONTRACT_CONFIG_NO_INVARIANTS].
(Also removing contract code from compiled object code is possible but requires users to program a fare amount of boiler-plate code, see also the __Smaller_Object_Code__ section.)
Yes, contract checking can be skipped at run-time by defining combinations of the [macroref BOOST_CONTRACT_NO_PRECONDITIONS], [macroref BOOST_CONTRACT_NO_POSTCONDITIONS], [macroref BOOST_CONTRACT_NO_INVARIANTS], [macroref BOOST_CONTRACT_NO_ENTRY_INVARIATS], and [macroref BOOST_CONTRACT_NO_EXIT_INVARIANTS] macros.
(Also removing contract code from compiled object code is possible but requires users to program a fare amount of boiler-plate code, see __Disable_Contract_Checking__.)
]
[Yes (contract code also removed from compiled object code).]
[Yes, but only predefined combinations of preconditions, postconditions, and class invariants can be disabled (contract code also removed from compiled object code).]
@ -448,7 +447,7 @@ Yes, contract checking can be skipped at run-time by defining any combination of
]
]
The authors of this library also consulted the following references that implement Contract Programming for C++ (but usually for a somewhat limited subset of the features above) or for other languages (see the __Bibliography__ section for a complete list of all the references consulted in the design and development of this library):
The authors of this library also consulted the following references that implement Contract Programming for C++ (but usually for a somewhat limited subset of the features above) or for other languages (see __Bibliography__ for a complete list of all the references consulted in the design and development of this library):
[table
[ [Reference] [Language] [Notes] ]
@ -456,20 +455,20 @@ The authors of this library also consulted the following references that impleme
The Digital Mars C++ compiler extends C++ adding Contract Programming language support (among many other features).
] ]
[ [__Lindrud04__] [C++] [
This supports class invariants and old values but it does not support subcontracting (plus contracts are specified within definitions instead of declarations and assertions are not constant-correct).
This supports class invariants and old values but it does not support subcontracting (contracts are specified within definitions instead of declarations and assertions are not constant-correct).
] ]
[ [__Tandin04__] [C++] [
Interestingly, these contract macros automatically generate __Doxygen__ documentation
Interestingly, these contract macros automatically generate Doxygen documentation
[footnote
*Rationale.*
Older versions of this library used to automatically generate __Doxygen__ documentation from contract definition macros.
This functionality was abandoned for a number of reasons: This library no longer uses macros to program contracts; The used macros became too complex and the __Doxygen__ preprocessor was no longer able to expand them; The __Doxygen__ documentation was just a repeat of the contract code (so programmers could directly look at contracts in the source code); __Doxygen__ might not necessarily be the C++ documentation tool used by all programmers.
Older versions of this library used to automatically generate Doxygen documentation from contract definition macros.
This functionality was abandoned for a number of reasons: this library no longer uses macros to program contracts; even before that, this library macros became too complex and the Doxygen preprocessor was no longer able to expand them; the Doxygen documentation was just a repeat of the contract code (so programmers could directly look at contracts in the source code); Doxygen might not necessarily be the documentation tool used by all C++ programmers.
]
but old values, class invariants, and subcontracting are not supported (plus contracts are specified within definitions instead of declarations and assertions are not constant-correct).
] ]
[ [__Maley99__] [C++] [
This supports Contract Programming including subcontracting but with some limitations (e.g., programmers need to manually build an inheritance tree using artificial template parameters), it does not use macros but programmers are required to write by hand a significant amount of boiler-plate code.
(The authors have found this work very inspiring when developing the first revisions of this library especially for the attempt to support subcontracting.)
This supports Contract Programming including subcontracting but with limitations (e.g., programmers need to manually build an inheritance tree using artificial template parameters), it does not use macros but programmers are required to write by hand a significant amount of boiler-plate code.
(The authors have found this work very inspiring when developing initial revisions of this library especially for the attempt to support subcontracting.)
] ]
[ [__C2__] [C++] [
This uses an external preprocessing tool (the authors could no longer find this project's code to evaluate it).
@ -495,14 +494,14 @@ This is an Ada-like programming language with support for Contract Programming.
]
Typically, preprocessing tools external to the language work by transforming specially formatted code comments into contract code that is then checked at run-time.
One of this library primary goals was to support Contract Programming entirely /within C++/ and without using any tool external to the standard language.
One of this library primary goals was to support Contract Programming entirely /within C++/ and without using any tool external to the standard language itself.
To the authors' knowledge, this the only library that fully supports all Contract Programming features for C++.
[footnote
Generally speaking, implementing preconditions and postconditions in C++ is not difficult (e.g., using some type of __RAII__ object).
Generally speaking, implementing preconditions and postconditions in C++ is not difficult (e.g., using some type of RAII object).
Implementing postcondition old values is also not too difficult (usually requiring users to copy old values into local variables, but it is somewhat more difficult to ensure such copies are not performed when postconditions are disable).
Most libraries stop here because implementing class invariants already becomes complex.
Then implementing subcontracting requires a significant amount of complexity and it seems to not be properly supported by any other library (especially with multiple inheritance, continuing to correctly copying postcondition old values across all overridden contracts, and reporting correct the result value to the postconditions overridden virtual functions).
Most Contract Programming libraries for C++ stop here because implementing class invariants is already somewhat more involved even if still doable (especially without requiring users to manually invoke an extra function to check invariants).
After that, implementing subcontracting requires a significant amount of complexity and it seems to not be properly supported by any library other than this one (especially including multiple inheritance, correctly copying postcondition old values across all overridden contracts deep in the inheritance tree, and correctly reporting the return value to the postconditions of the overridden virtual functions).
This library supports all of these features instead.
]

0
doc/qbk/examples.qbk → doc/examples.qbk
View File

143
doc/getting_started.qbk Normal file
View File

@ -0,0 +1,143 @@
[/ Copyright (C) 2008-2012 Lorenzo Caminiti ]
[/ Distributed under the Boost Software License, Version 1.0 ]
[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
[/ http://www.boost.org/LICENSE_1_0.txt) ]
[/ Home at http://sourceforge.net/projects/contractpp ]
[section Getting Started]
This section explains how to get oriented to start using this library.
[section This Documentation]
Programmers should be able to start using this library after reading the __Introduction__, __Getting_Started__, and __Tutorial__ sections.
The other sections of this documentation can be consulted at a later point to gain a more in-depth knowledge of the library.
Some footnotes are marked by the word "*Rationale*".
These explain reasons behind decisions made during the design and implementation of this library.
[endsect]
[section Compilers and Platforms]
In general, this library requires a C++ compiler with sound support of SFINAE and other template meta-programming techniques included in the C++03 standard.
This library requires Boost (Boost.Optional, Boost.Thread, Boost.FunctionTypes, Boost.Traits, Boost.MPL, etc.).
It is possible to use this library without C++11 lambda functions but a large amount of boiler-plate code is required to manually program separate functions to specify preconditions and postconditions (so using this library without C++11 lambda functions is not recommended, see __No_Lambda_Functions__).
It is also possible to use this library without C++11 (or C++99) variadic macros by manually programming a small amount of boiler-plate code (see __No_Macros__).
Some parts of this documentation use an operator [^['typeof](...)].
This is just to indicate an operator equivalent to C++11 `decltype` in this documentation.
Internally this library does not actually use type deduction in these cases (because the library already knows the type in question) so C++11 `decltype` and other type-of implementations are not required to compile this library.
This library has been developed and tested with:
* Visual Studio 2015 on Windows (MSVC =cl= version 19.00.23506).
* GCC version 4.9.3 on Cygwin (with C++11 features enabled =-std=c++11=).
* Clang version 3.5.2 on Cygwin (with C++11 features enabled =-std=c++11=).
* Boost C++ libraries version 1.60.0.
[endsect]
[section Code Organization]
Let [^['lib-root]] be the directory under which this library source files have been installed.
This library flies are organized as follows:
[pre
['lib-root/] # Directory where this library files were installed.
build/ # Build files (using Boost.Jam).
doc/ # Documentation (using Boost.QuickBook).
html/ # This documentation (HTML).
example/ # Examples (including those listed in this documentation).
include/
boost/
contract.hpp # Include all headers at once.
contract/ # Header files to be included one-by-one.
core/ # Fundamental headers (usually indirectly included by other headers).
detail/ # Implementation code (should never be included or used directly).
src/ # Library source code to be compiled.
test/ # Tests.
]
All headers required by this library can be included at once by:
#include <boost/contract.hpp>
Alternatively, all =boost/contract/*.hpp= headers are independent from one another and they can be selectively included one-by-one based on the specific functionality of this library being used (this might reduce compilation time).
The =boost/contract/core/*.hpp= headers are not independent from other headers and they do not need to be directly included in user code when one or more =boost/contract/*.hpp= header is included already.
Files in =boost/contract/detail/=, names in the `boost::contract::detail` namespace, names and macros starting with `boost_contract_detail...` and `BOOST_CONTRACT_DETAIL...` (in any namespace, including user's namespaces) are part of this library implementation and should never be used directly in user code.
Names starting with `BOOST_CONTRACT_ERROR...` are used by this library to report compile-time errors (so spotting these names in error messages reported by the compiler might help troubleshooting).
[endsect]
[section Installation and Compilation]
Let [^['lib-root]] be the directory under which this library source files have been installed.
Let [^['boost-root]] be the directory under which Boost source code has been installed and compiled following Boost's documentation (if pre-compiled Boost distributions are used instead, the [^['lib-boost]\/include] and [^['lib-boost]\/stage\/lib] directories below might be replaced by =/usr/include= and =/usr/lib= or similar directories depending on the specific Boost distribution, OS, etc.).
The following steps show how to compile this library as a shared library (a.k.a., Dynamically Linked Library (DLL)) and then compile and run a user program that uses this library (the [@../../example/features/introduction.cpp =introduction.cpp=] program shown in __Introduction__ is used as an example).
Using MSVC on Windows (from a developer command prompt that automatically invokes the correct =vcvarsall.bat=):
[pre
> cd ['lib-root]\build
> cl ['lib-root]\src\contract.cpp \/MDd \/EHs -DBOOST_CONTRACT_DYN_LINK -I ['lib-root]\include -I ['boost-root] /link /DLL /LIBPATH:['boost-root]\stage\lib /out:boost_contract.dll
]
[pre
> cd ['lib-root]\example\features
> cl introduction.cpp \/MDd \/EHs -I ['lib-root]\include -I ['boost-root] /link /LIBPATH:['boost-root]\stage\lib ['lib-root]\build\boost_contract.lib
]
[pre
> set PATH=%PATH%;['lib-root]\build
> introduction
]
Using GCC on Cygwin (and some Linux-like OS):
[pre
$ cd ['lib-root]\/build
$ g++ ['lib-root]\/src\/contract.cpp -std=c++11 -shared -DBOOST_CONTRACT_DYN_LINK -I ['lib-root]\/include -I ['boost-root] ['boost-root]\/stage\/lib\/libboost_system.a -o boost_contract.dll
]
[pre
$ cd ['lib-root]\/example\/features
$ g++ introduction.cpp -std=c++11 -I ['lib-root]\/include -I ['boost-root] ['lib-root]\/build\/boost_contract.dll -o introduction
]
[pre
$ export PATH=$PATH:['lib-root]\/build
$ .\/introduction
]
The above steps also work for Clang using =clang++= instead of =g++=.
Following a convention common to many Boost libraries, this library provides the [macroref BOOST_CONTACT_DYN_LINK] macro to be defined when compiling this library as a shared library instead.
If this macro is not defined, this library will be compiled as a statically linked library.
There is also a [macroref BOOST_CONTRACT_HEADER_ONLY] macro that can be defined when compiling user programs instead of pre-compiling this library separately as either a static or shared library (because this library will then be composed only of header files so it no longer needs to be compiled separately).
[important
When a program is composed of different libraries that in turn use this library, this library will not properly work at run-time unless it is compiled and linked as a shared library defining the [macroref BOOST_CONTRACT_DYN_LINK] macro as shown above.
[footnote
Specifically, this library will not correctly disable contracts while checking other contracts and call the correct user-defined contract failure handlers unless it is compiled as a shared library when it is being used by different libraries part of the same program.
]
]
It should be simple enough for programmers to setup their build environments (BJam, Make, CMake, MSBuild, etc.) to compile this library source code into a shared library and then compile and link user code against it (if that is preferred instead of manually running the compiler as indicated by the steps above).
For example, this library source comes with a set of Boost.Build (BJam) files that can be used to build the library and build and run its tests and examples assuming: Boost was built from source, an environment variable named `BOOST_ROOT` is set to the [^['boost-root]] directory path, and the `bjam` program can be found in the `PATH` environment variable.
The following uses BJam to build and run the [@../../example/features/introduction.cpp =introduction.cpp=] program and also to automatically build this library when necessary:
[pre
> cd ['lib-root]\example
> bjam features-introduction
]
[endsect]
[endsect]

65
doc/introduction.qbk Normal file
View File

@ -0,0 +1,65 @@
[/ Copyright (C) 2008-2012 Lorenzo Caminiti ]
[/ Distributed under the Boost Software License, Version 1.0 ]
[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
[/ http://www.boost.org/LICENSE_1_0.txt) ]
[/ Home at http://sourceforge.net/projects/contractpp ]
[section Introduction]
Contract Programming allows to specify preconditions, postconditions, and class invariants that are automatically checked when functions are executed at run-time.
These conditions assert program specifications within the source code itself allowing to find bugs more quickly during testing, making the code self-documenting, and increasing overall software quality.
The following example shows how to use this library to program contracts for a member function similar to `std::vector::push_back` (the somewhat arbitrary `pushable` base class is introduced here just to illustrate subcontracting, see [@../../example/features/introduction.cpp =introduction.cpp=]):
[footnote
For simplicity, the full contracts of the `vector` class are not programmed here (see the __Examples__ section for a much more comprehensive version of `vector`'s contracts).
]
[import ../example/features/introduction.cpp]
[introduction]
This library executes the following steps when the `vector::push_back` function above is called at run-time (see __Contract_Programming_Overview__):
* First, the class invariants and the function preconditions are checked.
* Then, the function body following the contract declaration is executed.
* Last, the class invariants and the function postconditions are checked.
* When subcontracting (like in the example above), this library will automatically check derived and base preconditions in __OR__, derived and base postconditions in __AND__, derived and base class invariants in __AND__.
For example, if there is a bug in the function caller for which `push_back` is called when `size` is equal to `max_size` then the execution of the program will terminate with an error message similar to the following (so it will be evident that the bug is in the caller):
[pre
precondition assertion "size() < max_size()" failed: file "introduction.cpp", line 35
]
Instead, if there is a bug in the `push_back` implementation for which `size` is not increased by `1` after `value` is added to `vector` by the function body then the execution will terminate with an error message similar to the following (so it will be evident that the bug is in the `push_back` body):
[pre
postcondition assertion "size() == *old_size + 1" failed: file "introduction.cpp", line 38
]
Similarly, if there is a bug in the `push_back` implementation for which `size` is not kept greater or equal than `capacity` then the execution will terminate with an error message similar to the following:
[pre
exit invariant assertion "size() <= capacity()" failed: file "introduction.cpp", line 25
]
Finally, if the class invariant check failed on entering the `push_back` function call, before executing the `push_back` implementation, then the execution will terminate with an error message similar to the following:
[pre
entry invariant assertion "size() <= capacity()" failed: file "introduction.cpp", line 25
]
By default, when an assertion fails this library prints an error message to the standard error `std::cerr` and terminates the program calling `std::terminate` (this behaviour can be customized to take any user-defined action including throwing exceptions, see the __Throw_on_Failure__ section).
Note that the error message printed by this library contains information to easily and uniquely identify the point in the program at which the assertion failed.
[footnote
*Rationale.*
The assertion failure messages generated by this library follows a format similar to the messages printed by Clang when the C-style `assert` macro fails.
]
[note
C++11 lambda functions are necessary to use this library without having to manually program a significant amount of boiler-plate code (but see the __No_Lambda_Functions__ section).
All other C++11 features (like `auto` declarations) are not really necessary even if they are sometimes used in this documentation for convenience.
]
[endsect]

129
doc/qbk/contract.qbk
View File

@ -1,129 +0,0 @@
[library Boost.Contract
[quickbook 1.5]
[version 1.0]
[authors [Caminiti <email>lorcaminiti@gmail.com</email>, Lorenzo]]
[copyright 2008-2015 Lorenzo Caminiti]
[license Distributed under the Boost Software License, Version 1.0 (see accompanying file LICENSE_1_0.txt or a copy at [@http://www.boost.org/LICENSE_1_0.txt])]
[/ purpose Contract Programming for C++]
[/ category Correctness and Testing]
]
[template file[dir name] '''<ulink url="../../'''[dir]'''/'''[name]'''">'''[^[name]]'''</ulink>''']
[def __CXX03__ [@http://en.wikipedia.org/wiki/C%2B%2B C++03]]
[def __CXX11__ [@http://en.wikipedia.org/wiki/C%2B%2B11 C++11]]
[def __C99__ [@http://en.wikipedia.org/wiki/C99 C99]]
[def __Java__ [@http://en.wikipedia.org/wiki/Java_(programming_language) Java]]
[def __Ada__ [@http://en.wikipedia.org/wiki/Ada_(programming_language) Ada]]
[def __Python__ [@http://www.python.org/ Python]]
[def __Eiffel__ [@http://en.wikipedia.org/wiki/Eiffel_(programming_language) Eiffel]]
[def __D__ [@http://dlang.org D]]
[def __substitution_principle__ [@http://en.wikipedia.org/wiki/Liskov_substitution_principle substitution principle]]
[def __Doxygen__ [@http://www.doxygen.org Doxygen]]
[def __SFINAE__ [@http://en.wikipedia.org/wiki/Substitution_failure_is_not_an_error SFINAE]]
[def __Boost__ [@http://www.boost.org Boost]]
[def __Boost_ConceptCheck__ [@http://www.boost.org/doc/libs/release/libs/concept_check Boost.ConceptCheck]]
[def __Boost_Config__ [@http://www.boost.org/doc/libs/release/libs/config Boost.Config]]
[def __Boost_Foreach__ [@http://www.boost.org/doc/libs/release/libs/foreach Boost.Foreach]]
[def __Boost_Function__ [@http://www.boost.org/doc/libs/release/libs/function Boost.Function]]
[def __Boost_Graph__ [@http://www.boost.org/doc/libs/release/libs/graph Boost.Graph]]
[def __Boost_Jam__ [@http://www.boost.org/doc/libs/release/doc/html/jam.html Boost.Jam]]
[def __Boost_LocalFunction__ [@http://www.boost.org/doc/libs/release/libs/local_function Boost.LocalFunction]]
[def __Boost_MPL__ [@http://www.boost.org/doc/libs/release/libs/mpl Boost.MPL]]
[def __Boost_Parameter__ [@http://www.boost.org/doc/libs/release/libs/parameter Boost.Parameter]]
[def __Boost_Phoenix__ [@http://www.boost.org/doc/libs/release/libs/phoenix Boost.Phoenix]]
[def __Boost_Preprocessor__ [@http://www.boost.org/doc/libs/release/libs/preprocessor Boost.Preprocessor]]
[def __Boost_Python__ [@http://www.boost.org/doc/libs/release/libs/python Boost.Python]]
[def __Boost_Typeof__ [@http://www.boost.org/doc/libs/release/libs/typeof Boost.Typeof]]
[def __Boost_TypeTraits__ [@http://www.boost.org/doc/libs/release/libs/type_traits Boost.TypeTraits]]
[def __Boost_Utility_IdentityType__ [@http://www.boost.org/doc/libs/release/libs/utility/identity_type Boost.Utility/IdentityType]]
[def __Bright04__ [link Bright04_anchor \[Bright04\]]]
[def __Bright04b__ [link Bright04b_anchor \[Bright04b\]]]
[def __C2__ [link C2_anchor \[C2\]]]
[def __Chrome02__ [link Chrome02_anchor \[Chrome02\]]]
[def __Cline90__ [link Cline90_anchor \[Cline90\]]]
[def __CodeContracts__ [link CodeContracts_anchor \[CodeContracts\]]]
[def __iContract__ [link iContract_anchor \[iContract\]]]
[def __Hoare73__ [link Hoare73_anchor \[Hoare73\]]]
[def __Jcontract__ [link Jcontract_anchor \[Jcontract\]]]
[def __Lindrud04__ [link Lindrud04_anchor \[Lindrud04\]]]
[def __Maley99__ [link Maley99_anchor \[Maley99\]]]
[def __Meyer97__ [link Meyer97_anchor \[Meyer97\]]]
[def __Mitchell02__ [link Mitchell02_anchor \[Mitchell02\]]]
[def __N1613__ [link N1613_anchor \[N1613\]]]
[def __N1866__ [link N1866_anchor \[N1866\]]]
[def __N1962__ [link N1962_anchor \[N1962\]]]
[def __N2081__ [link N2081_anchor \[N2081\]]]
[def __N2914__ [link N2914_anchor \[N2914\]]]
[def __SPARKAda__ [link SPARKAda_anchor \[SPARKAda\]]]
[def __SpecSharp__ [link SpecSharp_anchor \[SpecSharp\]]]
[def __Stroustrup97__ [link Stroustrup97_anchor \[Stroustrup97\]]]
[def __Stroustrup94__ [link Stroustrup94_anchor \[Stroustrup94\]]]
[def __Tandin04__ [link Tandin04_anchor \[Tandin04\]]]
[def __Introduction__ [link contract__.introduction Introduction]]
[def __Full_Table_of_Contents__ [link contract__.full_table_of_contents Full Table of Contents]]
[def __Getting_Started__ [link contract__.getting_started Getting Started]]
[def __Contract_Programming_Overview__ [link contract__.contract_programming_overview Contract Programming Overview]]
[def __Costs__ [link contract__.contract_programming_overview.costs Costs]]
[def __Free_Function_Calls__ [link contract__.contract_programming_overview.free_function_calls Free Function Calls]]
[def __Member_Function_Calls__ [link contract__.contract_programming_overview.member_function_calls Member Function Calls]]
[def __Constructor_Calls__ [link contract__.contract_programming_overview.constructor_calls Constructor Calls]]
[def __Destructor_Calls__ [link contract__.contract_programming_overview.destructor_calls Destructor Calls]]
[def __Constant_Correctness__ [link contract__.contract_programming_overview.constant_correctness Constant-Correctness]]
[def __Specification_vs__Implementation__ [link contract__.contract_programming_overview.specification_vs__implementation Specification vs. Implementation]]
[def __Broken_Contracts__ [link contract__.contract_programming_overview.broken_contracts Broken Contracts]]
[def __Features__ [link contract__.contract_programming_overview.features Features]]
[def __Tutorial__ [link contract__.tutorial Tutorial]]
[def __Forward_Declarations_and_Body_Definitions__ [link contract__.tutorial.forward_declarations_and_body_definitions Forward Declarations and Body Definitions]]
[def __Advanced_Topics__ [link contract__.advanced_topics Advanced Topics]]
[def __Assertion_Requirements__ [link contract__.advanced_topics.assertion_requirements Assertion Requirements]]
[def __Contract_Broken_Handlers__ [link contract__.advanced_topics.contract_broken_handlers__throw_on_failure_ Contract Broken Handlers]]
[def __Virtual_Specifiers__ [link contract__.virtual_specifiers Virtual Specifiers]]
[def __Concepts__ [link contract__.concepts Concepts]]
[def __Named_Parameters__ [link contract__.named_parameters Named Parameters]]
[def __Parameter_Identifiers__ [link contract__.named_parameters.parameter_identifiers Parameter Identifiers]]
[def __Examples__ [link contract__.examples Examples]]
[def __Grammar__ [link contract__.grammar Grammar]]
[def __Differences_with_CXX_Syntax__ [link contract__.grammar.differences_with_c___syntax Differences with C++ Syntax]]
[def __No_Variadic_Macros__ [link contract__.no_variadic_macros No Variadic Macros]]
[def __Reference__ [link contract__.reference Reference]]
[def __Bibliography__ [link contract__.bibliography Bibliography]]
[def __Release_Notes__ [link contract__.release_notes Release Notes]]
[def __Acknowledgments__ [link contract__.acknowledgments Acknowledgments]]
[def __AND__ [link logic_and_anchor [^AND]]]
[def __OR__ [link logic_or_anchor [^OR]]]
[def __Assignable__ [@http://www.boost.org/doc/libs/release/libs/utility/Assignable.html [^Assignable]]]
[def __ConstantCopyConstructible__ [link contract__.advanced_topics.old_and_result_value_copies [^ConstantCopyConstructible]]]
[def __CopyConstructible__ [@http://www.boost.org/doc/libs/release/libs/utility/CopyConstructible.html [^CopyConstructible]]]
[def __DefaultConstructible__ [@http://www.sgi.com/tech/stl/DefaultConstructible.html [^DefaultConstructible]]]
[def __EqualityComparable__ [@http://www.sgi.com/tech/stl/EqualityComparable.html [^EqualityComparable]]]
[def __InputIterator__ [@http://www.sgi.com/tech/stl/InputIterator.html [^InputIterator]]]
[:['["Our field needs more formality, but the profession has not realized it yet.]]]
[:['-- Bertrand Meyer (see __Meyer97__ page 400)]]
This library implements
[@http://en.wikipedia.org/wiki/Design_by_contract Contract Programming] (a.k.a., Design by Contract, DbC)
[footnote
Design by Contract (DbC) is a registered trademark of [@http://en.wikipedia.org/wiki/Eiffel_Software Eiffel Software].
Its methodology was first introduced by the __Eiffel__ programming language (see __Meyer97__).
]
for the C++ programming language.
All Contract Programming features are supported: subcontracting, class invariants, postconditions (with old and result values), preconditions, customizable actions on assertion failure, optional assertion compilation, disable assertion checking within other assertion checking, etc.
[include introduction.qbk]
[include getting_started.qbk]
[include contract_programming_overview.qbk]
[include tutorial.qbk]
[include advanced_topics.qbk]
[include examples.qbk]
[/ xinclude reference.xml]
[include release_notes.qbk]
[include bibliography.qbk]
[include acknowledgments.qbk]

101
doc/qbk/getting_started.qbk
View File

@ -1,101 +0,0 @@
[/ Copyright (C) 2008-2012 Lorenzo Caminiti ]
[/ Distributed under the Boost Software License, Version 1.0 ]
[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
[/ http://www.boost.org/LICENSE_1_0.txt) ]
[/ Home at http://sourceforge.net/projects/contractpp ]
[section Getting Started]
This section explains how to get oriented in order to start using this library.
[section This Documentation]
Programmers should have enough knowledge to use this library after reading the __Introduction__, __Getting_Started__, and __Tutorial__ sections.
The other sections can be consulted to gain a more in depth knowledge of the library.
Some footnotes are marked by the word "*Rationale*".
These explain reasons behind decisions made during the design and implementation of this library.
In most of the examples presented in this documentation the Boost.Detail/LightweightTest macroo `BOOST_TEST` and `BOOST_TEST_EQ` are used to test predicates and equality conditions respectively.
These macros are conceptually similar to C-style `assert` macro but they exit the program with a non-zero exit code via `boost::report_errors`, instead of aborting the program.
See =boost/detail/lightweight_test.hpp= for more information.
[footnote
*Rationale.*
Using Boost.Detail/LightweightTest allows to add the examples from this documentation to the library regression tests so to make sure that they always compile and run correctly.
Technically, Boost.Detail/LightweightTest is part of __Boost__'s non-public API so it should not be directly used by users outside __Boost__ (see __Boost_Test__ instead), but it is common practice to use it in the development and testing of other libraries like this one.
]
[endsect]
[section Compilers and Platforms]
In general, this library requires a C++ compiler with a sound support of __SFINAE__ and other template meta-programming techniques as per the __CXX03__ standard.
See the __Without_CXX11__ section for information on how to use this library without __CXX11__ features:
* In theory, it is possible to use this library without __CXX11__ lambda functions.
However, in that case a large amount of boiler-plate code is required to program separate functions to specify preconditions and postconditions (so using this library without __CXX11__ lambda functions is not recommended).
* It is possible to use this library without __CXX11__ (or __CXX99__) variadic macros.
In this case, some (smaller) amount of boiler-plate code is required to manually program the code otherwise expanded by the variadic macros.
* It is always possible to use this library without __CXX11__ auto declarations.
Most of the examples in this documentation use auto declarations only for simplicity and because they make the code more readable.
The authors originally developed and tested this library on:
* __Clang__ 3.4.2 on Cygwin (with __CXX11__ features enabled =-std=c++11=).
* _GCC__ 4.8.3 on Cygwin (with __CXX11__ features enabled =-std=c++11=).
* Microsoft Visual C++ (__MSVC__) 10.0 on Windows.
At present, this library has not been tested on other compilers or platforms.
[endsect]
[section Files and Names]
The directory structure of this library's files is as follow:
[pre
doc/
html/ # This documentation.
example/ # Examples (including the ones listed in this documentation).
include/ # Header files.
boost/
contract.hpp
contract/
core/
aux_/
test/ # Tests.
]
All headers required by this library can be included at once by:
#include <boost/contract.hpp>
Alternatively, all headers =boost/contract/*.hpp= are independent from one another and they can selectively included one at the time based on the specific API required from this library.
Headers in =boost/contract/core/= are also part of this library public API but they are not independent from other public headers (in general, these headers will be automatically included by including other public headers of this library).
Header files in =boost/contract/aux_/=, names in the `boost::contract::aux` namespace, names starting with `boost_contract_aux...` and `BOOST_CONTRACT_AUX...` in any namespace are all part of this library private API and should never be used directly in user code.
Names starting with `BOOST_CONTRACT_ERROR...` are used by this library to report compile-time errors (so spotting these names in error messages reported by the compiler might help in resolving errors).
[endsect]
[section Installation]
TODO
[endsect]
[section Disable Contract Compilation]
Some behaviour of this library can be customized at compile-time by defining special /configuration macros/ (see [headerref boost/contract/config.hpp]).
In particular, defining the macros [macroref BOOST_CONTRACT_NO_PRECONDITIONS], [macroref BOOST_CONTRACT_NO_POSTCONDITIONS], and [macroref BOOST_CONTRACT_NO_INVARIANTS] disables run-time checking of all preconditions, postconditions, and class invariants respectively.
By default, all contracts are checked at run-time (i.e., all these macros are not defined).
[endsect]
[endsect]

63
doc/qbk/introduction.qbk
View File

@ -1,63 +0,0 @@
[/ Copyright (C) 2008-2012 Lorenzo Caminiti ]
[/ Distributed under the Boost Software License, Version 1.0 ]
[/ (see accompanying file LICENSE_1_0.txt or a copy at ]
[/ http://www.boost.org/LICENSE_1_0.txt) ]
[/ Home at http://sourceforge.net/projects/contractpp ]
[section Introduction]
Contract Programming allows to specify preconditions, postconditions, and class invariants that are automatically checked when functions are executed at run-time.
These conditions assert program specifications within the source code itself allowing to find bugs more quickly during testing, making the code self-documenting, and increasing overall software quality.
The following example shows how to use this library to program contracts for the [@http://www.sgi.com/tech/stl/BackInsertionSequence.html `std::vector::push_back`] member function (for simplicity, the full contracts are not programmed here, see the __Examples__ section for a fully contracted version of `std::vector`).
In order to illustrate subcontracting, this `vector` class inherits from the (somewhat arbitrary) `pushable` base class (see also [@../../example/features/introduction.cpp =introduction.cpp=]):
[import ../example/features/introduction.cpp]
[introduction]
This library executes the following steps when the `vector::push_back` function above is called at run-time (see also the __Contract_Programming_Overview__ section):
* First, the class invariants and the function preconditions are checked.
* Then, the function body following the contract declaration is executed.
* Last, the class invariants and the function postconditions are checked.
* When subcontracting (like in the example above), this library will automatically check derived and base preconditions in __OR__, derived and base postconditions in __AND__, derived and base class invariants in __AND__.
For example, if there is a bug in the function caller for which `push_back` is called when `size` is equal to `max_size` then the execution of the program will terminate with an error message similar to the following, thus it will be evident the bug is in the caller:
[pre
precondition assertion "size() < max_size()" failed: file "introduction.cpp", line 36
]
Instead, if there is a bug in the `push_back` implementation for which `size()` is not increased by `1` after `value` is added to `vector` by the function body then the execution will terminate with an error message similar to the following, thus it will be evident the bug is in the `push_back` body:
[pre
postcondition assertion "size() == *old_size + 1" failed: file "introduction.cpp", line 39
]
Similarly, if there is a bug in the `push_back` implementation for which `size()` is not kept greater or equal than `capacity()` then the execution will terminate with an error message similar to the following:
[pre
exit invariant assertion "size() <= capacity()" failed: file "introduction.cpp", line 27
]
And, if the class invariant check failed on entering the `push_back` function call, before executing the `push_back` implementation, the message before program termination would have said:
[pre
entry invariant assertion "size() <= capacity()" failed: file "introduction.cpp", line 27
]
By default, when an assertion fails this library prints an error message the standard error `std::cerr` and then it terminates the program calling `std::terminate` (but this behaviour can be customized to any user-defined action including throwing an exception, see the __Contract_Failure_Handlers__ section).
Note that the error message printed by this library contains information to easily and uniquely identify the assertion that failed.
[footnote
*Rationale.*
The assertion failure message generated by this library follows a format similar to the message printed by __Clang__ when the C-style `assert` macro fails.
]
[note
C++11 lambda functions are required to use this library without having to write a significant amount of boiler-plate code (but see also __No_Lambda_Functions).
Other C++11 features (like auto declarations) are not really necessary even if they are sometime used in this documentation for convenience.
]
[endsect]

517
doc/qbk/tutorial.qbk
View File

@ -1,517 +0,0 @@
[import ../example/features/public.cpp]
[section Tutorial]
This section gives an introduction on how to program contracts using this library.
[section Free Functions]
Consider the following free function `inc` which increments its argument by `1` and returns the value its argument had before the increment (this function is equivalent to the usual C++ operator `int operator++(int& x, int)`).
Let's write the contract for such a function using code comments (see also [@../../example/features/no_contracts.cpp =no_contracts.cpp=]):
[import ../../example/features/no_contracts.cpp]
[no_contracts]
The precondition states that the argument to increment must be smaller than the maximum allowable value of its type (otherwise the increment will go out-of-range).
The postconditions state that the argument was actually incremented by `1` and that the function return value is equal to the argument before it was incremented.
Now let's program this function and its contract using the [funcref boost::contract::function] function from this library (see also [@../../example/features/free_function.cpp =free_function.cpp=]):
[import ../../example/features/free_function.cpp]
[free_function]
All necessary header files of this library are included by `#include <boost/contract.hpp>`.
Alternatively, programmers can selectively include only the header files they actually need among =boost/contract/*.hpp= (see also __Getting_Started__).
It is possible to specify both preconditions and postconditions for free functions (see also __Preconditions__ and __Postconditions__).
[funcref boost::contract::function] returns an RAII object (that can be assigned to a local variable of explicit type [classref boost::contract::guard] when programmers are not using C++11 auto declarations).
The free function body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check preconditions, by calling the functor [^['f]]`()` passed to `.precondition(`[^['f]]`)`.
At destruction instead:
# If the function body did not throw an exception:
# Check postconditions, by calling the functor [^['g]]`()` passed to `.postcondition(`[^['g]]`)`.
This ensures that free function contracts are correctly checked at run-time (see also __Function_Calls__).
[note
A free function can avoid calling [funcref boost::contract::function] for efficiency but only when it has no preconditions and no postconditions.
]
[endsect]
The same considerations also apply to private and protected member functions because their contracts are also programmed using [funcref boost::contract::function] like for free functions (see also __Private_and_Protected_Functions__).
[section Preconditions]
When preconditions are specified, they are programmed using a functor that can be called with no parameter [^['f]]`()` and it is passed to `.precondition(`[^['f]]`)`.
Contracts that do not have preconditions simply do not call `.precondition(...)`.
C++11 lambda functions are very convenient to program preconditions, but any other nullary functor can be used (see also __No_Lambda_Functions__).
[footnote
C++11 lambda functions with no parameters can be programmed as `[...] () { ... }` but also equivalently as `[...] { ... }`.
This second from is often used in this documentation omitting the empty parameter list `()` for brevity.
]
For example, for a free function contract (but same for all other contracts):
auto c = boost::contract::function() // Same for all other contracts.
.precondition([&] { // Capture by reference or value...
BOOST_CONTRACT_ASSERT(...); // ...but should not modify captures.
...
})
...
;
The precondition functor should capture all the variables that it needs to assert the preconditions.
These variables can be captured by value when the overhead associated with copying such variables is acceptable (but in this documentation preconditions often capture these variables by reference to avoid such overhead).
In any case, precondition assertions should not modify the value of the captured variables, even when those are captured by reference (see also __Constant_Correctness__).
Any code can be programmed for 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 slow to execute at run-time).
It is also recommended to use the [macroref BOOST_CONTRACT_ASSERT] macro to program the assertions because it enables this library to print very informative error messages when the asserted conditions are evaluated to be false at run-time (this is not a variadic macro, but see also __No_Macros__):
BOOST_CONTRACT_ASSERT(``/boolean-condition/``)
// Or, if condition has commas `,` not already within parenthesis `(...)`.
BOOST_CONTRACT_ASSERT((``/boolean-condition/``))
This library will automatically call [funcref boost::contract::precondition_failed] if any of the [macroref BOOST_CONTRACT_ASSERT] macro conditions are `false` and also if the precondition functor call throws any exception (by default, this terminates the program calling `std::terminate`, but see __Throw_on_Failure__ to throw exceptions, exit the program with an error code, etc.).
Preconditions can be specified before or after postconditions (by calling `.precondition(...)` before or after `.postcondition(...)`).
This library will generate a compile-time error if preconditions are specified multiple times for the same contract.
[note
Contracts are most useful when the assertions only use public members that are accessible to the caller so the caller can properly check and use the contract.
In particular, preconditions of a public member function or constructor that use non-public members are essentially incorrect because they cannot be fully checked by the caller (in fact, Eiffel generates a compile-time error in this case).
This library leaves it up to the programmers to only use public members when programming contracts and especially when programming preconditions (see also __Specification_and_Implementation__).
]
[endsect]
[section Postconditions]
When postconditions are specified, they are programmed using a functor that can be called with no parameter [^['g]]`()` and it is passed to `.postcondition(`[^['g]]`)`.
Contracts that do not have postconditions simply do not call `.postcondition(...)`.
C++11 lambda functions are very convenient to program postconditions, but any other nullary functor can be used (see also __No_Lambda_Functions__).
For example, for a free function contract (but same for all other contracts):
auto c = boost::contract::function() // Same for all other contracts.
...
.postcondition([&] { // Capture by reference...
BOOST_CONTRACT_ASSERT(...); // ...but should not modify captures.
...
})
;
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 these variables will have at function exit, and not the value these variables had when the postcondition functor was first constructed).
Postconditions can also capture return and old values (see also __Return_Value__ and __Old_Values__).
In any case, postcondition assertions should not modify the value of the captured variables (see also __Constant_Correctness__).
Any code can be programmed for 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 execute at run-time).
It is also recommended to use the [macroref BOOST_CONTRACT_ASSERT] macro to program the assertions because it enables this library to print very informative error messages when the asserted conditions are evaluated to be false at run-time (this is not a variadic macro, but see also __No_Macros__):
BOOST_CONTRACT_ASSERT(``/boolean-condition/``)
// Or, if condition has commas `,` not already within parenthesis `(...)`.
BOOST_CONTRACT_ASSERT((``/boolean-condition/``))
This library will automatically call [funcref boost::contract::postcondition_failed] if any of the [macroref BOOST_CONTRACT_ASSERT] macro conditions are `false` and also if the postcondition functor call throws any exception (by default, this terminates the program calling `std::terminate`, but see __Throw_on_Failure__ to throw exceptions, exit the program with an error code, etc.).
Postconditions can be specified before or after preconditions (by calling `.postcondition(...)` before or after `.precondition(...)`).
This library will generate a compile-time error if postconditions are specified multiple times for the same contract.
[endsect]
[section Return Value]
When the function non-void return value is used in postconditions, programmers are responsible to declare a local variable before the contract and to assign it to the return value at function exit (when the function does not throw an exception).
[footnote
The name of the local variable that holds the return value is arbitrary, but `result` is often used in this documentation.
]
For example, for a free function contract (but same for all other contracts):
``/return-type/`` result; // Must be assigned to return value.
auto c = boost::contract::function() // Same for all other contracts.
...
.postcondition([&] { // Also capture `result` reference...
... // ...but should not modify captures.
})
;
At any point where the enclosing function returns, programmers are responsible to assign the result variable to the expression being returned.
This can be easily done by making sure that /all/ the `return` statements in the function are of the form:
return result = ``/expression/``; // Assign `result` at each return.
The functor used to program postconditions should capture the result variable by reference (because postconditions must access the value this variable will have at function exit, and not the value this variable had when the postcondition functor was first constructed).
The return value should never be used in preconditions (because the return value is not yet evaluated and set when preconditions are checked, see also __Assertions__).
In any case, programmers should not modify the result variable in the contract assertions (see also __Constant_Correctness__).
It is also possible to declared result variables using `boost::optional` when the return type does not have a default constructor, or if the default constructor is too expensive to execute, etc. (see also __Optional_Return_Value__).
Virtual and overriding public member functions must always declare and use a result variable even when that is not directly used in postconditions (see also __Virtual_Public_Functions__ and __Overriding_Public_Functions__).
[endsect]
[section Old Values]
When old values are used in postconditions, programmes are responsible to declare local variables before the contract and to assign them to the related expressions via the [macroref BOOST_CONTRACT_OLDOF] macro.
[footnote
The name of the local variable that holds an old value is arbitrary, but `old_`[^['name]] is often used in this documentation.
]
For example, for a free function contract (but same for all other contracts):
...
boost::shared_ptr<``/type/`` const> old_``/name/`` = BOOST_CONTRACT_OLDOF(``/expression/``);
auto c = boost::contract::function() // Or some other contract object.
...
.postcondition([&] { // Capture by reference...
... // ...but should not modify captures.
})
;
Old values are handled as smart pointers to `const` values (so they cannot be mistakenly changed by the contract assertions, see also __Constant_Correctness__).
[footnote
*Rationale.*
`boost::shared_ptr` was used instead of `std::shared_ptr` because this library is designed to work well with Boost and technically to not require C++11 (even if the use of this library without C++11 lambda functions requires programmer to write a fare amount of boiler-plate code).
]
Therefore, old values must be dereferenced using `operator*` or `operator->` when they are used in postconditions (otherwise the compiler will most likely error).
This library ensures that old value smart pointers are not null by the time postconditions are checked so programmers can always safely dereference old value pointers in postconditions without any extra checking.
Old values should never be used in preconditions (because old values are same as original values when preconditions are checked, see also __Assertions__).
In fact, this library does not even guarantee that old value pointers are always not null when precondition functors are called (for example, when postcondition contract checking is disabled using [macroref BOOST_CONTRACT_CONFIG_NO_POSTCONDITONS], when checking an overridden virtual function contract via subcontracting, etc.).
Finally, see __Old_Values_at_Body__ for always delaying the assignment of old values until after preconditions (and possibly class invariants) have been checked first (in case it is important to simplify old value expressions programming them under the assumption that precondition and class invariant conditions are satisfied already).
This library ensures that old values are only copied once by the [macroref BOOST_CONTRACT_OLDOF] macro that they are actually never copied when postcondition contract checking is disabled by the [macroref BOOST_CONTRACT_CONFIF_NO_POSTCONDITIONS] configuration macro.
[macroref BOOST_CONTRACT_OLDOF] is actually a variadic macro and it takes an extra parameter when used in virtual or overriding public functions (see also __Virtual_Public_Functions__ and __Overriding_Public_Functions__, and see __No_Macros__ to program old values without using macros).
In the rest of this documentation, C++11 auto declarations will be often used for old values instead of explicitly writing the `boost::shared_ptr<... const>` type.
This is done just for convenience, and programmers can alway explicitly specify the declaration type if they are not using C++11 auto declarations.
[endsect]
[section Class Invariants]
When class invariants are specified, they are programmed in a public `const` member function named `invariant` taking no argument and returning `void`.
Classes that do not have invariants, simply do not declare an `invariant` member function.
[footnote
This library uses template meta-programming (SFINAE-based introspection techniques) to check invariants only for classes that declare a member function named `invariant`.
]
For example:
class a {
public: // Must be public.
void invariant() const { // Must be const.
BOOST_CONTRACT_ASSERT(...);
...
}
...
};
This member function must be `const` because contracts should not modify the object state (see also __Constant_Correctness__).
This library will generate a compile-time error if the `const` qualifier is missing (unless [macroref BOOST_CONTRACT_CONFIG_PERMISSIVE] is set).
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 execute at run-time).
It is also recommended to use the [macroref BOOST_CONTRACT_ASSERT] macro to program the assertions because it enables this library to print very informative error messages when the asserted conditions are evaluated to be false at run-time (this is not a variadic macro, but see also __No_Macros__):
BOOST_CONTRACT_ASSERT(``/boolean-condition/``)
// Or, if condition has commas `,` not already within parenthesis `(...)`.
BOOST_CONTRACT_ASSERT((``/boolean-condition/``))
This library will automatically call [funcref boost::contract::entry_invariant_failed] or [funcref boost::contract::exit_invariant_failed] if any of the [macroref BOOST_CONTRACT_ASSERT] macro conditions are `false` and also if the `invariant` function throws an exception (by default, this terminates the program calling `std::terminate`, but see __Throw_on_Failure__ to throw exceptions, exit the program with an error code, etc.).
See __Access__ to avoid making `invariant` a public member function (e.g., in cases when all public members of a class must be controlled exactly).
Set the [macroref BOOST_CONTRACT_CONFIG_INVARIANT] configuration macro to use a name different from `invariant` (e.g., because `invariant` clashes with other names in the user-defined class).
Furthermore, see __Static_Public_Functions__ and __Volatile_Public_Functions__ for programming class invariants for `static` and `volatile` public member function calls respectively.
[note
No contracts are checked (not event class invariants) when a data member is accessed directly (this is different from Eiffel where even accessing public data members checks class invariants).
Therefore, it might be best for both `class`es and `struct`s to have no mutable public data members and to access data members publicly only via appropriate public member functions that can check the class invariants.
]
[endsect]
[section Constructors]
Contracts for constructors are programmed using the [funcref boost::contract::constructor] function and the [classref boost::contract::constructor_precondition] base class.
For example (see also [@../../example/features/public.cpp =public.cpp=]):
[public_constructor]
It is not possible to specify preconditions using `.precondition(...)` for constructors (the 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 (see also __Preconditions__).
Programmes should not access the object `this` from constructor preconditions (because the object does not exists yet before the constructor body is executed, see also __No_Lambda_Functions__).
Constructors without preconditions simply do not explicitly initialize the [classref boost::contract::constructor_precondition] base (the base default constructor is used instead and that checks no contract).
When [classref boost::contract::constructor_precondition] is used:
* It must be specified as the /first/ class in the inheritance list (so constructor preconditions are checked before initializing any other base or member).
* Its inheritance level should always be `private` (so this extra base class does not alter the public inheritance tree of the derived class).
* It takes the derived class as template parameter (the Curiously Recursive Template Pattern (CRTP) is used here to avoid ambiguity errors with multiple inheritance).
[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 always avoiding base class ambiguities even in case of multiple inheritance.
Virtual inheritance cannot be used resolve such ambiguities because virtual bases are initialized only once by the out-most deriving class, and that would not allow to properly check preconditions of all base classes.
]
It is possible to specify postconditions for constructors (see also __Postconditions__).
Programmers should not access the old value of the object `this` in constructor postconditions (because the object did not exist yet before the constructor body was executed, see also __No_Lambda_Functions__).
[funcref boost::contract::constructor] takes `this` as a parameter because constructors check class invariants (see also __Class_Invariants__).
[funcref boost::contract::constructor] returns an RAII object (that can be assigned to a local variable of explicit type [classref boost::contract::guard] when programmers are not using C++11 auto declarations).
The constructor body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()` (but not non-static class invariants because the object does not exists yet).
At destruction instead:
# Check static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()`.
# If the constructor body did not throw an exception:
# Check non-static class invariants, by calling `this->invariant()`.
# Check postconditions, by calling the functor ['[^g]]`()` passed to `.postcondition(`['[^g]]`)`.
This together with C++ construction mechanism of base classes and the use of [classref boost::contract::constructor_precondition] ensures that the constructor contracts are correctly checked at run-time (see also __Constructor_Calls__).
[note
A constructor can avoid calling [funcref boost::contract::constructor] for efficiency but only when it has no postconditions and its class has no invariants.
(Even if [funcref boost::contract::constuctor] is not used, the constructor's class can still have bases because their contracts are always checked by C++ construction mechanism.)
]
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 also __Constructor_Calls__).
They could still use [classref boost::contract::constructor_precondition] to check preconditions before member initializations, and use [funcref boost::contract::function] to just check postconditions instead.
[endsect]
[section Destructors]
Contracts for destructors are programmed using the [funcref boost::contract::destructor] function.
For example (see also [@../../example/features/public.cpp =public.cpp=]):
[public_destructor]
It is not possible to specify preconditions for destructors (the library will generate a compile-time error if `.precondition(...)` is used here because destructors can be called at any time after construction so they have no precondition).
It is possible to specify postconditions for destructors (see also __Postconditions__ and see __Static_Public_Functions__ for an example).
Programmers should not access the object `this` in destructor postconditions (because the object no longer exists after the destructor body has been executed, see also __No_Lambda_Functions__).
[funcref boost::contract::destructor] takes `this` as a parameter because destructors check class invariants (see also __Class_Invariants__).
[funcref boost::contract::destructor] returns an RAII object (that can be assigned to a local variable of explicit type [classref boost::contract::guard] when programmers are not using C++11 auto declarations).
The destructor body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check static and non-static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()`.
At destruction instead:
# Check static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()`.
# If the destructor body threw an exception:
# Check non-static class invariants, by calling `this->invariant()` (because the object was not successfully destructed).
# Else:
# Check postconditions, by calling the functor ['[^g]]`()` passed to `.postcondition(`['[^g]]`)`.
This together with C++ destruction mechanism of base classes ensures that destructor contracts are correctly checked at run-time (see also __Destructor_Calls__).
[note
A destructor can avoid calling [funcref boost::contract::destructor] for efficiency but only when it has no postconditions and its class has no invariants.
(Even if [funcref boost::contract::destructor] is not used, the destructor's class can still have bases because their contracts are always checked by C++ destruction mechanism.)
]
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 also __Destructor_Calls__).
They could use [funcref boost::contract::function] to just check postconditions instead.
[endsect]
[section Public Functions]
Contracts for public member functions are programmed using the [funcref boost::contract::public_function] function.
Let's first consider public member functions that are not static, not virtual, and do not override any function from base classes.
For example, the following such a function `find` is declared as a member of the `unique_identifiers` class (see also [@../../example/features/public.cpp =public.cpp=]):
[public_function]
It is possible to specify both preconditions and postconditions for public member functions (see also __Preconditions__ and __Postconditions__).
[funcref boost::contract::public_function] takes `this` as a parameter because public member functions check class invariants (see also __Class_Invariants__).
[funcref boost::contract::public_function] returns an RAII object (that can be assigned to a local variable of explicit type [classref boost::contract::guard] when programmers are not using C++11 auto declarations).
The public member function body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check static and non-static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()`.
# Check preconditions, by calling the functor ['[^f]]`()` passed to `.precondition(`['[^f]]`)`.
At destruction instead:
# Check static and non-static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()` (even if the function body threw an exception).
# If the function body did not throw an exception:
# Check postconditions, by calling the functor ['[^g]]`()` passed to `.postcondition(`['[^g]]`)`.
This ensures that public member function contracts are correctly checked at run-time (see also __Public_Function_Calls__).
[note
A public member function can avoid calling [funcref boost::contract::public_function] for efficiency but only when it has no preconditions and no postconditions, it is not virtual, it does not override any virtual function, and its class has no invariant.
]
[endsect]
[section Virtual Public Functions]
Let's now consider public member functions that are virtual but that still do not override any function from base classes.
For example, the following such a function `push_back` is declared as a member of the `unique_identifiers` class (see also [@../../example/features/public.cpp =public.cpp=]):
[public_virtual_function]
Public virtual functions must declare an extra trailing parameter of type [classref boost::contract::virtual_]`*` and assign it to `0` by default (i.e., null).
Because this extra parameter is the last one and it has a default value, it does not alter the calling interface of the virtual function and callers will essentially never have to deal with it explicitly (a part from when manipulating the virtual function type for function pointer type-casting, etc.).
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 virtual function.
[footnote
*Rationale.*
The [classref boost::contract::virtual_]`*` optional parameter is used by this library to determine that a function is virtual (in C++ it is not possible to introspect if a function has been declared `virtual`).
Furthermore, this parameter is used by this library to pass result and old values that are evaluated by overriding function to the overridden virtual functions, and also to check preconditions and postconditions (but without executing the body) of the overridden virtual functions when subcontracting.
]
Furthermore, for non-void public virtual functions, programmers must pass a reference to the function return value as the second argument to [funcref boost::contract::public_function].
In this case the functor specified to `.postcondition(...)` takes a single parameter (possibly as a constant reference `const&`) to the return value.
[footnote
*Rationale.*
The functor passed to `.postcondition(...)` takes the extra return value parameter because that is used by this library to pass the return value evaluated by the overriding function to all its overridden virtual functions when subcontracting.
]
[important
It is the responsibility of the programmers to pass the extra result parameter to [funcref boost::contract::public_function] for non-void virtual functions.
[footnote
*Rationale.*
This library does not require the function type when using [funcref boost::contract::public_function] for non-overriding virtual functions.
Therefore, this library does not know if the enclosing function has a non-void return type and it cannot enforce that at compile-time.
It can do that only for overriding virtual functions.
]
]
[important
It is the responsibility of the programmers to pass the virtual extra parameter to all [macroref BOOST_CONTRACT_OLDOF] and [funcref boost::contract::public_function] calls, and also to pass the return value reference to [funcref boost::contract::public_function] for non-void functions.
This library cannot automatically generate compile-time errors if programmers fail to do so, but in general contract checking will not correctly work at run-time in such cases.
['Remember: When "`v`" is present, always pass it to old-of macros and contract-function calls; Always pass result after "`v`" for non-void functions.]
]
For the rest, the same considerations made in __Public_Functions__ apply.
[endsect]
[section Overriding Public Functions (Subcontracting)]
Let's now consider public member functions (virtual or not) that override public virtual functions from one or more public base class.
For example, the following such a function `push_back` is declared as a member of the `identifiers` derived class and it overrides `push_back` from the `unique_identifiers` base class (see also [@../../example/features/public.cpp =public.cpp=]):
[footnote
In this document, overriding functions are often marked with the `/* override */` comment.
On compilers that support C++11 virtual specifiers `override` can be used instead (`override` is not used in the documentation only because virtual specifiers are not widely supported yet, even by compilers that support other C++11 features like lambda functions).
]
[public_override_function]
(See the __Base_Types__ section below for more information about [macroref BOOST_CONTRACT_BASE_TYPES] and `base_types`.)
Overriding public functions must always list the extra trailing parameter of type [classref boost::contract::virtual_]`*` with `0` default value, even when they are not declared `virtual` (because 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 overriding function (as for non-overriding virtual public functions discussed above).
For overriding functions, [funcref boost::contract::public_function] takes an explicit template argument `override_`[^['function-name]] that must be defined at class scope using [macroref BOOST_CONTRACT_OVERRIDE][^(['function-name])] (see right after the function).
When called from overriding public functions, [funcref boost::contract::public_function] also takes a pointer to the enclosing function, the object `this` (because overriding public functions check 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 `bind`'s syntax.
The function pointer and references to all function arguments are needed for overriding virtual public functions because this library has to call overridden virtual public functions to check their contracts for subcontracting (even if without executing their bodies).
]
Furthermore, for non-void overriding public functions, programmers must pass a reference to the function return value as the second argument to [funcref boost::contract::public_function] (this library will generate a compile-time error otherwise).
[footnote
*Rationale.*
Again, the extra return value parameter is used to pass the return value to the overridden virtual public functions when subcontracting.
However, in this case the library has also 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 was not possible instead for non-overriding virtual public functions because their contracts do not use the function pointer, see also __Virtual_Public_Functions__).
]
In this case the functor specified to `.postcondition(...)` takes a single parameter (possibly as a constant reference `const&`) to the return value (this library will generate a compile-time error otherwise).
[important
['Remember: When "`v`" is present, always pass it to old-of macros and contract-function calls; Always pass result after "`v`" for non-void functions.]
]
[funcref boost::contract::public_function] returns an RAII object (that can be assigned to a local variable of explicit type [classref boost::contract::guard] when programmers are not using C++11 auto declarations).
The public member function body is programmed right after the declaration of this RAII object.
At construction, this RAII object doe the following:
# Check static and non-static class invariants for all overridden bases and for the derived class, by calling [^['typeof](['overridden_base])]`::static_invariant()` __AND__ [^['overridden_base]]`.invariant()` __AND__... [^['typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()`.
# Check preconditions for all overridden base functions and for the overriding derived function in __OR__ with each other, by calling functors [^['f1]]`()` __OR__... [^['fn]]`()` passed to `.precondition(`[^['f1]]`)`, ..., `.precondition(`[^['fn]]`)` for all of the overridden and overriding functions respectively.
At destruction instead:
# Check static and non-static class invariants for all overridden bases and for the derived class, by calling [^['typeof](['overridden_base])]`::static_invariant()` __AND__ [^['overridden_base]]`.invariant()` __AND__... [^['typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()` (even if the function body threw an exception).
# If the function body did not throw an exception:
# Check postconditions for all overridden base functions and for the overriding derived function in __AND__ with each other, by calling functors [^['g1]]`()` __AND__... [^['gn]]`()` passed to `.postcondition(`[^['g1]]`)`, ..., `.postcondition(`[^['gn]]`)` for all of the overridden and overriding functions respectively.
This ensures that overriding public function subcontracts are checked correctly at run-time (see also __Public_Function_Calls__).
This library will generate a compile-time error if there is no suitable virtual function to overload in any of the public base classes (similar to C++11 `override` virtual specifier, but 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]).
[macroref BOOST_CONTRACT_OVERRIDE] does not have to be used in a public section of the class (see also __Access__).
[macroref BOOST_CONTRACT_OVERRIDE] must be used only once in a given class and overloaded functions can reuse it, plus [macroref BOOST_CONTRACT_NAMED_OVERRIDE] can be used to generate a name different from `override_...` (see also __Overloads_and_Named_Override__).
For the rest, the same considerations made in __Virtual_Public_Functions__ apply.
[endsect]
[section Base Types (Subcontracting)]
In order to support subcontracting, this library must be made aware of base classes.
Programmers do that using the [macroref BOOST_CONTRACT_BASE_TYPES] macro to declared a public member type named `base_types` with a `typedef`.
For example (see also [@../../example/features/public.cpp =public.cpp=]):
[public_base_types]
For convenience, a /local macro/ named `BASES` (any other name can be used) is often used here to avoid repeating the base list twice (first when inheriting `: ...` and then when calling [macroref BOOST_CONTRACT_BASE_TYPES]`(...)`).
Being a local macro, `BASES` must be undefined after it has been used to declare `base_types` (to avoid macro redefinition errors).
[macroref BOOST_CONTRACT_BASE_TYPES] is a variadic macro and accepts a list of bases separated by commas (see __No_Macros__ to program `base_types` without using macros).
When the extra base [classref boost::contract::constructor_precondition] is used to program constructor preconditions, it must always be private and appear as the very first base (see also __Constructors__).
[important
Each base passed to [macroref BOOST_CONTRACT_BASE_TYPES] must /explicitly/ specify its inheritance access level `public`, `protected`, or `private` (`virtual` can be specified before or after the access level as usual in C++).
[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__).
Therefore, [macroref BOOST_CONTRACT_BASE_TYPES] inspect each inheritance access level (using preprocessor meta-programming) and strips non-public bases from the `base_types` list of bases to consider for subcontracting.
]
This library will generate a compiler-error if the first base is missing the inheritance access level, but this library is not able to automatically detect if the access level is missing from subsequent bases.
Therefore, 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.
(Note that the inheritance access level is instead optional in C++ because `private` is implicitly assumed for `class` types and `public` for `struct` types.)
]
See __Access__ to avoid making `base_types` a public member type (e.g., in cases when all public members of a class must be controlled exactly).
Set the [macroref BOOST_CONTRACT_CONFIG_BASE_TYPES] configuration macro to use a name different from `base_types` (e.g., because `base_types` clashes with other names in the user-defined class).
[endsect]
[section Private and Protected Functions]
Private and protected member functions do not check class invariants (because they are not part of the public class interface) and they do not subcontract (because they are not accessible at the calling site where the __substitution_principle__ applies, see also __Function_Calls__).
Instead, private and protected member functions only check preconditions and postconditions, like free functions do.
Therefore, [funcref boost::contract::function] is used to program contracts for private and protected functions, like for free functions.
For example (see also [@../../example/features/private_protected.cpp =private_protected.cpp=]):
[import ../../example/features/private_protected.cpp]
[private_protected]
The same considerations made in __Free_Functions__ apply.
[endsect]
[endsect]

0
doc/qbk/release_notes.qbk → doc/release_notes.qbk
View File

603
doc/tutorial.qbk Normal file
View File

@ -0,0 +1,603 @@
[import ../example/features/public.cpp]
[section Tutorial]
This section gives an introduction on how to program contracts using this library.
[section Non-Member Functions]
Consider the following non-member function `inc` which increments its argument `x` by `1` and returns the value `x` had before the increment (this function is equivalent to the usual C++ operation `x++`).
Let's write contracts for `inc` using code comments (see also [@../../example/features/function_comments.cpp =function_comments.cpp=]):
[import ../example/features/function_comments.cpp]
[no_contracts]
The precondition states that the argument to increment must be strictly smaller than the maximum allowable value of its type (to avoid overflow).
The postconditions state that the argument was actually incremented by `1` and that the function return value is equal to the argument before it was incremented.
Now let's program this function and its contract using the [funcref boost::contract::function] function from this library (see also [@../../example/features/function.cpp =function.cpp=]):
[import ../example/features/function.cpp]
[function]
All necessary header files of this library are included by `#include <boost/contract.hpp>`.
Alternatively, programmers can selectively include only the header files they actually need among =boost/contract/*.hpp= (see __Getting_Started__).
It is possible to specify both preconditions and postconditions for non-member functions (see __Preconditions__ and __Postconditions__).
The [funcref boost::contract::function] function returns an RAII object that must always be assigned to a local variable of type [classref boost::contract::guard] otherwise the library will generate a run-time error (note that C++11 `auto` declarations cannot be used here and the [classref boost::contract::guard] type must be explicitly specified).
[footnote
The name of this local variable is arbitrary, but `c` is often used in this documentation.
]
The function body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check preconditions, by calling the nullary functor [^['f]]`()` passed to `.precondition(`[^['f]]`)`.
At destruction instead:
# If the function body did not throw an exception:
# Check postconditions, by calling the nullary functor [^['g]]`()` passed to `.postcondition(`[^['g]]`)`.
This ensures that non-member function contracts are correctly checked at run-time (see __Function_Calls__).
[note
A non-member function can avoid calling [funcref boost::contract::function] for efficiency but only when it has no preconditions and no postconditions.
]
The same considerations also apply to private and protected member functions because their contracts are also programmed using [funcref boost::contract::function] like for non-member functions (see __Private_and_Protected_Functions__).
[endsect]
[section Preconditions]
When preconditions are specified, they are programmed using a functor that can be called with no parameter [^['f]]`()` and it is passed to `.precondition(`[^['f]]`)`.
Contracts that do not have preconditions simply do not call `.precondition(...)`.
When both preconditions and postconditions are specified, preconditions must appear before postconditions (see __Postconditions__).
C++11 lambda functions are very convenient to program preconditions, but any other nullary functor can be used (see also __No_Lambda_Functions__).
[footnote
Lambda functions with no parameters can be programmed in C++11 as `[...] () { ... }` but also equivalently as `[...] { ... }`.
This second from is often used in this documentation omitting the empty parameter list `()` for brevity.
]
For example, for [funcref boost::contract::function] (but same for all other contracts):
boost::contract::guard c = boost::contract::function() // Same for all other contracts.
.precondition([&] { // Capture by reference or value...
BOOST_CONTRACT_ASSERT(...); // ...but should not modify captures.
...
})
...
;
The precondition functor should capture all the variables that it needs to assert the preconditions.
These variables can be captured by value when the overhead of copying such variables is acceptable (but in this documentation preconditions often capture these variables by reference to avoid such overhead).
In any case, precondition assertions should not modify the value of the captured variables, even when those are captured by reference (see __Constant_Correctness__).
Any code can be programmed for 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 slow to execute at run-time).
It is also recommended to use the [macroref BOOST_CONTRACT_ASSERT] macro to program precondition assertions because it enables this library to print very informative error messages when the asserted conditions are evaluated to be false at run-time (this is not a variadic macro, see also __No_Macros__):
BOOST_CONTRACT_ASSERT(``/boolean-condition/``)
// Or, if condition has commas `,` not already within parenthesis `(...)`.
BOOST_CONTRACT_ASSERT((``/boolean-condition/``))
This library will automatically call [funcref boost::contract::precondition_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] macro conditions are `false` and also if the precondition functor throws an exception (by default, this terminates the program calling `std::terminate`, but see __Throw_on_Failure__ to throw exceptions, exit the program with an error code, etc.).
[note
Contracts are most useful when their assertions only use public members that are accessible to the caller so the caller can properly check and use the contract.
In particular, preconditions of a public member function or constructor that use non-public members are essentially incorrect because they cannot be fully checked by the caller (in fact, Eiffel generates a compile-time error in this case).
This library leaves it up to the programmers to only use public members when programming contracts and especially when programming preconditions (see also __Specification_and_Implementation__).
]
[endsect]
[section Postconditions]
When postconditions are specified, they are programmed using a functor that can be called with no parameter [^['g]]`()` and it is passed to `.postcondition(`[^['g]]`)`.
Contracts that do not have postconditions simply do not call `.postcondition(...)`.
When both preconditions and postconditions are specified, postconditions must appear after preconditions (see __Preconditions__).
C++11 lambda functions are very convenient to program postconditions, but any other nullary functor can be used (see also __No_Lambda_Functions__).
For example, for [funcref boost::contract::function] (but same for all other contracts):
boost::contract::guard c = boost::contract::function() // Same for all other contracts.
...
.postcondition([&] { // Capture by reference...
BOOST_CONTRACT_ASSERT(...); // ...but should not modify captures.
...
})
;
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).
Postconditions can also capture return and old values (see __Return_Value__ and __Old_Values__).
In any case, postcondition assertions should not modify the value of the captured variables (see also __Constant_Correctness__).
Any code can be programmed for 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 execute at run-time).
It is also recommended to use the [macroref BOOST_CONTRACT_ASSERT] macro to program postcondition assertions because it enables this library to print very informative error messages when the asserted conditions are evaluated to be false at run-time (this is not a variadic macro, but see also __No_Macros__):
BOOST_CONTRACT_ASSERT(``/boolean-condition/``)
// Or, if condition has commas `,` not already within parenthesis `(...)`.
BOOST_CONTRACT_ASSERT((``/boolean-condition/``))
This library will automatically call [funcref boost::contract::postcondition_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] macro conditions are `false` and also if the postcondition functor throws an exception (by default, this terminates the program calling `std::terminate`, but see __Throw_on_Failure__ to throw exceptions, exit the program with an error code, etc.).
[endsect]
[section Return Value]
In non-void functions, postconditions can access the function return value to program assertions.
In this case, programmers are responsible to declare a local variable before the contract and to assign it to the return value at function exit (when the function does not throw an exception).
[footnote
The name of the local variable that holds the return value is arbitrary, but `result` is often used in this documentation.
]
For example, for [funcref boost::contract::function] (but same for all other contracts):
``/return-type/`` result; // Must be assigned to return value.
boost::contract::guard c = boost::contract::function() // Same for all other contracts.
...
.postcondition([&] { // Also capture `result` reference...
BOOST_CONTRACT_ASSERT(result ...); // ...but should not modify captures.
...
})
;
At any point where the enclosing function returns, programmers are responsible to assign the result variable to the expression being returned.
This can be easily done by making sure that /all/ `return` statements in the function are of the form:
return result = ``/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 return value should never be used in preconditions (because the return value is not yet evaluated and set when preconditions are checked).
In any case, programmers should not modify the result variable in the contract assertions (see also __Constant_Correctness__).
It is also possible to declared the result variables 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 (see __Optional_Return_Value__).
Non-void virtual and overriding public member functions must always declare and use a result variable even when postconditions do not directly use the function return value (so to properly support subcontracting, see __Virtual_Public_Functions__ and __Overriding_Public_Functions__).
[endsect]
[section Old Values]
When old values are used in postconditions, programmes are responsible to declare local variables before the contract and to assign them to related old value expressions using the [macroref BOOST_CONTRACT_OLDOF] macro.
[footnote
The name of the local variable that holds an old value is arbitrary, but [^old_['name]] is often used in this documentation.
]
For example, for [funcref boost::contract::function] (but same for all other contracts):
boost::contract::old_ptr<``/type/``> old_``/name/`` = BOOST_CONTRACT_OLDOF(``/expression/``);
boost::contract::guard c = boost::contract::function() // Same for all other contracts.
...
.postcondition([&] { // Capture by reference...
BOOST_CONTRACT_ASSERT(*old_``/name/`` ...); // ...but should not modify captures.
...
})
;
Old values are handled by this library using the smart pointer class template [classref boost::contract::old_ptr] (so programmers do not directly manage the allocation and deallocation of the pointed memory).
The pointed old value is automatically qualified as `const` (so old values cannot be mistakenly changed by the contract assertions, see also __Constant_Correctness__).
This library ensures that old value pointers are always not null by the time postconditions are checked (so programmers can safely dereference these pointers in postcondition assertions using `operator*` or `operator->` without having to check if old value pointers are not null first).
Old values should never be used in preconditions (because old values are the same as the original values when preconditions are checked).
This library does not even guarantee that old value pointers are not null when precondition functors are called (for example, when postcondition contract checking is disabled using [macroref BOOST_CONTRACT_NO_POSTCONDITONS], when checking an overridden virtual public function contract via subcontracting, etc.).
Finally, see __Old_Values_at_Body__ for delaying the assignment of old values until after preconditions (and possibly class invariants) are checked (this allows to program old value expressions under the simplifying assumption that precondition and class invariant assertions are satisfied already).
The [macroref BOOST_CONTRACT_OLDOF] macro is actually a variadic macro and it takes an extra parameter when used in virtual or overriding public functions (see __Virtual_Public_Functions__ and __Overriding_Public_Functions__).
C++11 auto declarations can be used with [macroref BOOST_CONTRACT_OLDOF] for brevity `auto `[^old_['name] = BOOST_CONTRACT_OLDOF(['expression])].
See __No_Macros__ to program old values without using [macroref BOOST_CONTRACT_OLDOF] (e.g., on compilers that do not support variadic macros).
This library ensures that old values are copied only once and that they are never copied when postcondition contract checking is disabled using [macroref BOOST_CONTRACT_NO_POSTCONDITIONS].
[endsect]
[section Class Invariants]
When class invariants are specified, they are programmed in a public `const` member function named `invariant` taking no argument and returning `void`.
Classes that do not have invariants, simply do not declare the `invariant` member function.
[footnote
This library uses template meta-programming (SFINAE-based introspection techniques) to check invariants only for classes that declare a member function named `invariant`.
]
For example:
class a {
public: // Must be public.
void invariant() const { // Must be const.
BOOST_CONTRACT_ASSERT(...);
...
}
...
};
This member function must be `const` because contracts should not modify the object state (see also __Constant_Correctness__).
This library will generate a compile-time error if the `const` qualifier is missing (unless the [macroref BOOST_CONTRACT_PERMISSIVE] macro 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 execute at run-time).
It is also recommended to use the [macroref BOOST_CONTRACT_ASSERT] macro to program class invariant assertions because it enables this library to print very informative error messages when the asserted conditions are evaluated to be false at run-time (this is not a variadic macro, but see also __No_Macros__):
BOOST_CONTRACT_ASSERT(``/boolean-condition/``)
// Or, if condition has commas `,` not already within parenthesis `(...)`.
BOOST_CONTRACT_ASSERT((``/boolean-condition/``))
This library will automatically call [funcref boost::contract::entry_invariant_failure] or [funcref boost::contract::exit_invariant_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] macro conditions are `false` and also if the `invariant` function throws an exception (by default, this terminates the program calling `std::terminate`, but see __Throw_on_Failure__ to throw exceptions, exit the program with an error code, etc.).
See __Access__ to avoid making the `invariant` member function `public`.
[footnote
In this documentation the `invariant` member function is often declared `public` for simplicity.
However, in most production code it might not be acceptable to augment the public members of a class adding `invariant` and [classref boost::contract::access] can be used to avoid that as explained in __Access__.
]
See the [macroref BOOST_CONTRACT_INVARIANT] macro to use a name different from `invariant` (e.g., because `invariant` clashes with other names in user-defined classes).
[note
No contracts are checked (not event class invariants) when a data member is accessed directly (this is different from Eiffel where even accessing public data members checks class invariants).
Therefore, it might be best for both `class`es and `struct`s that have invariants to have no mutable public data members and to access data members publicly only via appropriate public member functions that can check the class invariants.
]
[heading Static Class Invariants]
When static class invariants are specified, they are programmed in a public `static` member functions named `static_invariant` taking no argument and returning `void`.
Classes that do not have static class invariants, simply do not declare a `static_invariant` member 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 `static_invariant`.
]
For example:
class a {
public: // Must be public.
static void static_invariant() { // Must be static.
BOOST_CONTRACT_ASSERT(...);
...
}
...
};
This member function must be `static` so it correctly cannot access the object `this`.
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 execute at run-time).
It is also recommended to use the [macroref BOOST_CONTRACT_ASSERT] macro to program the assertions because it enables this library to print very informative error messages when the asserted conditions are evaluated to be false at run-time (this is not a variadic macro, but see also __No_Macros__):
BOOST_CONTRACT_ASSERT(``/boolean-condition/``)
// Or, if condition has commas `,` not already within parenthesis `(...)`.
BOOST_CONTRACT_ASSERT((``/boolean-condition/``))
This library will automatically call [funcref boost::contract::entry_invariant_failure] or [funcref boost::contract::exit_invariant_failure] if any of the [macroref BOOST_CONTRACT_ASSERT] macro conditions are `false` and also if the `static_invariant` function throws an exception (by default, this terminates the program calling `std::terminate`, but see __Throw_on_Failure__ to throw exceptions, exit the program with an error code, etc.).
See __Access__ to avoid making `static_invariant` member function `public`.
[footnote
In this documentation the `static_invariant` member function is often declared `public` for simplicity.
However, in most production code it might not be acceptable to augment the public members of a class adding `static_invariant` and [classref boost::contract::access] can be used to avoid that as explained in __Access__.
]
Set the [macroref BOOST_CONTRACT_STATIC_INVARIANT] macro to use a name different from `static_invariant` (e.g., because `static_invariant` clashes with other names in the user-defined class).
[footnote
*Rationale.*
In C++, it is not possible to overload a member function based on the `static` classifier.
Therefore, different function names have to be used for member functions checking static and non-static class invariants, namely `invariant` and `static_invariant`.
]
See __Volatile_Public_Functions__ for programming volatile class invariants.
[endsect]
[section Constructors]
Contracts for constructors are programmed using the [funcref boost::contract::constructor] function and the [classref boost::contract::constructor_precondition] base class.
For example (see also [@../../example/features/public.cpp =public.cpp=]):
[public_constructor]
It is not possible to specify preconditions using `.precondition(...)` for constructors (the 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 (see also __Preconditions__).
Programmes should not access the object `this` from constructor preconditions (because the object does not exists yet before the constructor body is executed, see also __No_Lambda_Functions__).
Constructors without preconditions simply do not explicitly initialize the [classref boost::contract::constructor_precondition] base (because [classref boost::contract::constructor_precondition] default constructor checks no contract).
When [classref boost::contract::constructor_precondition] is used:
* It should be specified as the /first/ class in the inheritance list (so constructor preconditions are checked before initializing any other base or member).
* Its inheritance level should always be `private` (so this extra base class does not alter the public inheritance tree of the derived class).
* It takes the derived class as template parameter (the Curiously Recursive Template Pattern (CRTP) is used here to avoid ambiguity errors with multiple inheritance).
[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 always avoiding base class ambiguities even in case of multiple inheritance.
Virtual inheritance cannot be used resolve such ambiguities because virtual bases are initialized only once by the out-most derived class, and that would not allow to properly check preconditions of all base classes.
]
It is possible to specify postconditions for constructors (see also __Postconditions__).
Programmers should not access the old value of the object `this` in constructor postconditions (because the object did not exist yet before the constructor body was executed, see also __No_Lambda_Functions__).
The [funcref boost::contract::constructor] function takes `this` as a parameter because constructors check class invariants (see also __Class_Invariants__).
The [funcref boost::contract::constructor] function returns an RAII object that must always be assigned to a local variable of type [classref boost::contract::guard] otherwise this library will generate a run-time error (note that C++11 `auto` declarations cannot be used here and the [classref boost::contract::guard] type must be explicitly specified).
The constructor body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()` (but not non-static class invariants because the object does not exists yet).
At destruction instead:
# Check static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()`.
# If the constructor body did not throw an exception:
# Check non-static class invariants, by calling `this->invariant()`.
# Check postconditions, by calling the nullary functor ['[^g]]`()` passed to `.postcondition(`['[^g]]`)`.
This together with C++ object construction mechanism of base classes and the use of [classref boost::contract::constructor_precondition] ensures that the constructor contracts are correctly checked at run-time (see also __Constructor_Calls__).
[note
A constructor can avoid calling [funcref boost::contract::constructor] for efficiency but only when it has no postconditions and its class has no invariants.
(Even if [funcref boost::contract::constuctor] is not used by a derived class, contracts of base classes will still be correctly checked by C++ object construction mechanism.)
]
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 also __Constructor_Calls__).
They could still use [classref boost::contract::constructor_precondition] to check preconditions before member initializations, and use [funcref boost::contract::function] (but not [funcref boost::contract::constructor]) to only check postconditions without checking class invariants (see also __Private_and_Protected_Functions__).
[endsect]
[section Destructors]
Contracts for destructors are programmed using the [funcref boost::contract::destructor] function.
For example (see also [@../../example/features/public.cpp =public.cpp=]):
[public_destructor]
It is not possible to specify preconditions for destructors (the library will generate a compile-time error if `.precondition(...)` is used here because destructors can be called at any time after construction so they have no precondition).
It is possible to specify postconditions for destructors (see also __Postconditions__ for more information and see __Static_Public_Functions__ for an example).
Programmers should not access the object `this` in destructor postconditions (because the object no longer exists after the destructor body has been executed, see also __No_Lambda_Functions__).
The [funcref boost::contract::destructor] function takes `this` as a parameter because destructors check class invariants (see also __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::guard] otherwise this library will generate a run-time error (note that C++11 `auto` declarations cannot be used here and the [classref boost::contract::guard] type must be explicitly specified).
The destructor body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check static and non-static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()`.
At destruction instead:
# Check static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()`.
# If the destructor body threw an exception:
# Check non-static class invariants, by calling `this->invariant()` (because the object was not successfully destructed).
# Else:
# Check postconditions, by calling the nullay functor ['[^g]]`()` passed to `.postcondition(`['[^g]]`)`.
This together with C++ object destruction mechanism of base classes ensures that destructor contracts are correctly checked at run-time (see also __Destructor_Calls__).
[note
A destructor can avoid calling [funcref boost::contract::destructor] for efficiency but only when it has no postconditions and its class has no invariants.
(Even if [funcref boost::contract::destructor] is not used by a derived class, contracts of base classes will still be correctly checked by C++ object destruction mechanism.)
]
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 also __Destructor_Calls__).
They could use [funcref boost::contract::function] (but not [funcref boost::contract::destructor]) to only check postconditions without checking class invariants (see also __Private_and_Protected_Functions__).
[endsect]
[section Public Functions]
Contracts for public member functions are programmed using the [funcref boost::contract::public_function] function.
Let's consider public member functions that are not static, not virtual, and do not override any function from base classes.
For example, the following such a function `find` is declared as a member of the `unique_identifiers` class (see also [@../../example/features/public.cpp =public.cpp=]):
[public_function]
It is possible to specify both preconditions and postconditions for public member functions (see also __Preconditions__ and __Postconditions__).
The [funcref boost::contract::public_function] function takes `this` as a parameter because public member functions check class invariants (see also __Class_Invariants__).
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::guard] otherwise this library will generate a run-time error (note that C++11 `auto` declarations cannot be used here and the [classref boost::contract::guard] type must be explicitly specified).
The public member function body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check static and non-static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()`.
# Check preconditions, by calling the nullary functor ['[^f]]`()` passed to `.precondition(`['[^f]]`)`.
At destruction instead:
# Check static and non-static class invariants, by calling ['[^typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()` (even if the function body threw an exception).
# If the function body did not throw an exception:
# Check postconditions, by calling the nullary functor ['[^g]]`()` passed to `.postcondition(`['[^g]]`)`.
This ensures that public member function contracts are correctly checked at run-time (see also __Public_Function_Calls__).
[note
A public member function can avoid calling [funcref boost::contract::public_function] for efficiency but only when it has no preconditions and no postconditions, it is not virtual, it does not override any virtual function, and its class has no invariant.
]
[endsect]
[section Virtual Public Functions]
Let's consider public member functions that are virtual but that still do not override any function from base classes.
For example, the following such a function `push_back` is declared as a member of the `unique_identifiers` class (see also [@../../example/features/public.cpp =public.cpp=]):
[public_virtual_function]
Public virtual functions must declare an extra trailing parameter of type [classref boost::contract::virtual_]`*` with `0` default value (i.e., `nullptr`).
[footnote
The name of this extra parameter is arbitrary, but `v` is often used in this documentation.
]
This extra parameter is the last parameter and it has a default argument so it does not really alter the calling interface of the virtual function.
Callers will rarely have to explicitly deal with this extra parameter (a part from when manipulating the virtual function type directly as a function pointer, for function pointer type-casts, etc.).
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 virtual function.
[footnote
*Rationale.*
The [classref boost::contract::virtual_]`*` optional parameter is used by this library to determine that a function is virtual (in C++ it is not possible to introspect if a function has been 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, and also to check preconditions and postconditions of overridden virtual functions when subcontracting (but without executing overridden function bodies).
]
The [funcref boost::contract::public_function] function takes `this` as a parameter because public virtual functions check class invariants (see also __Class_Invariants__).
As shown in the example above, when the public virtual function has a non-void return type programmers must pass a reference to the function return value as the second argument to [funcref boost::contract::public_function].
In this case the functor specified to `.postcondition(...)` takes a single parameter for the return value (possibly as a constant reference `const&` to avoid extra copies of the return value).
[footnote
*Rationale.*
The functor passed to `.postcondition(...)` takes the extra return value parameter because that is used by this library to pass the return value evaluated by the overriding function to all its overridden virtual functions when subcontracting.
]
[important
It is the responsibility of the programmers to pass the extra parameter `v` to all [macroref BOOST_CONTRACT_OLDOF] and [funcref boost::contract::public_function] calls within public virtual functions, and also to pass the return value reference after `v` to [funcref boost::contract::public_function] for non-void public virtual functions.
This library cannot automatically generate compile-time errors if programmers fail to do so (but in general contract checking will not correctly work at run-time).
[footnote
*Rationale.*
This library does not require the function type when using [funcref boost::contract::public_function] for non-overriding virtual functions.
Therefore, this library does not know if the enclosing function has a non-void return type so it cannot check if the return value reference is passed as required for non-overriding virtual functions.
Instead this library requires the function type for overriding virtual functions thus it gives a compile-time error if the return value reference is missing in those cases.
]
['Remember: always pass "v" as the first argument to old-of macros, the contract, etc. for public virtual functions; always pass the result variable after "`v`" to the contract for non-void virtual functions.]
]
For the rest, the same considerations made in __Public_Functions__ apply.
[endsect]
[section Public Function Overrides (Subcontracting)]
Let's consider public member functions (virtual or not) that override public virtual functions from one or more public base classes.
For example, the following such a function `push_back` is declared as a member of the `identifiers` derived class and it overrides `push_back` from the `unique_identifiers` base class (see also [@../../example/features/public.cpp =public.cpp=]):
[footnote
In this document, overriding functions are often marked with the comment `/* override */`.
On compilers that support C++11 virtual specifiers, the `override` identifier can be used instead (`override` is not used in the documentation only because virtual specifiers are not widely supported yet, even by compilers that support C++11 lambda functions, etc.).
]
[public_function_override]
The extra `typedef` that uses the [macroref BOOST_CONTRACT_BASE_TYPES] macro is required by this library for derived classes and it is internally used detect base classes for subcontracting (see __Base_Classes__).
When called from overriding public functions, [funcref boost::contract::public_function] takes an explicit template argument `override_`[^['function-name]] that must be defined by:
BOOST_CONTRACT_OVERRIDE(``['function-name]``)
This can be used at any point in the public section of the enclosing class (see __Access__ to use [macroref BOOST_CONTRACT_OVERRIDE] in a non-public section of the class instead).
The [macroref BOOST_CONTRACT_OVERRIDE] macro must be used only once in a class for a given function name and overloaded functions can reuse the same [^override_['function-name]] definition (plus [macroref BOOST_CONTRACT_NAMED_OVERRIDE] can be used to generate a name different than [^override_['function-name]], see also __Overloads_and_Named_Overrides__).
This library will generate a compile-time error if there is no suitable virtual function to override in any of the public base classes.
[footnote
This error is similar in principle to the error generated by 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 valid functions to override for subcontracting.
]
Overriding public functions must always list the extra trailing parameter of type [classref boost::contract::virtual_]`*` with `0` default value (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).
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 overriding function.
When called from overriding public functions, [funcref boost::contract::public_function] also takes a pointer to the enclosing function, the object `this` (because overriding public functions check 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 `bind`'s syntax.
The function pointer and references to all function arguments are needed for overriding virtual public functions 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).
]
As shown in the example above, when the overriding public function has a non-void return type, programmers must pass a reference to the function return value as the second argument to [funcref boost::contract::public_function] (this library will generate a compile-time error otherwise).
[footnote
*Rationale.*
As for non-overriding public virtual functions, also overriding functions use the extra return value parameter to pass it to the overridden functions when subcontracting.
In the case of overriding functions this library also 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 public virtual functions because their contracts do not have to specify the function pointer, see also __Virtual_Public_Functions__).
]
In this case the functor specified to `.postcondition(...)` takes a single parameter for the return value (possibly as a constant reference `const&` to avoid extra copies of the return value).
[important
It is the responsibility of the programmers to pass the extra parameter `v` to all [macroref BOOST_CONTRACT_OLDOF] and [funcref boost::contract::public_function] calls within overriding public functions, and also to pass the return value reference after `v` to [funcref boost::contract::public_function] for non-void overriding public functions.
This library cannot always generate compile-time errors if programmers fail to do so (but in general contract checking will not correctly work at run-time).
['Remember: always pass "v" as the first argument to old-of macros, the contract, etc. for overriding public functions; always pass the result variable after "`v`" to the contract for non-void overriding public functions.]
]
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::guard] otherwise this library will generate a run-time error (note that C++11 `auto` declarations cannot be used here and the [classref boost::const::guard] type must be explicitly specified).
The public member function body is programmed right after the declaration of this RAII object.
At construction, this RAII object doe the following:
# Check static and non-static class invariants for all overridden bases and for the derived class, by calling [^['typeof](['overridden-base])]`::static_invariant()` __AND__ [^['overridden-base]]`.invariant()` __AND__... [^['typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()`.
# Check preconditions for all overridden base functions and for the overriding derived function in __OR__ with each other, by calling the nullary functors [^['f1]]`()` __OR__... [^['fn]]`()` passed to `.precondition(`[^['f1]]`)`, ..., `.precondition(`[^['fn]]`)` for all of the overridden and overriding functions respectively.
At destruction instead:
# Check static and non-static class invariants for all overridden bases and for the derived class, by calling [^['typeof](['overridden-base])]`::static_invariant()` __AND__ [^['overridden-base]]`.invariant()` __AND__... [^['typeof]]`(*this)::static_invariant()` __AND__ `this->invariant()` (even if the function body threw an exception).
# If the function body did not throw an exception:
# Check postconditions for all overridden base functions and for the overriding derived function in __AND__ with each other, by calling the nullary functors [^['g1]]`()` __AND__... [^['gn]]`()` passed to `.postcondition(`[^['g1]]`)`, ..., `.postcondition(`[^['gn]]`)` for all of the overridden and overriding functions respectively.
This ensures that overriding public function subcontracts are checked correctly at run-time (see also __Public_Function_Calls__).
For the rest, the same considerations made in __Public_Virtual_Functions__ apply.
[endsect]
[section Base Classes (Subcontracting)]
In order for this library to support subcontracting, programmers must specify the bases of a class declaring a public member type named `base_types` via a `typedef` using [macroref BOOST_CONTRACT_BASE_TYPES].
For example (see also [@../../example/features/base_types.cpp =base_types.cpp=]):
[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 when inheriting [^: ['base-list]] and then when invoking [macroref 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 macro redefinition errors).
[footnote
In this documentation, the local macro to declare base classes is often named `BASES` but any other name can be used.
]
[macroref BOOST_CONTRACT_BASE_TYPES] is a variadic macro and accepts a list of bases separated by commas (see __No_Macros__ to program `base_types` without using macros).
When the extra base [classref boost::contract::constructor_precondition] is used to program constructor preconditions, it must always be private and appear as the very first base (see also __Constructors__).
[important
Each base passed to [macroref BOOST_CONTRACT_BASE_TYPES] must /explicitly/ specify its inheritance access level `public`, `protected`, or `private` (`virtual` is optional and can be specified either before or after the access level as usual in C++).
[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__).
Therefore, [macroref BOOST_CONTRACT_BASE_TYPES] inspect each inheritance access level (using preprocessor meta-programming) and removes non-public bases from the list bases `base_types` to consider for subcontracting.
]
This library will generate a compiler-error if the first base is missing its inheritance access level, but this library will not be able to error if the access level is missing from bases after the first one.
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).
]
See __Access__ to avoid making `base_types` member type `public` (e.g., in cases when all public members of a class including `typedef`s must be controlled exactly).
Set the [macroref BOOST_CONTRACT_CONFIG_BASE_TYPES] configuration macro to use a name different from `base_types` (e.g., because `base_types` clashes with other names in the user-defined class).
[endsect]
[section Static Public Functions]
Let's consider static public member functions.
For example, the following such a function `instances` is declared as a member of the `make` class template (see also [@../../example/features/static_public.cpp =static_public.cpp=]):
[import ../example/features/static_public.cpp]
[static_public]
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 (necessary to check static class invariants, see also __Static_Class_Invariants__) is specified as an explicit template parameter.
Even if they are not present in the example above, it is possible to specify preconditions and postconditions for static public member functions using `.precondition(...)` and `.postcondition(...)` as usual (see also __Preconditions__ and __Postconditions__).
The [funcref boost::contract::public_function] function returns an RAII object that must be assigned to a local variable of type [classref boost::contract::guard] otherwise this library will generate a run-time error (note that C++11 `auto` declarations cannot be used here and the [classref boost::contract::guard] type must be explicitly specified).
The static public member functions body is programmed right after the declaration of this RAII object.
At construction, this RAII object does the following:
# Check static class invariants, by calling [^['class-type]]`::static_invariant()` (but never non-static class invariants).
# Check preconditions, by calling the nullary functor [^['f]]`()` passed to `.precondition(`[^['f]]`)`.
At destruction instead:
# Check static class invariants, by calling [^['class-type]]`::static_invariant()` (even if the function body threw and exception, but never non-static class invariants).
# If the function body did not throw an exception:
# Check postconditions, by calling the nullary functor [^['g]]`()` passed to `.postcondition(`[^['g]]`)`.
This ensures that static public member function contracts are correctly checked at run-time (note that static public member functions do not subcontract, see also __Public_Function_Calls__).
[note
A static public member function can avoid calling [funcref boost::contract::public_function] for efficiency but only when it has no preconditions, no postconditions, and its class has no static invariants (the class can still have non-static invariants or base classes instead).
]
[endsect]
[section Private and Protected Functions]
Private and protected member functions do not check class invariants (because they are not part of the public class interface) and they do not subcontract (because they are not accessible at the calling site where the __substitution_principle__ applies, see also __Function_Calls__).
However, programmers can still choose to specify preconditions and postconditions for private and protected member functions if they want to check correctness of implementations and usage of base member functions in derived classes.
Therefore, when programmers decide to specify contracts for private and protected member functions, they can use [funcref boost::contract::function] (like for non-member functions).
For example (see also [@../../example/features/private_protected.cpp =private_protected.cpp=]):
[import ../example/features/private_protected.cpp]
[private_protected]
The same considerations made in __Non_Member_Functions__ apply.
See __Constructors__ and __Destructors__ for notes on how to program contracts for private and protected constructors and destructors respectively.
[endsect]
[endsect]

16
example/Jamfile.v2
View File

@ -1,4 +1,16 @@
subdir-usage ;
test-suite features :
[ subdir-run features : introduction ]
[ subdir-run features : function_comments ]
[ subdir-run features : function ]
[ subdir-run features : base_types ]
[ subdir-run features : public ]
[ subdir-run features : static_public ]
[ subdir-run features : private_protected ]
;
test-suite meyer97 :
[ subdir-run meyer97 : stack4_main ]
[ subdir-run meyer97 : stack3 ]
@ -35,7 +47,3 @@ test-suite stroustrup97 :
[ subdir-run stroustrup97 : string ]
;
test-suite doc :
[ subdir-run doc : push_back ]
;

180
example/features/base_types.cpp Normal file
View File

@ -0,0 +1,180 @@
#include <boost/contract.hpp>
#include <cassert>
template<typename T>
class pushable {
public:
void invariant() const {
BOOST_CONTRACT_ASSERT(capacity() <= max_size());
}
virtual void push_back(T x, boost::contract::virtual_* v = 0) = 0;
protected:
virtual int capacity() const = 0;
virtual int max_size() const = 0;
};
template<typename T>
void pushable<T>::push_back(T x, boost::contract::virtual_* v) {
boost::contract::old_ptr<int> old_capacity =
BOOST_CONTRACT_OLDOF(v, capacity());
boost::contract::guard c = boost::contract::public_function(v, this)
.precondition([&] {
BOOST_CONTRACT_ASSERT(capacity() < max_size());
})
.postcondition([&] {
BOOST_CONTRACT_ASSERT(capacity() >= *old_capacity);
})
;
assert(false); // Shall never execute this body.
}
struct has_size { virtual int size() const = 0; };
struct has_empty { virtual bool empty() const = 0; };
class unique_chars
: private boost::contract::constructor_precondition<unique_chars>
{
public:
void invariant() const {
BOOST_CONTRACT_ASSERT(size() >= 0);
}
unique_chars(char from, char to) :
boost::contract::constructor_precondition<unique_chars>([&] {
BOOST_CONTRACT_ASSERT(from <= to);
})
{
boost::contract::guard c = boost::contract::constructor(this)
.postcondition([&] {
BOOST_CONTRACT_ASSERT(size() == (to - from + 1));
})
;
for(char x = from; x <= to; ++x) vect_.push_back(x);
}
virtual ~unique_chars() {
boost::contract::guard c = boost::contract::destructor(this);
}
int size() const {
boost::contract::guard c = boost::contract::public_function(this);
return vect_.size();
}
bool find(char x) const {
bool result;
boost::contract::guard c = boost::contract::public_function(this)
.postcondition([&] {
if(size() == 0) BOOST_CONTRACT_ASSERT(!result);
})
;
return result = std::find(vect_.begin(), vect_.end(), x) != vect_.end();
}
virtual void push_back(char x, boost::contract::virtual_* v = 0) {
boost::contract::old_ptr<bool> old_find =
BOOST_CONTRACT_OLDOF(v, find(x));
boost::contract::old_ptr<int> old_size =
BOOST_CONTRACT_OLDOF(v, size());
boost::contract::guard c = boost::contract::public_function(v, this)
.precondition([&] {
BOOST_CONTRACT_ASSERT(!find(x));
})
.postcondition([&] {
if(!*old_find) {
BOOST_CONTRACT_ASSERT(find(x));
BOOST_CONTRACT_ASSERT(size() == *old_size + 1);
}
})
;
vect_.push_back(x);
}
protected:
unique_chars() {}
std::vector<int> const& vect() const { return vect_; }
private:
std::vector<int> vect_;
};
//[base_types
class chars
#define BASES /* local macro (for convenience) */ \
private boost::contract::constructor_precondition<chars>, \
public unique_chars, public virtual pushable<char>, \
virtual protected has_size, private has_empty
: BASES // Bases of this class.
{
public:
typedef BOOST_CONTRACT_BASE_TYPES(BASES) base_types; // Bases typedef.
#undef BASES // Undefine local macro.
/* ... */
//]
void invariant() const {
BOOST_CONTRACT_ASSERT(empty() == (size() == 0));
}
chars(char from, char to) : unique_chars(from, to) {
boost::contract::guard c = boost::contract::constructor(this);
}
chars(char const* const c_str) :
boost::contract::constructor_precondition<chars>([&] {
BOOST_CONTRACT_ASSERT(c_str[0] != '\0');
})
{
boost::contract::guard c = boost::contract::constructor(this);
for(int i = 0; c_str[i] != '\0'; ++i) push_back(c_str[i]);
}
void push_back(char x, boost::contract::virtual_* v = 0) /* override */ {
boost::contract::old_ptr<bool> old_find =
BOOST_CONTRACT_OLDOF(v, find(x));
boost::contract::old_ptr<int> old_size =
BOOST_CONTRACT_OLDOF(v, size());
boost::contract::guard c = boost::contract::public_function<
override_push_back>(v, &chars::push_back, this, x)
.precondition([&] {
BOOST_CONTRACT_ASSERT(find(x));
})
.postcondition([&] {
if(*old_find) BOOST_CONTRACT_ASSERT(size() == *old_size);
})
;
if(!find(x)) unique_chars::push_back(x);
}
BOOST_CONTRACT_OVERRIDE(push_back);
bool empty() const {
boost::contract::guard c = boost::contract::public_function(this);
return size() == 0;
}
int size() const { return unique_chars::size(); }
protected:
int max_size() const { return vect().max_size(); }
int capacity() const { return vect().capacity(); }
};
int main() {
chars s("aba");
assert(s.find('a'));
assert(s.find('b'));
assert(!s.find('c'));
return 0;
}

21
example/features/free_function.cpp
View File

@ -1,21 +0,0 @@
//[free_function
#include <boost/contract.hpp>
int inc(int& x) {
int result;
boost::shared_ptr<int const> old_x = BOOST_CONTRACT_OLDOF(x);
boost::contract::guard c = boost::contract::function()
.precondition([&] {
BOOST_CONTRACT_ASSERT(x < std::numberic_limits<int>::max());
})
.postcondition([&] {
BOOST_CONTRACT_ASSERT(x == *old_x + 1);
BOOST_CONTRACT_ASSERT(result == *old_x);
})
;
return result = x++; // Function body.
}
//]

31
example/features/function.cpp Normal file
View File

@ -0,0 +1,31 @@
#include <limits>
#include <cassert>
//[function
#include <boost/contract.hpp>
int inc(int& x) {
int result;
boost::contract::old_ptr<int> old_x = BOOST_CONTRACT_OLDOF(x);
boost::contract::guard c = boost::contract::function()
.precondition([&] {
BOOST_CONTRACT_ASSERT(x < std::numeric_limits<int>::max());
})
.postcondition([&] {
BOOST_CONTRACT_ASSERT(x == *old_x + 1);
BOOST_CONTRACT_ASSERT(result == *old_x);
})
;
return result = x++; // Function body.
}
//]
int main() {
int x = std::numeric_limits<int>::max() - 1;
assert(inc(x) == std::numeric_limits<int>::max() - 1);
assert(x == std::numeric_limits<int>::max());
return 0;
}

21
example/features/function_comments.cpp Normal file
View File

@ -0,0 +1,21 @@
#include <limits>
#include <cassert>
//[no_contracts
int inc(int& x)
// Precondition: x < std::numeric_limits<int>::max()
// Postcondition: x == oldof(x) + 1
// result == oldof(x)
{
return x++;
}
//]
int main() {
int x = std::numeric_limits<int>::max() - 1;
assert(inc(x) == std::numeric_limits<int>::max() - 1);
assert(x == std::numeric_limits<int>::max());
return 0;
}

37
example/features/introduction.cpp
View File

@ -4,15 +4,14 @@
// file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt).
// Home at http://www.boost.org/libs/contract
#include <boost/detail/lightweight_test.hpp>
template<typename T>
class pushable;
#include <cassert>
//[introduction
#include <boost/contract.hpp>
#include <vector>
#include <cstddef>
#include <cassert>
template<typename T> class pushable;
template<typename T>
class vector
@ -24,30 +23,30 @@ public:
#undef BASES
void invariant() const { // Checked in AND with base class invariants.
BOOST_CONTRACT_ASSERT(size() <= capacity()); // Line 27.
BOOST_CONTRACT_ASSERT(size() <= capacity()); // Line 25.
}
virtual void push_back(T const& value, boost::contract::virtual_* v = 0)
/* override */ {
boost::contract::old_ptr<std::size_t> old_size =
boost::contract::old_ptr<unsigned> old_size =
BOOST_CONTRACT_OLDOF(v, size()); // Old values.
boost::contract::guard c = boost::contract::public_function<
override_push_back>(v, &vector::push_back, this, value)
.precondition([&] { // Checked in OR with base preconditions.
BOOST_CONTRACT_ASSERT(size() < max_size()); // Line 36.
BOOST_CONTRACT_ASSERT(size() < max_size()); // Line 35.
})
.postcondition([&] { // Checked in AND with base postconditions.
BOOST_CONTRACT_ASSERT(size() == *old_size + 1); // Line 39.
BOOST_CONTRACT_ASSERT(size() == *old_size + 1); // Line 38.
})
;
vect_.push_back(value);
}
BOOST_CONTRACT_OVERRIDE(push_back)
BOOST_CONTRACT_OVERRIDE(push_back) // For `override_push_back`.
std::size_t size() const { return vect_.size(); }
std::size_t max_size() const { return vect_.max_size(); }
std::size_t capacity() const { return vect_.capacity(); }
unsigned size() const { return vect_.size(); }
unsigned max_size() const { return vect_.max_size(); }
unsigned capacity() const { return vect_.capacity(); }
private:
std::vector<T> vect_;
@ -64,13 +63,14 @@ public:
virtual void push_back(T const& value, boost::contract::virtual_* v = 0)
= 0;
virtual std::size_t max_size() const = 0;
virtual std::size_t capacity() const = 0;
protected:
virtual unsigned capacity() const = 0;
virtual unsigned max_size() const = 0;
};
template<typename T> // Contract for pure virtual function.
void pushable<T>::push_back(T const& value, boost::contract::virtual_* v) {
boost::contract::old_ptr<std::size_t> old_capacity =
boost::contract::old_ptr<unsigned> old_capacity =
BOOST_CONTRACT_OLDOF(v, capacity());
boost::contract::guard c = boost::contract::public_function(v, this)
.precondition([&] {
@ -80,12 +80,13 @@ void pushable<T>::push_back(T const& value, boost::contract::virtual_* v) {
BOOST_CONTRACT_ASSERT(capacity() >= *old_capacity);
})
;
assert(false); // Shall never execute this body.
}
int main() {
vector<int> vect;
vect.push_back(123);
BOOST_TEST_EQ(vect.size(), 1);
return boost::report_errors();
assert(vect.size() == 1);
return 0;
}

11
example/features/no_contracts.cpp
View File

@ -1,11 +0,0 @@
//[no_contracts
int inc(int& x)
// Precondition: x < std::numeric_limits<int>::max()
// Postcondition: x == oldof(x) + 1
// result == oldof(x)
{
return x++;
}
//]

48
example/features/private_protected.cpp
View File

@ -1,16 +1,14 @@
#include <boost/contract.hpp>
#include <limits>
#include <cassert>
//[private_protected
template<typename T = int>
class countdwon {
public:
explicit countdown(T n) : n_(n) {}
/* ... */
class counter {
protected:
T get() const { // Protected function (like free functions).
int get() const { // Protected function (like non-member functions).
int result;
auto c = boost::contract::function()
boost::contract::guard c = boost::contract::function()
.postcondition([&] {
BOOST_CONTRACT_ASSERT(result == n_);
})
@ -20,11 +18,11 @@ protected:
}
private:
void dec() { // Private function (like free functions).
auto old_n = BOOST_CONTRACT_OLDOF(n_);
auto c = boost::contract::function()
void dec() { // Private function (like non-member functions).
boost::contract::old_ptr<int> old_n = BOOST_CONTRACT_OLDOF(n_);
boost::contract::guard c = boost::contract::function()
.precondition([&] {
BOOST_CONTRACT_ASSERT(n_ > std::numeric_limit<T>::min());
BOOST_CONTRACT_ASSERT(n_ > std::numeric_limits<int>::min());
})
.postcondition([&] {
BOOST_CONTRACT_ASSERT(n_ == *old_n - 1);
@ -34,7 +32,27 @@ private:
--n_; // Function body.
}
T n_;
};
int n_;
/* ... */
//]
friend struct test_counter;
public:
counter() : n_(0) {}
};
struct test_counter {
static void run() {
counter cnt;
assert(cnt.get() == 0);
cnt.dec();
assert(cnt.get() == -1);
}
};
int main() {
test_counter::run();
return 0;
}

102
example/features/public.cpp
View File

@ -1,4 +1,7 @@
#include <boost/contract.hpp>
#include <cassert>
// Vector of unique integer numbers.
//[public_constructor
// An identifier can be pushed only once in this container.
@ -8,19 +11,19 @@ class unique_identifiers
public:
// Create this container with all identifiers in range [from, to].
unqiue_identifiers(int from, int to) :
unique_identifiers(int from, int to) :
boost::contract::constructor_precondition<unique_identifiers>([&] {
BOOST_CONTRACT_ASSERT(from <= to);
})
{
auto c = boost::contract::constructor(this)
boost::contract::guard c = boost::contract::constructor(this)
.postcondition([&] {
BOOST_CONTRACT_ASSERT(size() == (to - from));
BOOST_CONTRACT_ASSERT(size() == (to - from + 1));
})
;
// Constructor body.
for(id = from; id <= to; ++id) vect_.push_back(id);
for(int id = from; id <= to; ++id) vect_.push_back(id);
}
/* ... */
@ -29,13 +32,16 @@ public:
//[public_destructor
// Destroy this container.
virtual ~unique_identifiers() {
auto c = boost::contract::destructor(this); // Check invariants.
// Destructor body here...
// Following contract checks invariants.
boost::contract::guard c = boost::contract::destructor(this);
// Destructor body here... (do nothing in this example).
}
//]
int size() const {
auto c = boost::contract::public_function(this); // Check invariants.
// Following contract checks invariants.
boost::contract::guard c = boost::contract::public_function(this);
return vect_.size();
}
@ -43,7 +49,7 @@ public:
// Check if specified identifier is in container.
bool find(int id) const {
bool result;
auto c = boost::contract::public_function(this)
boost::contract::guard c = boost::contract::public_function(this)
.postcondition([&] {
if(size() == 0) BOOST_CONTRACT_ASSERT(!result);
})
@ -59,14 +65,17 @@ public:
// Specified identifier must not already be in container.
virtual int push_back(int id, boost::contract::virtual_* v = 0) {
int result;
auto old_find = BOOST_CONTRACT_OLDOF(v, find(id));
auto old_size = BOOST_CONTRACT_OLDOF(v, size());
auto c = boost::contract::public_function(v, result, this)
boost::contract::old_ptr<bool> old_find =
BOOST_CONTRACT_OLDOF(v, find(id)); // Pass `v`.
boost::contract::old_ptr<int> old_size =
BOOST_CONTRACT_OLDOF(v, size()); // Pass `v`.
boost::contract::guard c = boost::contract::public_function(
v, result, this) // Pass `v` and `result`.
.precondition([&] {
BOOST_CONTRACT_ASSERT(!find(id)); // Already in, not allowed.
BOOST_CONTRACT_ASSERT(!find(id));
})
.postcondition([&] (int result) {
if(!*old_find) { // Pushed in container.
if(!*old_find) {
BOOST_CONTRACT_ASSERT(find(id));
BOOST_CONTRACT_ASSERT(size() == *old_size + 1);
}
@ -80,42 +89,41 @@ public:
}
//]
void invariant() const {
BOOST_CONTRACT_ASSERT(size() >= 0);
}
void invariant() const { BOOST_CONTRACT_ASSERT(size() >= 0); }
private:
std::vector<int> vect_;
};
//[public_override_function
//[public_function_override
// Can push same identifier multiple times in container (but with no effect).
class identifiers
#define BASES public unique_identifiers
: BASES
{
public:
typedef BOOST_CONTRACT_BASE_TYPES(BASES) base_types;
typedef BOOST_CONTRACT_BASE_TYPES(BASES) base_types; // Bases typedef.
#undef BASES
void invariant() const { // Check in AND with bases.
BOOST_CONTRACT_ASSERT(empty() == (size() == 0));
}
// Do nothing if specified identifier already in container.
int push_back(int id, boost::contract::virtual_* v = 0) /* override */ {
int result;
auto old_find = BOOST_CONTRACT_OLDOF(v, find(id));
auto old_size = BOOST_CONTRACT_OLDOF(v, size());
auto c = boost::contract::public_function<override_push_back>(
v, result, &identifiers::push_back, this, id)
boost::contract::old_ptr<bool> old_find =
BOOST_CONTRACT_OLDOF(v, find(id));
boost::contract::old_ptr<int> old_size =
BOOST_CONTRACT_OLDOF(v, size());
boost::contract::guard c = boost::contract::public_function<
override_push_back // Pass override plus below function pointer...
>(v, result, &identifiers::push_back, this, id) // ...and arguments.
.precondition([&] { // Check in OR with bases.
BOOST_CONTRACT_ASSERT(find(id)); // Already in, now allowed.
BOOST_CONTRACT_ASSERT(find(id));
})
.postcondition([&] (int result) { // Check in AND with bases.
if(*old_find) { // Not added.
BOOST_CONTRACT_ASSERT(size() == *old_size);
}
if(*old_find) BOOST_CONTRACT_ASSERT(size() == *old_size);
})
;
@ -127,26 +135,32 @@ public:
/* ... */
//]
bool empty() const {
auto c = boost::contract::public_function(this); // Check invariants.
// Following contract checks invariants.
boost::contract::guard c = boost::contract::public_function(this);
return size() == 0;
}
identifiers(int from, int to) : unique_identifiers(from, to) {
// Following contract checks invariants.
boost::contract::guard c = boost::contract::constructor(this);
}
};
int main() {
unique_identifiers uids(1, 4);
assert(uids.find(2));
assert(!uids.find(5));
uids.push_back(5);
assert(uids.find(5));
//[public_base_types
class multi_identifiers
#define BASES \
private boost::contract::constructor_precondition<multi_identifiers>, \
public identifiers, public virtual pushable, \
protected sizer, private capacitor
: BASES
{
public:
typedef BOOST_CONTRACT_BASE_TYPES(BASES) base_types;
#undef BASES
/* ... */
//]
};
identifiers ids(10, 40);
assert(!ids.find(50));
ids.push_back(50);
ids.push_back(50);
assert(ids.find(50));
return 0;
}

49
example/features/static.cpp
View File

@ -1,49 +0,0 @@
#include <boost/contract.hpp>
//[static
template<class C>
class make {
public:
static void static_invariant() { // Static class invariants.
BOOST_CONTRACT_ASSERT(instances() >= 0);
}
static int instances() {
auto c = boost::contract::public_function<make>(); // Check invariants.
return instances_; // Function body.
}
make() : obj_() {
auto old_instances = BOOST_CONTRACT_OLDOF(instances());
auto c = boost::contract::constructor(this)
.postcondition([&] {
BOOST_CONTRACT_OLDOF(instances() == *old_instances + 1);
})
;
++instances_;
}
~make() {
auto old_instances = BOOST_CONTRACT_OLDOF(instances());
auto c = boost::contract::destructor(this)
.postcondition([&] { // (An example of destructor postconditions.)
BOOST_CONTRACT_OLDOF(instances() == *old_instances - 1);
})
;
--instances_;
}
/* ... */
private:
C obj_;
static int instances_;
};
template<class C>
int make<C>::instances_ = 0;
//]

63
example/features/static_public.cpp Normal file
View File

@ -0,0 +1,63 @@
#include <boost/contract.hpp>
#include <cassert>
//[static_public
template<class C>
class make {
public:
static void static_invariant() { // Static class invariants.
BOOST_CONTRACT_ASSERT(instances() >= 0);
}
static int instances() {
// Explicit template parameter `make` (to check static invariants).
boost::contract::guard c = boost::contract::public_function<make>();
return instances_; // Function body.
}
/* ... */
//]
make() : object() {
boost::contract::old_ptr<int> old_instances =
BOOST_CONTRACT_OLDOF(instances());
boost::contract::guard c = boost::contract::constructor(this)
.postcondition([&] {
BOOST_CONTRACT_ASSERT(instances() == *old_instances + 1);
})
;
++instances_;
}
~make() {
boost::contract::old_ptr<int> old_instances =
BOOST_CONTRACT_OLDOF(instances());
boost::contract::guard c = boost::contract::destructor(this)
.postcondition([&] { // (An example of destructor postconditions.)
BOOST_CONTRACT_ASSERT(instances() == *old_instances - 1);
})
;
--instances_;
}
C object;
private:
static int instances_;
};
template<class C>
int make<C>::instances_ = 0;
int main() {
struct x {};
make<x> x1, x2, x3;
assert(make<x>::instances() == 3);
return 0;
}

42
include/boost/contract/call_if.hpp
View File

@ -8,6 +8,7 @@
// See: http://www.boost.org/doc/libs/release/libs/contract/doc/html/index.html
// Do not include all_core_headers here (call_if is essentially standalone).
#include <boost/contract/detail/always_true.hpp>
#include <boost/contract/detail/none.hpp>
#include <boost/make_shared.hpp>
#include <boost/shared_ptr.hpp>
@ -18,11 +19,11 @@
// Boost.ResultOf not always able to deduce lambda result type (on MSVC).
#ifndef BOOST_NO_CXX11_DECL_TYPE
#include <boost/utility/declval.hpp>
#define BOOST_CONTRACT_CALL_IF_ENABLE_IF_UNARY_RESULT_OF_(F) \
#define BOOST_CONTRACT_CALL_IF_RESULT_OF_(F) \
decltype(boost::declval<F>()())
#else
#include <boost/utility/result_of.hpp>
#define BOOST_CONTRACT_CALL_IF_ENABLE_IF_UNARY_RESULT_OF_(F) \
#define BOOST_CONTRACT_CALL_IF_RESULT_OF_(F) \
typename boost::result_of<F()>::type
#endif
@ -31,26 +32,24 @@
namespace boost { namespace contract {
template<bool Cond, typename Then, typename R = boost::contract::detail::none>
class call_if_statement {}; // Empty so cannot be used (but copyable).
struct call_if_statement {}; // Empty so cannot be used (but copyable).
// Dispatch true condition (then) between non-void and void calls.
// IMPORTANT: result_of<Then()> can be evaluated only when condition is already
// checked to be true (as Then() is required to be valid only in that case) so
// this extra level of dispatching is necessary to avoid compiler errors.
template<typename Then>
class call_if_statement<true, Then, boost::contract::detail::none> :
public call_if_statement<true, Then, // Copyable (as its base).
BOOST_CONTRACT_CALL_IF_ENABLE_IF_UNARY_RESULT_OF_(Then)>
struct call_if_statement<true, Then, boost::contract::detail::none> :
call_if_statement<true, Then, // Copyable (as its base).
BOOST_CONTRACT_CALL_IF_RESULT_OF_(Then)>
{
public:
explicit call_if_statement(Then f) : call_if_statement<true, Then,
BOOST_CONTRACT_CALL_IF_ENABLE_IF_UNARY_RESULT_OF_(Then)>(f) {}
BOOST_CONTRACT_CALL_IF_RESULT_OF_(Then)>(f) {}
};
// True condition (then) for non-void call.
template<typename Then, typename R>
class call_if_statement<true, Then, R> { // Copyable (as *).
public:
struct call_if_statement<true, Then, R> { // Copyable (as *).
explicit call_if_statement(Then f) : r_(boost::make_shared<R>(f())) {}
operator R() const { return *r_; }
@ -74,8 +73,7 @@ private:
// True condition (then) for void call.
template<typename Then>
class call_if_statement<true, Then, void> { // Copyable (no data).
public:
struct call_if_statement<true, Then, void> { // Copyable (no data).
explicit call_if_statement(Then f) { f(); }
// Cannot provide `operator R()` here, because R is void.
@ -96,8 +94,7 @@ public:
// False condition (else) for both non-void and void calls.
template<typename Then> // Copyable (no data).
class call_if_statement<false, Then, boost::contract::detail::none> {
public:
struct call_if_statement<false, Then, boost::contract::detail::none> {
explicit call_if_statement(Then const&) {}
// Do not provide `operator result_type()` here, require else_ instead.
@ -106,10 +103,7 @@ public:
// already checked to be false (as Else() is required to be valid only in
// that case) so this is done lazily only in this template instantiation.
template<typename Else>
BOOST_CONTRACT_CALL_IF_ENABLE_IF_UNARY_RESULT_OF_(Else) else_(Else f)
const {
return f();
}
BOOST_CONTRACT_CALL_IF_RESULT_OF_(Else) else_(Else f) const { return f(); }
template<bool ElseIfCond, typename ElseIfThen>
call_if_statement<ElseIfCond, ElseIfThen> else_if_c(ElseIfThen f) const {
@ -133,6 +127,18 @@ call_if_statement<Cond::value, Then> call_if(Then f) {
return call_if_statement<Cond::value, Then>(f);
}
template<bool Cond, typename F>
bool check_if_c(F f) {
return call_if_c<Cond>(f).else_(
boost::contract::detail::always_true());
}
template<class Cond, typename F>
bool check_if(F f) {
return call_if_c<Cond::value>(f).else_(
boost::contract::detail::always_true());
}
} } // namespace
#endif // #include guard

1
include/boost/contract/core/config.hpp
View File

@ -69,6 +69,7 @@
// However, not disabling contract checking while checking preconditions can
// lead to infinite recursive call in user code so by default this macro is
// not defined.
// TODO: Rename this BOOST_CONTRACT_PRECONDITIONS_DISABLE_NO_ASSERTIONS
// BOOST_CONTRACT_PRECONDITIONS_DISABLE_NOTHING
// BOOST_CONTRACT_NO_PRECONDITIONS

4
include/boost/contract/core/set_old_postcondition.hpp
View File

@ -87,10 +87,10 @@ private:
friend class set_precondition_old_postcondition<R>;
template<class CC>
friend set_old_postcondition constructor(CC* oobj);
friend set_old_postcondition<> constructor(CC* oobj);
template<class CC>
friend set_old_postcondition destructor(CC* oobj);
friend set_old_postcondition<> destructor(CC* oobj);
};
} } // namespace

17
include/boost/contract/detail/always_true.hpp Normal file
View File

@ -0,0 +1,17 @@
#ifndef BOOST_CONTRACT_DETAIL_ALWAYS_TRUE_HPP_
#define BOOST_CONTRACT_DETAIL_ALWAYS_TRUE_HPP_
namespace boost { namespace contract { namespace detail {
struct always_true {
template<class> struct result; // To support boost::result_of.
template<class F> struct result<F()> { typedef bool type; };
bool operator()() { return true; }
};
} } } // namespace
#endif // #include guard

84
include/boost/contract/detail/condition/check_pre_post_inv.hpp
View File

@ -105,13 +105,15 @@ public:
protected:
#ifndef BOOST_CONTRACT_NO_ENTRY_INVARIANTS
void check_entry_inv() { check_inv(true, false); }
void check_entry_static_inv() { check_inv(true, true); }
void check_entry_inv() { check_inv(true, false, false); }
void check_entry_static_inv() { check_inv(true, true, false); }
void check_entry_all_inv() { check_inv(true, false, true); }
#endif
#ifndef BOOST_CONTRACT_NO_EXIT_INVARIANTS
void check_exit_inv() { check_inv(false, false); }
void check_exit_static_inv() { check_inv(false, true); }
void check_exit_inv() { check_inv(false, false, false); }
void check_exit_static_inv() { check_inv(false, true, false); }
void check_exit_all_inv() { check_inv(false, false, true); }
#endif
#if !defined(BOOST_CONTRACT_NO_PRECONDITIONS) || \
@ -122,16 +124,20 @@ protected:
private:
#ifndef BOOST_CONTRACT_NO_INVARIANTS
void check_inv(bool on_entry, bool static_inv_only) {
void check_inv(bool on_entry, bool static_only, bool both_const_cv) {
if(this->failed()) return;
try {
// Static members only check static inv.
check_static_inv<C>();
if(!static_inv_only) {
// Volatile (const or not) members check static and cv inv.
check_cv_inv<C>();
// Other members (const or not) check static, cv, and const.
check_const_inv<C>();
if(!static_only) {
if(both_const_cv) {
check_cv_inv<C>();
check_const_inv<C>();
} else if(boost::is_volatile<C>::value) {
check_cv_inv<C>();
} else {
check_const_inv<C>();
}
}
} catch(...) {
if(on_entry) {
@ -139,7 +145,32 @@ private:
} else this->fail(&boost::contract::exit_invariant_failure);
}
}
template<class C_>
typename boost::disable_if<
boost::contract::access::has_const_invariant<C_> >::type
check_const_inv() {}
template<class C_>
typename boost::enable_if<
boost::contract::access::has_const_invariant<C_> >::type
check_const_inv() { boost::contract::access::const_invariant(obj_); }
template<class C_>
typename boost::disable_if<
boost::contract::access::has_cv_invariant<C_> >::type
check_cv_inv() {}
template<class C_>
typename boost::enable_if<
boost::contract::access::has_cv_invariant<C_> >::type
check_cv_inv() { boost::contract::access::cv_invariant(obj_); }
template<class C_>
typename boost::disable_if<
boost::contract::access::has_static_invariant<C_> >::type
check_static_inv() {}
template<class C_>
typename boost::enable_if<
boost::contract::access::has_static_invariant<C_> >::type
@ -152,39 +183,6 @@ private:
}
}
template<class C_>
typename boost::disable_if<
boost::contract::access::has_static_invariant<C_> >::type
check_static_inv() {}
template<class C_>
typename boost::enable_if<
boost::contract::access::has_cv_invariant<C_> >::type
check_cv_inv() { boost::contract::access::cv_invariant(obj_); }
template<class C_>
typename boost::disable_if<
boost::contract::access::has_cv_invariant<C_> >::type
check_cv_inv() {}
template<class C_>
struct call_const_inv :
boost::mpl::and_<
boost::contract::access::has_const_invariant<C_>,
// Volatile (like const) cannot be stripped so [const] volatile
// members only check cv invariant, and cannot check const inv.
boost::mpl::not_<boost::is_volatile<C_> >
>
{};
template<class C_>
typename boost::enable_if<call_const_inv<C_> >::type
check_const_inv() { boost::contract::access::const_invariant(obj_); }
template<class C_>
typename boost::disable_if<call_const_inv<C_> >::type
check_const_inv() {}
// Check is class's func is inherited from its base types or not.
template<template<class> class HasFunc, template<class> class FuncAddr>
struct inherited {

2
include/boost/contract/detail/operation/constructor.hpp
View File

@ -64,7 +64,7 @@ public:
#ifndef BOOST_CONTRACT_NO_EXIT_INVARIANTS
if(body_threw) this->check_exit_static_inv();
else this->check_exit_inv();
else this->check_exit_all_inv();
#endif
#ifndef BOOST_CONTRACT_NO_POSTCONDITIONS
if(!body_threw) this->check_post(none());

4
include/boost/contract/detail/operation/destructor.hpp
View File

@ -41,7 +41,7 @@ private:
{
check_guard checking;
// Obj exists (before dtor body), check static and non- inv.
this->check_entry_inv();
this->check_entry_all_inv();
// Dtor cannot have pre because it has no parameters.
}
#endif
@ -71,7 +71,7 @@ public:
bool body_threw = std::uncaught_exception();
#ifndef BOOST_CONTRACT_NO_EXIT_INVARIANTS
if(body_threw) this->check_exit_inv();
if(body_threw) this->check_exit_all_inv();
else this->check_exit_static_inv();
#endif
#ifndef BOOST_CONTRACT_NO_POSTCONDITIONS

278
test/Jamfile.v2
View File

@ -3,39 +3,39 @@ subdir-usage ;
test-suite constructor
:
[ subdir-run-aliased constructor : decl_pre_all ]
[ subdir-run-aliased constructor : decl_pre_ends ]
[ subdir-run-aliased constructor : decl_pre_mid ]
[ subdir-run-aliased constructor : decl_pre_none ]
[ subdir-run-with-no constructor : decl_pre_all ]
[ subdir-run-with-no constructor : decl_pre_ends ]
[ subdir-run-with-no constructor : decl_pre_mid ]
[ subdir-run-with-no constructor : decl_pre_none ]
[ subdir-run-aliased constructor : decl_post_all ]
[ subdir-run-aliased constructor : decl_post_ends ]
[ subdir-run-aliased constructor : decl_post_mid ]
[ subdir-run-aliased constructor : decl_post_none ]
[ subdir-run-with-no constructor : decl_post_all ]
[ subdir-run-with-no constructor : decl_post_ends ]
[ subdir-run-with-no constructor : decl_post_mid ]
[ subdir-run-with-no constructor : decl_post_none ]
[ subdir-run-aliased constructor : decl_entry_static_inv_all ]
[ subdir-run-aliased constructor : decl_entry_static_inv_ends ]
[ subdir-run-aliased constructor : decl_entry_static_inv_mid ]
[ subdir-run-aliased constructor : decl_entry_static_inv_none ]
[ subdir-run-with-no constructor : decl_entry_static_inv_all ]
[ subdir-run-with-no constructor : decl_entry_static_inv_ends ]
[ subdir-run-with-no constructor : decl_entry_static_inv_mid ]
[ subdir-run-with-no constructor : decl_entry_static_inv_none ]
[ subdir-run-aliased constructor : decl_exit_static_inv_all ]
[ subdir-run-aliased constructor : decl_exit_static_inv_ends ]
[ subdir-run-aliased constructor : decl_exit_static_inv_mid ]
[ subdir-run-aliased constructor : decl_exit_static_inv_none ]
[ subdir-run-with-no constructor : decl_exit_static_inv_all ]
[ subdir-run-with-no constructor : decl_exit_static_inv_ends ]
[ subdir-run-with-no constructor : decl_exit_static_inv_mid ]
[ subdir-run-with-no constructor : decl_exit_static_inv_none ]
# No decl_entry_static_inv_... for constructors.
[ subdir-run-aliased constructor : decl_exit_inv_all ]
[ subdir-run-aliased constructor : decl_exit_inv_ends ]
[ subdir-run-aliased constructor : decl_exit_inv_mid ]
[ subdir-run-aliased constructor : decl_exit_inv_none ]
[ subdir-run-with-no constructor : decl_exit_inv_all ]
[ subdir-run-with-no constructor : decl_exit_inv_ends ]
[ subdir-run-with-no constructor : decl_exit_inv_mid ]
[ subdir-run-with-no constructor : decl_exit_inv_none ]
[ subdir-run-aliased constructor : contracts ]
[ subdir-run-aliased constructor : access ]
[ subdir-run-aliased constructor : ifdef_contracts ]
[ subdir-run-with-no constructor : contracts ]
[ subdir-run-with-no constructor : access ]
[ subdir-run-with-no constructor : ifdef_contracts ]
[ subdir-run-aliased constructor : body_throw ]
[ subdir-run-aliased constructor : old_throw ]
[ subdir-run-with-no constructor : body_throw ]
[ subdir-run-with-no constructor : old_throw ]
[ subdir-compile-fail constructor : pre_error ]
;
@ -44,193 +44,193 @@ test-suite destructor
:
# No decl_pre_... for destructors.
[ subdir-run-aliased destructor : decl_post_all ]
[ subdir-run-aliased destructor : decl_post_ends ]
[ subdir-run-aliased destructor : decl_post_mid ]
[ subdir-run-aliased destructor : decl_post_none ]
[ subdir-run-with-no destructor : decl_post_all ]
[ subdir-run-with-no destructor : decl_post_ends ]
[ subdir-run-with-no destructor : decl_post_mid ]
[ subdir-run-with-no destructor : decl_post_none ]
[ subdir-run-aliased destructor : decl_entry_static_inv_all ]
[ subdir-run-aliased destructor : decl_entry_static_inv_ends ]
[ subdir-run-aliased destructor : decl_entry_static_inv_mid ]
[ subdir-run-aliased destructor : decl_entry_static_inv_none ]
[ subdir-run-with-no destructor : decl_entry_static_inv_all ]
[ subdir-run-with-no destructor : decl_entry_static_inv_ends ]
[ subdir-run-with-no destructor : decl_entry_static_inv_mid ]
[ subdir-run-with-no destructor : decl_entry_static_inv_none ]
[ subdir-run-aliased destructor : decl_exit_static_inv_all ]
[ subdir-run-aliased destructor : decl_exit_static_inv_ends ]
[ subdir-run-aliased destructor : decl_exit_static_inv_mid ]
[ subdir-run-aliased destructor : decl_exit_static_inv_none ]
[ subdir-run-with-no destructor : decl_exit_static_inv_all ]
[ subdir-run-with-no destructor : decl_exit_static_inv_ends ]
[ subdir-run-with-no destructor : decl_exit_static_inv_mid ]
[ subdir-run-with-no destructor : decl_exit_static_inv_none ]
[ subdir-run-aliased destructor : decl_entry_inv_all ]
[ subdir-run-aliased destructor : decl_entry_inv_ends ]
[ subdir-run-aliased destructor : decl_entry_inv_mid ]
[ subdir-run-aliased destructor : decl_entry_inv_none ]
[ subdir-run-with-no destructor : decl_entry_inv_all ]
[ subdir-run-with-no destructor : decl_entry_inv_ends ]
[ subdir-run-with-no destructor : decl_entry_inv_mid ]
[ subdir-run-with-no destructor : decl_entry_inv_none ]
# No decl_exit_inv_... for destructors.
[ subdir-run-aliased destructor : contracts ]
[ subdir-run-aliased destructor : access ]
[ subdir-run-aliased destructor : ifdef_contracts ]
[ subdir-run-with-no destructor : contracts ]
[ subdir-run-with-no destructor : access ]
[ subdir-run-with-no destructor : ifdef_contracts ]
[ subdir-run-aliased destructor : body_throw ]
[ subdir-run-aliased destructor : old_throw ]
[ subdir-run-with-no destructor : body_throw ]
[ subdir-run-with-no destructor : old_throw ]
[ subdir-compile-fail destructor : pre_error ]
;
test-suite public_function
:
[ subdir-run-aliased public_function : decl_pre_all ]
[ subdir-run-aliased public_function : decl_pre_ends ]
[ subdir-run-aliased public_function : decl_pre_mid ]
[ subdir-run-aliased public_function : decl_pre_none ]
[ subdir-run-with-no public_function : decl_pre_all ]
[ subdir-run-with-no public_function : decl_pre_ends ]
[ subdir-run-with-no public_function : decl_pre_mid ]
[ subdir-run-with-no public_function : decl_pre_none ]
[ subdir-run-aliased public_function : decl_post_all ]
[ subdir-run-aliased public_function : decl_post_ends ]
[ subdir-run-aliased public_function : decl_post_mid ]
[ subdir-run-aliased public_function : decl_post_none ]
[ subdir-run-with-no public_function : decl_post_all ]
[ subdir-run-with-no public_function : decl_post_ends ]
[ subdir-run-with-no public_function : decl_post_mid ]
[ subdir-run-with-no public_function : decl_post_none ]
[ subdir-run-aliased public_function : decl_entry_static_inv_all ]
[ subdir-run-aliased public_function : decl_entry_static_inv_ends ]
[ subdir-run-aliased public_function : decl_entry_static_inv_mid ]
[ subdir-run-aliased public_function : decl_entry_static_inv_none ]
[ subdir-run-with-no public_function : decl_entry_static_inv_all ]
[ subdir-run-with-no public_function : decl_entry_static_inv_ends ]
[ subdir-run-with-no public_function : decl_entry_static_inv_mid ]
[ subdir-run-with-no public_function : decl_entry_static_inv_none ]
[ subdir-run-aliased public_function : decl_exit_static_inv_all ]
[ subdir-run-aliased public_function : decl_exit_static_inv_ends ]
[ subdir-run-aliased public_function : decl_exit_static_inv_mid ]
[ subdir-run-aliased public_function : decl_exit_static_inv_none ]
[ subdir-run-with-no public_function : decl_exit_static_inv_all ]
[ subdir-run-with-no public_function : decl_exit_static_inv_ends ]
[ subdir-run-with-no public_function : decl_exit_static_inv_mid ]
[ subdir-run-with-no public_function : decl_exit_static_inv_none ]
[ subdir-run-aliased public_function : decl_entry_inv_all ]
[ subdir-run-aliased public_function : decl_entry_inv_ends ]
[ subdir-run-aliased public_function : decl_entry_inv_mid ]
[ subdir-run-aliased public_function : decl_entry_inv_none ]
[ subdir-run-with-no public_function : decl_entry_inv_all ]
[ subdir-run-with-no public_function : decl_entry_inv_ends ]
[ subdir-run-with-no public_function : decl_entry_inv_mid ]
[ subdir-run-with-no public_function : decl_entry_inv_none ]
[ subdir-run-aliased public_function : decl_exit_inv_all ]
[ subdir-run-aliased public_function : decl_exit_inv_ends ]
[ subdir-run-aliased public_function : decl_exit_inv_mid ]
[ subdir-run-aliased public_function : decl_exit_inv_none ]
[ subdir-run-with-no public_function : decl_exit_inv_all ]
[ subdir-run-with-no public_function : decl_exit_inv_ends ]
[ subdir-run-with-no public_function : decl_exit_inv_mid ]
[ subdir-run-with-no public_function : decl_exit_inv_none ]
[ subdir-run-aliased public_function : contracts ]
[ subdir-run-with-no public_function : contracts ]
[ subdir-run-aliased public_function : virtual ]
[ subdir-run-aliased public_function : virtual_branch ]
[ subdir-run-aliased public_function : virtual_sparse ]
[ subdir-run-with-no public_function : virtual ]
[ subdir-run-with-no public_function : virtual_branch ]
[ subdir-run-with-no public_function : virtual_sparse ]
[ subdir-run-aliased public_function : protected ]
[ subdir-run-with-no public_function : protected ]
[ subdir-compile-fail public_function : protected_error ]
[ subdir-run-aliased public_function : access ]
[ subdir-run-aliased public_function : ifdef_contracts ]
[ subdir-run-with-no public_function : access ]
[ subdir-run-with-no public_function : ifdef_contracts ]
[ subdir-run-aliased public_function : body_throw ]
[ subdir-run-aliased public_function : old_throw ]
[ subdir-run-with-no public_function : body_throw ]
[ subdir-run-with-no public_function : old_throw ]
[ subdir-run-aliased public_function : max_args0 ]
[ subdir-run-aliased public_function : max_args0_no_tva ]
[ subdir-run-aliased public_function : max_args1 ]
[ subdir-run-aliased public_function : max_args1_no_tva ]
[ subdir-run-aliased public_function : max_args2 ]
[ subdir-run-aliased public_function : max_args2_no_tva ]
[ subdir-run-aliased public_function : max_args ]
[ subdir-run-aliased public_function : max_args_no_tva ]
[ subdir-run-with-no public_function : max_args0 ]
[ subdir-run-with-no public_function : max_args0_no_tva ]
[ subdir-run-with-no public_function : max_args1 ]
[ subdir-run-with-no public_function : max_args1_no_tva ]
[ subdir-run-with-no public_function : max_args2 ]
[ subdir-run-with-no public_function : max_args2_no_tva ]
[ subdir-run-with-no public_function : max_args ]
[ subdir-run-with-no public_function : max_args_no_tva ]
[ subdir-run-aliased public_function : max_bases ]
[ subdir-run-with-no public_function : max_bases ]
[ subdir-run-aliased public_function : overload ]
[ subdir-run-aliased public_function : overload_no_tva ]
[ subdir-run-with-no public_function : overload ]
[ subdir-run-with-no public_function : overload_no_tva ]
[ subdir-compile-fail public_function : override_error ]
[ subdir-run-aliased public_function : override_permissive ]
[ subdir-run-with-no public_function : override_permissive ]
[ subdir-run-aliased public_function : static ]
[ subdir-run-aliased public_function : static_body_throw ]
[ subdir-run-aliased public_function : static_old_throw ]
[ subdir-run-aliased public_function : static_no_contracts ]
[ subdir-run-with-no public_function : static ]
[ subdir-run-with-no public_function : static_body_throw ]
[ subdir-run-with-no public_function : static_old_throw ]
[ subdir-run-with-no public_function : static_no_contracts ]
;
test-suite invariant
:
[ subdir-run-aliased invariant : decl_static_cv_const ]
[ subdir-run-aliased invariant : decl_static_cv ]
[ subdir-run-aliased invariant : decl_cv_const ]
[ subdir-run-aliased invariant : decl_static_const ]
[ subdir-run-aliased invariant : decl_static ]
[ subdir-run-aliased invariant : decl_cv ]
[ subdir-run-aliased invariant : decl_const ]
[ subdir-run-aliased invariant : decl_nothing ]
[ subdir-run-with-no invariant : decl_static_cv_const ]
[ subdir-run-with-no invariant : decl_static_cv ]
[ subdir-run-with-no invariant : decl_cv_const ]
[ subdir-run-with-no invariant : decl_static_const ]
[ subdir-run-with-no invariant : decl_static ]
[ subdir-run-with-no invariant : decl_cv ]
[ subdir-run-with-no invariant : decl_const ]
[ subdir-run-with-no invariant : decl_nothing ]
[ subdir-compile-fail invariant : static_mutable_error ]
[ subdir-run-aliased invariant : static_mutable_permissive ]
[ subdir-run-with-no invariant : static_mutable_permissive ]
[ subdir-compile-fail invariant : static_const_error ]
[ subdir-run-aliased invariant : static_const_permissive ]
[ subdir-run-with-no invariant : static_const_permissive ]
[ subdir-compile-fail invariant : static_volatile_error ]
[ subdir-run-aliased invariant : static_volatile_permissive ]
[ subdir-run-with-no invariant : static_volatile_permissive ]
[ subdir-compile-fail invariant : static_cv_error ]
[ subdir-run-aliased invariant : static_cv_permissive ]
[ subdir-run-with-no invariant : static_cv_permissive ]
[ subdir-compile-fail invariant : static_error ]
[ subdir-run-aliased invariant : static_permissive ]
[ subdir-run-with-no invariant : static_permissive ]
[ subdir-compile-fail invariant : mutable_error ]
[ subdir-run-aliased invariant : mutable_permissive ]
[ subdir-run-with-no invariant : mutable_permissive ]
[ subdir-compile-fail invariant : volatile_error ]
[ subdir-run-aliased invariant : volatile_permissive ]
[ subdir-run-with-no invariant : volatile_permissive ]
;
test-suite function
:
[ subdir-run-aliased function : decl_pre_all ]
[ subdir-run-aliased function : decl_pre_none ]
[ subdir-run-with-no function : decl_pre_all ]
[ subdir-run-with-no function : decl_pre_none ]
[ subdir-run-aliased function : decl_post_all ]
[ subdir-run-aliased function : decl_post_none ]
[ subdir-run-with-no function : decl_post_all ]
[ subdir-run-with-no function : decl_post_none ]
[ subdir-run-aliased function : contracts ]
[ subdir-run-aliased function : ifdef_contracts ]
[ subdir-run-with-no function : contracts ]
[ subdir-run-with-no function : ifdef_contracts ]
[ subdir-run-aliased function : body_throw ]
[ subdir-run-aliased function : old_throw ]
[ subdir-run-with-no function : body_throw ]
[ subdir-run-with-no function : old_throw ]
;
test-suite result
:
[ subdir-run-aliased result : mixed_optional ]
[ subdir-run-aliased result : mixed_optional_ref ]
[ subdir-run-with-no result : mixed_optional ]
[ subdir-run-with-no result : mixed_optional_ref ]
[ subdir-compile-fail result : type_mismatch_error ]
;
test-suite old
:
[ subdir-run-aliased old : auto ]
[ subdir-run-with-no old : auto ]
[ subdir-run-aliased old : no_macros ]
[ subdir-run-with-no old : no_macros ]
[ subdir-compile-fail old : no_make_old_error ]
[ subdir-run-aliased old : noncopyable ]
[ subdir-run-with-no old : noncopyable ]
[ subdir-compile-fail old : noncopyable_error ]
[ subdir-run-aliased old : no_equal ]
[ subdir-run-with-no old : no_equal ]
[ subdir-compile-fail old : no_equal_error ]
;
test-suite union
:
[ subdir-run-aliased union : contracts ]
[ subdir-run-with-no union : contracts ]
;
test-suite move
:
[ subdir-run-aliased move : contracts ]
[ subdir-run-with-no move : contracts ]
;
test-suite disable
:
[ subdir-run-aliased disable : prog ]
[ subdir-run-aliased disable : prog_pre_disable_nothing ]
[ subdir-run-with-no disable : prog ]
[ subdir-run-with-no disable : prog_pre_disable_nothing ]
[ subdir-lib disable : lib_a :
<link>shared:<define>BOOST_CONTRACT_TEST_LIB_A_DYN_LINK ]
[ subdir-lib disable : lib_b : <library>disable-lib_a
<link>shared:<define>BOOST_CONTRACT_TEST_LIB_B_DYN_LINK ]
[ subdir-run-aliased disable : lib_ab :
[ subdir-run-with-no disable : lib_ab :
<library>disable-lib_a <library>disable-lib_b ]
[
@ -248,22 +248,22 @@ test-suite disable
# Test contracts in .hpp so can have post (even if NO_POST here).
<define>BOOST_CONTRACT_NO_POSTCONDITIONS
]
[ subdir-run-aliased disable : lib_xy :
[ subdir-run-with-no disable : lib_xy :
<library>disable-lib_x <library>disable-lib_y ]
;
test-suite set
:
[ subdir-run-aliased set : pre_old_post ]
[ subdir-run-aliased set : pre_old ]
[ subdir-run-aliased set : old_post ]
[ subdir-run-aliased set : pre_post ]
[ subdir-run-aliased set : pre ]
[ subdir-run-aliased set : old ]
[ subdir-run-aliased set : post ]
[ subdir-run-aliased set : nothing ]
[ subdir-run-with-no set : pre_old_post ]
[ subdir-run-with-no set : pre_old ]
[ subdir-run-with-no set : old_post ]
[ subdir-run-with-no set : pre_post ]
[ subdir-run-with-no set : pre ]
[ subdir-run-with-no set : old ]
[ subdir-run-with-no set : post ]
[ subdir-run-with-no set : nothing ]
[ subdir-run-aliased set : no_guard ]
[ subdir-run-with-no set : no_guard ]
[ subdir-compile-fail set : old_pre_error ]
[ subdir-compile-fail set : post_old_error ]