libs/contract/doc/examples.qbk

   1
   2 [/ Copyright (C) 2008-2018 Lorenzo Caminiti]
   3 [/ Distributed under the Boost Software License, Version 1.0 (see accompanying]
   4 [/ file LICENSE_1_0.txt or a copy at http://www.boost.org/LICENSE_1_0.txt).]
   5 [/ See: http://www.boost.org/doc/libs/release/libs/contract/doc/html/index.html]
   6
   7 [section Examples]
   8
   9 This section lists some examples taken from different sources discussing contract programming and implemented here using this library.
  10
  11 [note
  12 Some of these examples might be from old code, containing obsolete coding practices, not optimized for execution speed, not complete, and they might be more relevant in the context of programming languages different from C++.
  13 Nevertheless, programmers are encouraged to review these examples to see a few diverse uses of this library that might be relevant to their needs.
  14 ]
  15
  16 The examples in this sections are taken from the following sources:
  17
  18 * __N1962__: Examples from a detailed and complete proposal to add contract programming to C++11 (unfortunately, this proposal was never accepted into the standard).
  19 * __Meyer97__: Examples from the Eiffel programming language (reprogrammed here in C++ using this library).
  20 * __Mitchell02__: Additional examples from the Eiffel programming language (reprogrammed here in C++ using this library).
  21 * __Cline90__: Examples from a very early proposal called Annotated C++ (A++) to add contract programming to C++ (A++ was never implemented or proposed for addition to the standard).
  22
  23 The following are some examples of particular interest:
  24
  25 * [link N1962_vector_anchor \[N1962\] Vector]: Complete set of contracts for `std::vector`, plus a comparison with __N1962__ syntax.
  26 * [link N1962_square_root_anchor \[N1962\] Square Root]: Comparison with D syntax.
  27 * [link Mitchell02_counter_anchor \[Mitchell02\] Counter]: Subcontracting.
  28 * [link Meyer97_stack4_anchor \[Meyer97\] Stack4]: Comparison with Eiffel syntax.
  29 * [link Cline90_vector_anchor \[Cline90\] Vector]: Comparison with A++ syntax.
  30
  31 Most of the examples listed here use old values and class invariants which are instead not supported by __P0380__.
  32 Therefore, there is not meaningful example here that can be directly implemented and compared using __P0380__ syntax.
  33
  34 [#N1962_vector_anchor]
  35 [section \[N1962\] Vector: Contracts for STL vector and comparison with __N1962__ proposed syntax]
  36
  37 On compilers that support C++17 `if constexpr`, the following example using this library can be simplified removing [funcref boost::contract::condition_if] and related functor templates such as `all_of_equal_to`, etc., making it more similar to the pseudo-code on the right-hand side (see __Assertion_Requirements__).
  38
  39 [import ../example/n1962/vector.cpp]
  40 [import ../example/n1962/vector_n1962.hpp]
  41 [table
  42     [ [This library] [\[N1962\] proposal (not accepted in C++) plus C++17 [^if constexpr]] ]
  43     [ [[n1962_vector]] [[n1962_vector_n1962]] ]
  44 ]
  45
  46 [endsect]
  47
  48 [section \[N1962\] Circle: Subcontracting]
  49 [import ../example/n1962/circle.cpp]
  50 [n1962_circle]
  51 [endsect]
  52
  53 [#N1962_factorial_anchor]
  54 [section \[N1962\] Factorial: Recursion]
  55 [import ../example/n1962/factorial.cpp]
  56 [n1962_factorial]
  57 [endsect]
  58
  59 [section \[N1962\] Equal: Operators]
  60 [import ../example/n1962/equal.cpp]
  61 [n1962_equal]
  62 [endsect]
  63
  64 [section \[N1962\] Sum: Array parameter]
  65 [import ../example/n1962/sum.cpp]
  66 [n1962_sum]
  67 [endsect]
  68
  69 [#N1962_square_root_anchor]
  70 [section \[N1962\] Square Root: Default parameters and comparison with D syntax]
  71 [import ../example/n1962/sqrt.cpp]
  72 [import ../example/n1962/sqrt.d]
  73 [table
  74     [ [This Library] [The D Programming Language] ]
  75     [ [[n1962_sqrt]] [[n1962_sqrt_d]] ]
  76 ]
  77 [endsect]
  78
  79 [#Meyer97_stack4_anchor]
  80 [section \[Meyer97\] Stack4: Comparison with Eiffel syntax]
  81 [import ../example/meyer97/stack4.hpp]
  82 [import ../example/meyer97/stack4_main.cpp]
  83 [import ../example/meyer97/stack4.e]
  84 [table
  85     [ [This Library] [The Eiffel Programming Language] ]
  86     [ [[meyer97_stack4]] [[meyer97_stack4_e]] ]
  87     [ [[meyer97_stack4_main]] [] ]
  88 ]
  89 [endsect]
  90
  91 [section \[Meyer97\] Stack3: Error codes instead of preconditions]
  92 [import ../example/meyer97/stack3.cpp]
  93 [meyer97_stack3]
  94 [endsect]
  95
  96 [section \[Mitchell02\] Name List: Relaxed subcontracts]
  97 [import ../example/mitchell02/name_list.cpp]
  98 [mitchell02_name_list]
  99 [endsect]
 100
 101 [section \[Mitchell02\] Dictionary: Key-value map]
 102 [import ../example/mitchell02/dictionary.cpp]
 103 [mitchell02_dictionary]
 104 [endsect]
 105
 106 [section \[Mitchell02\] Courier: Subcontracting and static class invariants]
 107 [import ../example/mitchell02/courier.cpp]
 108 [mitchell02_courier]
 109 [endsect]
 110
 111 [section \[Mitchell02\] Stack: Stack-like container]
 112 [import ../example/mitchell02/stack.cpp]
 113 [mitchell02_stack]
 114 [endsect]
 115
 116 [section \[Mitchell02\] Simple Queue: Queue-like container and disable old value copies for audit assertions]
 117 [import ../example/mitchell02/simple_queue.cpp]
 118 [mitchell02_simple_queue]
 119 [endsect]
 120
 121 [section \[Mitchell02\] Customer Manager: Contracts instead of defensive programming]
 122 [import ../example/mitchell02/customer_manager.cpp]
 123 [mitchell02_customer_manager]
 124 [endsect]
 125
 126 [section \[Mitchell02\] Observer: Pure virtual functions]
 127 [import ../example/mitchell02/observer/observer.hpp]
 128 [mitchell02_observer]
 129 [import ../example/mitchell02/observer/subject.hpp]
 130 [mitchell02_subject]
 131 [import ../example/mitchell02/observer_main.cpp]
 132 [mitchell02_observer_main]
 133 [endsect]
 134
 135 [#Mitchell02_counter_anchor]
 136 [section \[Mitchell02\] Counter: Subcontracting]
 137 [import ../example/mitchell02/counter/push_button.hpp]
 138 [mitchell02_push_button]
 139 [import ../example/mitchell02/counter/decrement_button.hpp]
 140 [mitchell02_decrement_button]
 141 [import ../example/mitchell02/counter/counter.hpp]
 142 [mitchell02_counter]
 143 [import ../example/mitchell02/counter_main.cpp]
 144 [mitchell02_counter_main]
 145 [endsect]
 146
 147 [#Cline90_vector_anchor]
 148 [section \[Cline90\] Vector: Comparison with A++ proposal syntax]
 149 [import ../example/cline90/vector.hpp]
 150 [import ../example/cline90/vector_main.cpp]
 151 [import ../example/cline90/vector_axx.hpp]
 152 [table
 153     [ [This Library] [A++ Proposal (never actually implemented)] ]
 154     [ [[cline90_vector]] [[cline90_vector_axx]] ]
 155     [ [[cline90_vector_main]] [] ]
 156 ]
 157 [endsect]
 158
 159 [section \[Cline90\] Stack: Stack-like container]
 160 [import ../example/cline90/stack.cpp]
 161 [cline90_stack]
 162 [endsect]
 163
 164 [section \[Cline90\] Vector-Stack: Subcontracting]
 165 [import ../example/cline90/vstack.cpp]
 166 [cline90_vstack]
 167 [endsect]
 168
 169 [section \[Cline90\] Calendar: A very simple calendar]
 170 [import ../example/cline90/calendar.cpp]
 171 [cline90_calendar]
 172 [endsect]
 173
 174 [endsect]
 175