Macro BOOST_CONTRACT_PUBLIC

Macro BOOST_CONTRACT_PUBLIC_FUNCTION

BOOST_CONTRACT_PUBLIC_FUNCTION — Program contracts that can be completely disabled at compile-time for non-static public functions that do not override.

Synopsis

// In header: <boost/contract_macro.hpp>

BOOST_CONTRACT_PUBLIC_FUNCTION(...)

Description

This is used together with BOOST_CONTRACT_PRECONDITION, BOOST_CONTRACT_POSTCONDITION, BOOST_CONTRACT_EXCEPT, and BOOST_CONTRACT_OLD to specify preconditions, postconditions, exception guarantees, and old value copies at body that can be completely disabled at compile-time for non-static public functions (virtual or not, void or not) that do not override:

class u {
    friend class boost::contract::access;

    BOOST_CONTRACT_INVARIANT({ // Optional (as for static and volatile).
        BOOST_CONTRACT_ASSERT(...);
        ...
    })

public:
    // Non-virtual (same if void).
    t f(...) {
        t result;
        BOOST_CONTRACT_OLD_PTR(old_type)(old_var);
        BOOST_CONTRACT_PUBLIC_FUNCTION(this)
            BOOST_CONTRACT_PRECONDITION([&] { // Optional.
                BOOST_CONTRACT_ASSERT(...);
                ...
            })
            BOOST_CONTRACT_OLD([&] { // Optional.
                old_var = BOOST_CONTRACT_OLDOF(old_expr);
                ...
            })
            BOOST_CONTRACT_POSTCONDITION([&] { // Optional.
                BOOST_CONTRACT_ASSERT(...);
                ...
            })
            BOOST_CONTRACT_EXCEPT([&] { // Optional.
                BOOST_CONTRACT_ASSERT(...);
                ...
            })
        ;

        ... // Function body (use `return result = return_expr`).
    }
    
    // Virtual and void.
    virtual void g(..., boost::contract::virtual_* v = 0) {
        BOOST_CONTRACT_OLD_PTR(old_type)(old_var);
        BOOST_CONTRACT_PUBLIC_FUNCTION(v, this)
            ...
            BOOST_CONTRACT_OLD([&] { // Optional.
                old_var = BOOST_CONTRACT_OLDOF(v, old_expr);
                ...
            })
            ...
        ;
        
        ... // Function body.
    }
    
    // Virtual and non-void.
    virtual t h(..., boost::contract::virtual_* v = 0) {
        t result;
        BOOST_CONTRACT_OLD_PTR(old_type)(old_var);
        BOOST_CONTRACT_PUBLIC_FUNCTION(v, result, this)
            ...
            BOOST_CONTRACT_OLD([&] { // Optional.
                old_var = BOOST_CONTRACT_OLDOF(v, old_expr);
                ...
            })
            BOOST_CONTRACT_POSTCONDITION([&] (t const& result) { // Optional
                BOOST_CONTRACT_ASSERT(...);
                ...
            })
            ...
        ;
        
        ... // Function body (use `return result = return_expr`).
    }
    
    ...
};

For optimization, this can be omitted for non-virtual public functions that do not have preconditions, postconditions and exception guarantees, within classes that have no invariants. Virtual public functions should always use BOOST_CONTRACT_PUBLIC_FUNCTION otherwise this library will not be able to correctly use them for subcontracting.

This is an overloaded variadic macro and it can be used in the following different ways (note that no code is generated when BOOST_CONTRACT_NO_PUBLIC_FUNCTIONS is defined).

1. BOOST_CONTRACT_PUBLIC_FUNCTION(obj) expands to code equivalent to the following (for non-virtual public functions that are not static and do not override, returning void or not):

#ifndef BOOST_CONTRACT_NO_PUBLIC_FUNCTIONS
    boost::contract::check internal_var =
            boost::contract::public_function(obj)
#endif

2. BOOST_CONTRACT_PUBLIC_FUNCTION(v, obj) expands to code equivalent to the following (for virtual public functions that are not static and do not override, returning void):

#ifndef BOOST_CONTRACT_NO_PUBLIC_FUNCTIONS
    boost::contract::check internal_var =
            boost::contract::public_function(v, obj)
#endif

3. BOOST_CONTRACT_PUBLIC_FUNCTION(v, r, obj) expands to code equivalent to the following (for virtual public functions that are not static and do not override, not returning void):

#ifndef BOOST_CONTRACT_NO_PUBLIC_FUNCTIONS
    boost::contract::check internal_var =
            boost::contract::public_function(v, r, obj)
#endif

Where (these are all variadic macro parameters so they can contain commas not protected by round parenthesis):

v is the extra parameter of type boost::contract::virtual_* and default value 0 from the enclosing virtual public function declaring the contract.
r is a reference to the return value of the enclosing virtual public function declaring the contract. This is usually a local variable declared by the enclosing virtual public function just before the contract, but programmers must set it to the actual value being returned by the function at each return statement.
obj is the object this from the scope of the enclosing public function declaring the contract. This object might be mutable, const, volatile, or const volatile depending on the cv-qualifier of the enclosing function (volatile public functions will check volatile class invariants, see Volatile Public Functions).
internal_var is a variable name internally generated by this library (this name is unique but only on different line numbers so this macro cannot be expanded multiple times on the same line).