| Home | Libraries | People | FAQ | More

## Function template public_function

boost::contract::public_function — Program contracts for non-void public functions overrides (virtual or not).

## Synopsis

    // In header: <boost/contract/public_function.hpp>

    template<typename Override, typename VirtualResult, typename F,
             typename Class, typename... Args>
      specify_precondition_old_postcondition_except< VirtualResult >
      public_function(virtual_ * v, VirtualResult & r, F f, Class * obj,
                      Args &... args);

## Description

This is used to specify preconditions, postconditions, exception guarantees, old value copies at body, and check class invariants for public function overrides (virtual or not) that do not return `void:`

    class u
        #define BASES private boost::contract::constructor_precondition<u>, \
                public b, private w
        : BASES
    {
        friend class boost::contract::access;

        typedef BOOST_CONTRACT_BASE_TYPES(BASES) base_types;
        #undef BASES

        void invariant() const { // Optional (as for static and volatile).
            BOOST_CONTRACT_ASSERT(...);
            ...
        }

        BOOST_CONTRACT_OVERRIDES(f)

    public:
        // Override from `b::f`.
        t f(t_1 a_1, ..., t_n a_n, boost::contract::virtual_* v = 0) {
            t result;
            boost::contract::old_ptr<old_type> old_var;
            boost::contract::check c = boost::contract::public_function<
                    override_f>(v, result, &u::f, this, a_1, ..., a_n)
                .precondition([&] { // Optional.
                    BOOST_CONTRACT_ASSERT(...);
                    ...
                })
                .old([&] { // Optional.
                    old_var = BOOST_CONTRACT_OLDOF(v, old_expr);
                    ...
                })
                .postcondition([&] (t const& result) { // Optional.
                    BOOST_CONTRACT_ASSERT(...);
                    ...
                })
                .except([&] { // Optional.
                    BOOST_CONTRACT_ASSERT(...);
                    ...
                })
            ;

            ... // Function body (use `return result = return_expr`).
        }

        ...
    };

A public function override should always call ``boost::contract::public_function`` otherwise this library will not be able to correctly use it for subcontracting.

See Also: Public Function Overrides

Parameters: |
`v` | The trailing parameter of type ``boost::contract::virtual_```*` and default value `0` from the enclosing public function override.
`r` | A reference to the return value of the enclosing public function override declaring the contract. This is usually a local variable declared by the enclosing public function override just before the contract, but programmers must set it to the actual value being returned by the function at each `return` statement.
`f` | A pointer to the enclosing public function override declaring the contract (but see Function Overloads).
`obj` | The object `this` from the scope of the enclosing public function override 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).
`args` | All arguments passed to the enclosing public function override declaring the contract (by reference and in the order they appear in the enclosing function declaration), but excluding the trailing argument `v`.
Template Parameters: |
`Override` | The type trait `override_function-name` declared using the ``BOOST_CONTRACT_OVERRIDE`` or related macros. This template parameter must be explicitly specified (because there is no function argument from which it can be automatically deduced by C++).
`VirtualResult` | This type must be the same as, or compatible with, the return type of the enclosing public function override declaring the contract (this library might not be able to generate a compile-time error if these types mismatch, but in general that will cause run-time errors or undefined behaviour). Alternatively, `boost::optional<return-type>` can also be used (see Optional Return Values). (Usually this template parameter is automatically deduced by C++ and it does not need to be explicitly specified by programmers.)
`F` | The function pointer type of the enclosing public function override declaring the contract. (Usually this template parameter is automatically deduced by C++ and it does not need to be explicitly specified by programmers.)
`Class` | The type of the class containing the virtual public function declaring the contract. (Usually this template parameter is automatically deduced by C++ and it does not need to be explicitly specified by programmers.)
`Args` | The types of all parameters passed to the enclosing public function override declaring the contract, but excluding the trailing parameter type `boost::contract::virtual_*`. On compilers that do not support variadic templates, this library internally implements this function using preprocessor meta-programming (in this case, the maximum number of supported arguments is defined by ``BOOST_CONTRACT_MAX_ARGS``). (Usually these template parameters are automatically deduced by C++ and they do not need to be explicitly specified by programmers.)
Returns: | The result of this function must be assigned to a variable of type `boost::contract::check` declared explicitly (i.e., without using C++11 `auto` declarations) and locally just before the code of the public function body (otherwise this library will generate a run-time error, see `BOOST_CONTRACT_ON_MISSING_CHECK_DECL`).