boost/contract/function.hpp

   1
   2 #ifndef BOOST_CONTRACT_FUNCTION_HPP_
   3 #define BOOST_CONTRACT_FUNCTION_HPP_
   4
   5 // Copyright (C) 2008-2018 Lorenzo Caminiti
   6 // Distributed under the Boost Software License, Version 1.0 (see accompanying
   7 // file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt).
   8 // See: http://www.boost.org/doc/libs/release/libs/contract/doc/html/index.html
   9
  10 /** @file
  11 Program contracts for (non-public) functions.
  12 */
  13
  14 #include <boost/contract/core/config.hpp>
  15 #include <boost/contract/core/specify.hpp>
  16 #if     !defined(BOOST_CONTRACT_NO_FUNCTIONS) || \
  17         !defined(BOOST_CONTRACT_NO_INVARIANTS) || \
  18          defined(BOOST_CONTRACT_STATIC_LINK)
  19     #include <boost/contract/detail/operation/function.hpp>
  20 #endif
  21
  22 namespace boost { namespace contract {
  23
  24 /**
  25 Program contracts for non-member, private and protected functions.
  26
  27 This is used to specify preconditions, postconditions, exception guarantees, and
  28 old value copies at body for non-member, private and protected functions (these
  29 functions never check class invariants, see
  30 @RefSect{contract_programming_overview.function_calls, Function Calls}):
  31
  32 @code
  33 void f(...) {
  34     boost::contract::old_ptr<old_type> old_var;
  35     boost::contract::check c = boost::contract::function()
  36         .precondition([&] { // Optional.
  37             BOOST_CONTRACT_ASSERT(...);
  38             ...
  39         })
  40         .old([&] { // Optional.
  41             old_var = BOOST_CONTRACT_OLDOF(old_expr);
  42             ...
  43         })
  44         .postcondition([&] { // Optional.
  45             BOOST_CONTRACT_ASSERT(...);
  46             ...
  47         })
  48         .except([&] { // Optional.
  49             BOOST_CONTRACT_ASSERT(...);
  50             ...
  51         })
  52     ;
  53
  54     ... // Function body.
  55 }
  56 @endcode
  57
  58 This can be used also to program contracts in implementation code for lambda
  59 functions, loops, and arbitrary blocks of code.
  60 For optimization, this can be omitted for code that does not have preconditions,
  61 postconditions, and exception guarantees.
  62
  63 @see    @RefSect{tutorial.non_member_functions, Non-Member Functions},
  64         @RefSect{advanced.private_and_protected_functions,
  65         Private and Protected Functions},
  66         @RefSect{advanced.lambdas__loops__code_blocks__and__constexpr__,
  67         Lambdas\, Loops\, Code Blocks}
  68
  69 @return The result of this function must be assigned to a variable of type
  70         @RefClass{boost::contract::check} declared explicitly (i.e., without
  71         using C++11 @c auto declarations) and locally just before the code of
  72         the function body (otherwise this library will generate a run-time
  73         error, see @RefMacro{BOOST_CONTRACT_ON_MISSING_CHECK_DECL}).
  74 */
  75 inline specify_precondition_old_postcondition_except<> function() {
  76     // Must #if also on ..._INVARIANTS here because specify_... is generic.
  77     #if     !defined(BOOST_CONTRACT_NO_FUNCTIONS) || \
  78             !defined(BOOST_CONTRACT_NO_INVARIANTS) || \
  79              defined(BOOST_CONTRACT_STATIC_LINK)
  80         return specify_precondition_old_postcondition_except<>(
  81                 new boost::contract::detail::function());
  82     #else
  83         return specify_precondition_old_postcondition_except<>();
  84     #endif
  85 }
  86
  87 } } // namespace
  88
  89 #endif // #include guard
  90