trompeloeil

CookBook.md (73461B)

---

 # *Trompeloeil* cook book
 
 - [Integrating with unit test frame works](#unit_test_frameworks)
 - [Creating Mock Classes](#creating_mock_classes)
   - [Mocking private or protected member functions](#mocking_non_public)
   - [Mocking overloaded member functions](#mocking_overloaded)
   - [Mocking operator()](#mocking_call_operator)
   - [Mocking a class template](#mocking_class_template)
   - [Mocking non-virtual member functions](#mocking_non_virtual)
   - [Mocking free functions](#mocking_free_functions)
   - [Mocking functions which return a template](#mocking_return_template)
 - [Setting Expectations](#setting_expectations)
   - [Matching exact values](#matching_exact_values)
   - [Matching values with conditions](#matching_conditions)
   - [Matching strings with regular expressions](#matching_regular_expressions)
   - [Matching pointers to values](#matching_pointers)
   - [Matching the opposite of a matcher](#negating_matchers)
   - [Matching calls with conditions depending on several parameters](#matching_multiconditions)
   - [Matching `std::unique_ptr<T>` and other non-copyable values](#matching_non_copyable)
   - [Matching calls to overloaded member functions](#matching_overloads)
   - [Define side effects for matching calls](#side_effects)
   - [Return values from matching calls](#return_values)
   - [Return references from matching calls](#return_references)
   - [Throwing exceptions from matching calls](#throw)
   - [Allowing any call](#allowing_any)
   - [Temporarily disallowing matching calls](#temporary_disallow)
   - [Expecting several matching calls in some sequences](#sequences)
   - [Expecting matching calls a certain number of times](#match_count)
 - [Controlling lifetime of mock objects](#lifetime)
 - [Customize output format of values](#custom_formatting)
 - [Tracing mocks](#tracing)
   - [Using `trompeloeil::stream_tracer`](#stream_tracer)
   - [Writing custom tracers](#custom_tracer)
 - [Writing custom matchers](#custom_matchers)
   - [Typed matchers](#typed_matcher)
   - [Duck-typed matchers](#duck_typed_matcher)
   - [Legacy matchers](#legacy_matcher)
 
 ## <A name="unit_test_frameworks"/> Integrating with unit test frame works
 
 By default, *Trompeloeil* reports violations by throwing an exception,
 explaining the problem in the
 [`what()`](http://en.cppreference.com/w/cpp/error/exception/what) string.
 
 Depending on your test frame work and your runtime environment, this may,
 or may not, suffice.
 
 *Trompeloeil* offers support for adaptation to any test frame work. Some
 sample adaptations are:
 
 - [Catch!](#adapt_catch)
 - [crpcut](#adapt_crpcut)
 - [CxxTest](#adapt_cxxtest)
 - [doctest](#adapt_doctest)
 - [gtest](#adapt_gtest)
 - [lest](#adapt_lest)
 - [boost Unit Test Framework](#adapt_boost_unit_test_framework)
 - [MSTest](#adapt_mstest)
 - [Criterion](#adapt_criterion)
 
 There are two mechanisms for adapting to a testing frame work. The compile time
 adapter and the run time adapter. The compile time adapter is easier to use,
 especially if you write several test programs, but the runtime adapter allows
 for more flexibility, for example if you need run-time data like CLI arguments.
 
 ### Compile time adapter
 
 If you have a unit testing framework named *my_test*, create a header file
 `<my_test/trompeloeil.hpp>`. This header file must include `<trompeloeil.hpp>`,
 and provide an inline specialization of the
 `trompeloeil::reporter<trompeloeil::specialized>::send()` function.
 
 Below, as an example, is the adapter for the
 [*doctest*](https://github.com/onqtam/doctest) unit testing frame work, in the
 file `<doctest/trompeloeil.hpp>`
 
 ```Cpp
 #ifndef TROMPELOEIL_DOCTEST_HPP_
 #define TROMPELOEIL_DOCTEST_HPP_
 
 #ifndef DOCTEST_VERSION_MAJOR                   //** 1 **//
 #error "<doctest.h> must be included before <doctest/trompeloeil.hpp>"
 #endif
 
 #include "../trompeloeil.hpp"                   //** 2 **//
 
 namespace trompeloeil
 {
   template <>
   inline void reporter<specialized>::send(      //** 3 **//
     severity s,
     char const* file,
     unsigned long line,
     std::string const& msg)
   {
     auto f = line ? file : "[file/line unavailable]";
     if (s == severity::fatal)
     {
       ADD_FAIL_AT(f, line, msg);                //** 4 **//
     }
     else
     {
       ADD_FAIL_CHECK_AT(f, line, msg);          //** 4 **//
     }
   }
 }
 
 
 #endif //TROMPELOEIL_DOCTEST_HPP_
 ```
 
 The preprocessor check at `//** 1 **//` is not necessary, but it gives a
 friendly hint about what's missing. The function uses *doctest* macros
 at `//** 4 **//`, so `<doctest.h>` must be included for this to compile.
 
 At `//** 2 **//` the include path is relative, since this is the file from
 the *Trompeloeil* distribution, where the main `trompeloeil.hpp` file is
 known to be in the parent directory of `doctest/trompeloeil.hpp`.
 
 At `//** 3 **//` the specialized function is marked `inline`, so as not to
 cause linker errors if your test program consists of several translation
 units, each including `<doctest/trompeloeil.hpp>`.
 
 At `//** 4 **//` the violations are reported in a *doctest* specific
 manner.
 
 It is important to understand the first parameter
 `trompeloeil::severity`. It is an enum with the values
 `trompeloeil::severity::fatal` and `trompeloeil::severity::nonfatal`. The value
 `severity::nonfatal` is used when reporting violations during stack rollback,
 typically during the destruction of an [expectation](
   reference.md/#expectation
 ). In this case it is vital that no exception is
 thrown, or the process will terminate. If the value is
 `severity::fatal`, it is instead imperative that the function does not return.
 It may throw or abort.
 
 **NOTE!** There are some violations that cannot be attributed to a source code
 location. An example is an unexpected call to a
 [mock function](reference.md/#mock_function) for which there
 are no expectations. In these cases `file` will be `""` string and
 `line` == 0.
 
 Please contribute your adapter, so that others can enjoy your unit testing
 framework together with *Trompeloeil*.
 
 ### Run time adapter
 
 Run time adaptation to unit test frame works is done with this function:
 
 ```Cpp
 using reporter_func = std::function<void(
   severity,
   char const *file,
   unsigned long line,
   std::string const &msg)>;
 using ok_reporter_func = std::function<void(char const *msg)>;
 
 reporter_func trompeloeil::set_reporter(reporter_func new_reporter);
 std::pair<reporter_func, ok_reporter_func> trompeloeil::set_reporter(
   reporter_func new_reporter, ok_reporter_func new_ok_reporter)
 ```
 
 Call it with the adapter to your test frame work. The return value is the old
 adapter. The overload is provided to allow you to also set an 'OK reporter' at
 the same time (it also returns the old 'OK reporter') See the next section for
 details.
 
 It is important to understand the first parameter
 `trompeloeil::severity`. It is an enum with the values
 `trompeloeil::severity::fatal` and `trompeloeil::severity::nonfatal`. The value
 `severity::nonfatal` is used when reporting violations during stack rollback,
 typically during the destruction of an
 [expectation](reference.md/#expectation). In this case it is vital that
 no exception is thrown, or the process will terminate. If the value is
 `severity::fatal`, it is instead imperative that the function does not return.
 It may throw or abort.
 
 **NOTE!** There are some violations that cannot be attributed to a source code
 location. An example is an unexpected call to a
 [mock function](reference.md/#mock_function) for which there
 are no expectations. In these cases `file` will be `""` string and
 `line` == 0.
 
 ### Status OK reporting
 
 It is possible to make an adaption to the reporter that will be called if
 a positive expectation is met. This can be useful for correct counting and reporting
 from the testing framework. Negative expectations like `FORBID_CALL` and
 `.TIMES(0)` are not counted.
 
 Either provide your adapter as an inline specialization of the
 `trompeloeil::reporter<trompeloeil::specialized>::sendOk()` function at
 compile time or as the second argument to
 `trompeloeil::set_reporter(new_reporter, new_ok_reporter)` at runtime.
 The function should call a matcher in the testing framework that always
 yields true.
 
 Below, as an example, is the compile time adapter for the Catch2 unit testing frame
 work, in the file `<catch2/trompeloeil.hpp>`
 
 ```Cpp
   template <>
   inline void reporter<specialized>::sendOk(
     const char* trompeloeil_mock_calls_done_correctly)
   {
       REQUIRE(trompeloeil_mock_calls_done_correctly);
   }
 ```
 
 If you roll your own `main()`, you may prefer a runtime adapter instead. Please note that the first param given to `set_reporter()` here is a dummy - see the sections below for implementation examples for your unit testing framework of choice.
 
 ```Cpp
 trompeloeil::set_reporter(
   [](auto, auto, auto, auto) {}, // Not relevant here
   [](const char* trompeloeil_mock_calls_done_correctly)
     {
       // Example for Catch2
       REQUIRE(trompeloeil_mock_calls_done_correctly);
     }
 );
 ```
 
 Below is a simple example for *Catch2*:
 
 ```Cpp
 class MockFoo
 {
 public:
     MAKE_MOCK0(func, void());
 };
 
 TEST_CASE("Foo test")
 {
     MockFoo foo;
     REQUIRE_CALL(foo, func()).TIMES(2,4);
     foo.func();
     foo.func();
 }
 ```
 
 When the test is executed we get the following output
 
 ```sh
 $ ./footest
 ===============================================================================
 All tests passed (2 assertions in 1 test case)
 ```
 
 ### <A name="adapt_catch"/>Use *Trompeloeil* with [Catch2](https://github.com/catchorg/Catch2)
 
 The easiest way to use *Trompeloeil* with *Catch2* is to
 `#include <catch2/trompeloeil.hpp>` in your test .cpp files. Note that the
 inclusion order is important. `<catch.hpp>` must be included before
 `<catch/trompeloeil.hpp>`.
 
 Like this:
 
 ```Cpp
 #include <catch.hpp>
 #include <catch2/trompeloeil.hpp>
 
 TEST_CASE("...
 ```
 
 If you roll your own `main()`, you may prefer a runtime adapter instead.
 Before running any tests, make sure to call:
 
 ```Cpp
   trompeloeil::set_reporter([](
     trompeloeil::severity s,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     std::ostringstream os;
     if (line) os << file << ':' << line << '\n';
     os << msg;
     auto failure = os.str();
     if (s == trompeloeil::severity::fatal)
     {
       FAIL(failure);
     }
     else
     {
       CAPTURE(failure);
       CHECK(failure.empty());
     }
   });
 ```
 
 ### <A name="adapt_cxxtest"/>Use *Trompeloeil* with [CxxTest](https://www.cxxtest.com)
 
 The easiest way to use *Trompeloeil* with *CxxTest* is to
 `#include <cxxtest/trompeloeil.hpp>` in your test `.hpp` files. Note that the
 inclusion order is important. `<cxxtest/TestSuite.h>` must be included before
 `<cxxtest/trompeloeil.hpp>`.
 
 Like this:
 
 ```Cpp
 #include <cxxtest/TestSuite.h>
 #include <cxxtest/trompeloeil.hpp>
 
 class TestClass: public CxxTest::TestSuite
 {
 public:
   void TestXXX()
   {
     // ...
   }
 };
 ```
 
 If you roll your own `main()`, you may prefer a runtime adapter instead.
 Before running any tests, make sure to call:
 
 ```Cpp
   trompeloeil::set_reporter([](
     trompeloeil::severity s,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     std::ostringstream os;
     if (line) os << file << ':' << line << '\n';
     os << msg;
     auto failure = os.str();
     if (s == severity::fatal)
     {
       // Must not return normally i.e. must throw, abort or terminate.
       TS_FAIL(failure);
     }
     else
     {
       // nonfatal: violation occurred during stack rollback.
       // Must not throw an exception.
       TS_WARN(failure);
     }
   });
 ```
 
 ### <A name="adapt_crpcut"/>Use *Trompeloeil* with [crpcut](http://crpcut.sourceforge.net)
 
 The easiest way to use *Trompeloeil* with *crpcut* is to
 `#include <crpcut/trompeloeil.hpp>` in your test .cpp files. Note that the
 inclusion order is important. `<crpcut.hpp>` must be included before
 `<crpcut/trompeloeil.hpp>`.
 
 Like this:
 
 ```Cpp
 #include <crpcut.hpp>
 #include <crpcut/trompeloeil.hpp>
 
 TEST(...
 ```
 
 If you instead prefer a runtime adapter, make sure to call
 
 ```Cpp
   trompeloeil::set_reporter([](
     trompeloeil::severity,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     std::ostringstream os;
     os << file << ':' << line;
     auto loc = os.str();
     auto location = line == 0U
       ? ::crpcut::crpcut_test_monitor::current_test()->get_location()
       : ::crpcut::datatypes::fixed_string::make(loc.c_str(), loc.length());
     ::crpcut::comm::report(::crpcut::comm::exit_fail,
                            std::ostringstream(msg),
                            location);
   });
 ```
 
 before any tests are run.
 
 ### <A name="adapt_doctest"/>Use *Trompeloeil* with [doctest](https://github.com/onqtam/doctest)
 
 - [doctest 1.2 or newer](#doctest12)
 - [doctest &lt; 1.2](#doctest_old)
 
 #### <A name="doctest12"/> doctest 1.2 or newer
 
 The easiest way to use *Trompeloeil* with *doctest* is to
 `#include <doctest/trompeloeil.hpp>` in your test .cpp files. Note that the
 inclusion order is important. `<doctest.h>` must be included before
 `<doctest/trompeloeil.hpp>`.
 
 Like this:
 
 ```Cpp
 #include <doctest.h>
 #include <doctest/trompeloeil.hpp>
 
 TEST_CASE("...
 ```
 
 If you roll your own `main()`, you may prefer a runtime adapter instead.
 Before running any tests, make sure to call:
 
 ```Cpp
   trompeloeil::set_reporter([](
     trompeloeil::severity s,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     auto f = line ? file : "[file/line unavailable]";
     if (s == severity::fatal)
     {
       ADD_FAIL_AT(f, line, msg);
     }
     else
     {
       ADD_FAIL_CHECK_AT(f, line, msg);
     }
   });
 ```
 
 #### <A name="doctest_old"/> doctest &lt; 1.2
 
 Create a simple `doctest_violation` type by pasting the below code
 into the file containing `main()`.
 
 ```Cpp
   struct doctest_violation : std::ostringstream
   {
     friend std::ostream& operator<<(std::ostream& os, doctest_violation const& v)
     {
       return os << v.str();
     }
   };
 ```
 
 Then, before running any tests, make sure to call:
 
 ```Cpp
   trompeloeil::set_reporter([](
     trompeloeil::severity s,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     ::doctest_violation violation;
     if (line) violation << file << ':' << line << '\n';
     violation << msg;
     if (s == trompeloeil::severity::fatal)
     {
       REQUIRE_FALSE(violation);
     }
     else
     {
        CHECK_FALSE(violation);
     }
   });
 ```
 
 ### <A name="adapt_gtest"/>Use *Trompeloeil* with [gtest](https://code.google.com/p/googletest/)
 
 The easiest way to use *Trompeloeil* with *gtest* is to
 `#include <gtest/trompeloeil.hpp>` in your test .cpp files. Note that the
 inclusion order is important. `<gtest.h>` must be included before
 `<gtest/trompeloeil.hpp>`.
 
 Like this:
 
 ```Cpp
 #include <gtest.h>
 #include <gtest/trompeloeil.hpp>
 
 TEST("...
 ```
 
 If you instead prefer a runtime adapter, make sure to call
 
 ```Cpp
   trompeloeil::set_reporter([](
     trompeloeil::severity s,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     if (s == trompeloeil::severity::fatal)
     {
       std::ostringstream os;
       if (line != 0U)
       {
         os << file << ':' << line << '\n';
       }
       throw trompeloeil::expectation_violation(os.str() + msg);
     }
 
     ADD_FAILURE_AT(file, line) << msg;
   });
 ```
 
 before running any tests.
 
 ### <A name="adapt_lest"/>Use *Trompeloeil* with [lest](https://github.com/martinmoene/lest)
 
 With *lest*, you always provide your own `main()`. In it, provide a runtime adapter like the one below.
 
 ```Cpp
 int main(int argc, char *argv[])
 {
   std::ostream& stream = std::cout;
 
   trompeloeil::set_reporter([&stream](
     trompeloeil::severity s,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     if (s == trompeloeil::severity::fatal)
     {
       throw lest::message{"", lest::location{ line ? file : "[file/line unavailable]", int(line) }, "", msg };
     }
     else
     {
       stream << lest::location{ line ? file : "[file/line unavailable]", int(line) } << ": " << msg;
     }
   });
 
   return lest::run(specification, argc, argv, stream);
 }
 ```
 
 ### <A name="adapt_boost_unit_test_framework"/>Use *Trompeloeil* with [boost Unit Test Framework](http://www.boost.org/doc/libs/1_59_0/libs/test/doc/html/index.html)
 
 The easiest way to use *Trompeloeil* with *boost::unit_test* is to
 `#include <boost/trompeloeil.hpp>` in your test .cpp files. Note that the
 inclusion order is important. `<boost/test/unit_test.hpp>` must be included before
 `<boost/trompeloeil.hpp>`.
 
 Like this:
 
 ```Cpp
 #include <boost/test/unit_test.hpp>
 #include <boost/trompeloeil.hpp>
 
 BOOST_AUTO_TEST_CASE("...
 ```
 
 If you instead prefer a runtime adapter, make sure to call
 
 ```Cpp
   trompeloeil::set_reporter([](
     trompeloeil::severity s,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     std::ostringstream os;
     if (line != 0U) os << file << ':' << line << '\n';
     auto text = os.str() + msg;
     if (s == trompeloeil::severity::fatal)
       BOOST_FAIL(text);
     else
       BOOST_ERROR(text);
   });
 ```
 
 before running any tests.
 
 ### <A name="adapt_mstest"/> Use *Trompeloeil* with [MSTest](https://msdn.microsoft.com/en-us/library/hh694602.aspx)
 
 Place the below code snippet in, for example, your `TEST_CLASS_INITIALIZE(...)`
 
 ```Cpp
   using namespace trompeloeil;
   set_reporter([](
     severity,
     char const* file,
     unsigned long line,
     std::string const& msg)
   {
     std::wstring wideMsg(msg.begin(), msg.end());
     std::wstring wfile;
     if (line > 0) wfile.append(file, file + strlen(file));
     __LineInfo loc(wfile.c_str(), "", line);
     Assert::Fail(wideMsg.c_str(), line == 0 ? nullptr : &loc);
   });
 ```
 
 ### <A name="adapt_criterion"/>Use *Trompeloeil* with [Criterion](https://github.com/Snaipe/Criterion)
 
 The easiest way to use *Trompeloeil* with *Criterion* is to
 `#include <criterion/trompeloeil.hpp>` in your test .cpp files. Note that the
 inclusion order is important. `<criterion/criterion.hpp>` must be included before
 `<criterion/trompeloeil.hpp>`.
 
 Like this:
 
 ```Cpp
 #include <criterion/criterion.hpp>
 #include <criterion/trompeloeil.hpp>
 
 Test(...
 ```
 
 If you instead prefer a runtime adapter, make sure to call
 
 ```Cpp
   trompeloeil::set_reporter([](
     trompeloeil::severity s,
     const char* file,
     unsigned long line,
     std::string const& msg)
   {
     struct criterion_assert_stats cr_stat__;
     cr_stat__.passed = false;
     cr_stat__.file = file;
     cr_stat__.line = line;
     cr_stat__.message = msg;
     if (s == severity::fatal)
     {
         criterion_send_assert(&cr_stat__);
         CR_FAIL_ABORT_();
     }
     else
     {
         criterion_send_assert(&cr_stat__);
         CR_FAIL_CONTINUES_();
     }
   });
 ```
 
 before running any tests.
 
 ## <A name="creating_mock_classes"/> Creating Mock Classes
 
 A Mock class is any class that [mocks](reference.md/#mock_function) member
 functions.
 
 There are two ways to create mocks. A very frequently seen situation is
 when inheriting from an interface (i.e. an abstract base class with
 pure virtual functions). When this is the case, the easiest route is to
 inherit the interface via
 [`trompeloeil::mock_interface<T>`](#reference.md/mock_interface)
 and implement the mock functions with the macros
 [**`IMPLEMENT_MOCKn(...)`**](reference.md/#IMPLEMENT_MOCKn) and
 [**`IMPLEMENT_CONST_MOCKn(...)`**](reference.md/#IMPLEMENT_CONST_MOCKn). These
 only work when implementing to an interface, do not handle multiple inheritance
 and do not handle overloads.
 
 A more generic technique is to implement free mocks as members of any
 `struct` or `class` using the macros [**`MAKE_MOCKn`**](
   reference.md/#MAKE_MOCKn
 ) and [**`MAKE_CONST_MOCKn`**](
   reference.md/#MAKE_CONST_MOCKn
 ), where `n` is the number of parameters in the function.
 
 Example:
 
 ```Cpp
 class Dictionary
 {
 public:
   virtual ~Dictionary() = default;
   virtual std::string& lookup(int n) const = 0;
   virtual void add(int n, std::string&&) = 0;
 };
 
 class MockDictionary : public trompeloeil::mock_interface<Dictionary>
 {
   IMPLEMENT_CONST_MOCK1(lookup);
   IMPLEMENT_MOCK2(add);
 };
 
 struct Logger
 {
   MAKE_MOCK2(log, void(int severity, const std::string& msg));
 };
 
 ```
 
 In the example above, `MockDictionary` is, as the name implies, a mock class for
 the pure virtual class `Dictionary`.
 
 The line `IMPLEMENT_CONST_MOCK1(lookup);` implements the function
 `std::string& lookup(int) const` and the line `IMPLEMENT_MOCK2(add);` implements
 the function `void add(int, std::string&&)`.
 
 The line `MAKE_MOCK2(log, void(int severity, const std::string& msg))`
 creates a mock function `void Logger::log(int, const std::string&)`. If
 [**`MAKE_MOCKn(...)`**](reference.md/#MAKE_MOCKn) or
 [**`MAKE_CONST_MOCKn(...)`**](reference.md/#MAKE_CONST_MOCKn) are used
 to implement a virtual function from a base class, it is always recommended to
 add a third macro parameter `override` since it gives the compiler an ability to
 complain about mistakes.
 
 ### <A name="mocking_non_public"/> Mocking private or protected member functions
 
 Mocking private or protected member functions using
 [**`MAKE_MOCKn(...)`**](reference.md/#MAKE_MOCKn) or
 [**`MAKE_CONST_MOCKn(...)`**](reference.md/#MAKE_CONST_MOCKn) is no different
 from mocking
 
 public member functions. Just make them public in the mock class. It may seem
 strange that you can change access rights of a member function through
 inheritance, but C\+\+ allows it.
 
 Example:
 
 ```Cpp
 class Base
 {
 private:
   virtual void secret(int);
 };
 
 class Mock : public Base
 {
 public:
   MAKE_MOCK1(secret, void(int), override); // not so secret now
 };
 ```
 
 The [mock functions](reference.md/#mock_function) must be public for you to
 be able to set [expectations](#setting_expectations) on them, but there is
 nothing preventing a public function from implementing a private virtual function
 in a base class.
 
 **NOTE!** Mocking private or protected functions does not work with
 [**`IMPLEMENT_MOCKn(...)`**](reference.md/#IMPLEMENT_MOCKn) or
 [**`IMPLEMENT_CONST_MOCKn(...)`**](reference.md/#IMPLEMENT_CONST_MOCKn), since
 these need full visibility of the function in the base class.
 
 ### <A name="mocking_overloaded"/> Mocking overloaded member functions
 
 *Trompeloeil* matches [mock functions](reference.md/#mock_function) by
 their name and their signature, so there is nothing special about
 adding several overloads of mocked functions.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(overload, void(int));
   MAKE_MOCK1(overload, int(const std::string&));
   MAKE_MOCK2(overload, int(const char*, size_t));
 };
 ```
 
 Above there are three [mock functions](reference.md/#mock_function) named
 `overload`, with different signatures.
 
 See [Matching calls to overloaded member functions](#matching_overloads)
 for how to place [expectations](reference.md/#expectation) on them.
 
 **NOTE!** Overloaded member functions cannot be mocked using the
 macros [**`IMPLEMENT_MOCKn(...)`**](reference.md/IMPLEMENT_MOCKn) or
 [**`IMPLEMENT_CONST_MOCKn(...)`**](reference.md/IMPLEMENT_CONST_MOCKn)`.
 
 ### <A name="mocking_call_operator"/> Mocking operator()
 
 The *Trompeloeil* macros cannot handle `operator()` directly, so to
 mock the function call operator you have to go via an indirection, where
 you implement a trivial `operator()` that calls a function that you can mock.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   int operator()(int x) const { return function_call(x); }
   MAKE_CONST_MOCK1(function_call, int(int));
 };
 ```
 
 ### <A name="mocking_class_template"/> Mocking a class template
 
 Unlike some *C\+\+* mocking frame works, *Trompeloeil* does not make a
 distinction between mocks in class templates and mocks in concrete classes.
 
 Example:
 
 ```Cpp
 template <typename T>
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int));
   MAKE_MOCK2(tfunc, int(const T&, size_t));
 };
 ```
 
 Above, `Mock<T>` is a mock class template with two member functions. The
 member function `void func(int)` does not depend on the template parameter,
 whereas the member function `int tfunc(const T&, size_t)` does. This will
 work for any type `T`.
 
 ### <A name="mocking_non_virtual"/> Mocking non-virtual member functions
 
 While it is often the case that mocks are used to implement interfaces, there is
 no such requirement. Just add the [mock functions][mockfun] that are needed.
 
 Example:
 
 ```Cpp
 class ConcreteMock
 {
 public:
   MAKE_MOCK2(func, bool(size_t, const char*));
 };
 ```
 
 Above `ConcreteMock` is a mock class that implements a non-virtual [mock
 function][mockfun] `bool func(size_t, const char*)`.
 
 > **REMINDER**: Non-virtual functions may not be dispatched via polymorphism at
 > runtime. This feature doesn't alter the underlying semantic rules for virtual
 > methods. If you upcast to a base type, the mock class implementations of these
 > methods will _not_ be invoked.
 
 [mockfun]: reference.md/#mock_function
 
 ### <A name="mocking_free_functions"/> Mocking free functions
 
 Free functions on their own cannot be mocked, the calls to them needs to
 be dispatched to [mock objects](reference.md/#mock_object). Often there are
 several free functions that together form an API, and then it makes sense
 to implement one mock class for the API, with
 [mock functions](reference.md/#mock_function) for each.
 
 Example, assume a simple C-API
 
 ```Cpp
 // C-API.h
 
 #ifdef __cplusplus
 extern "C" {
 #endif
 
 struct c_api_cookie;
 
 struct c_api_cookie* c_api_init();
 
 int c_api_func1(struct c_api_cookie* cookie, const char* str, size_t len);
 
 void c_api_end(struct c_api_cookie*);
 
 #ifdef __cplusplus
 }
 #endif
 ```
 
 ```Cpp
 // unit-test-C-API.h
 
 #include "C-API.h"
 
 class API
 {
 public:
   MAKE_MOCK0(c_api_init, c_api_cookie*());
   MAKE_MOCK3(c_api_func1, int(c_api_cookie*, const char*, size_t));
   MAKE_MOCK1(c_api_end, void(c_api_cookie*));
 };
 
 extern API c_api_mock;
 ```
 
 Then implement the functions in a test version of the API, which uses the
 mock.
 
 ```Cpp
 // unit-test_c_api.cpp
 #include "unit-test-C-API.h"
 
 API c_api_mock;
 
 extern "C" {
   c_api_cookie c_api_init()
   {
     return api_mock.c_api_init();
   }
 
   int c_api_func1(c_api_cookie* cookie, const char* str, size_t len)
   {
     return api_mock.c_api_func1(cookie, str, len);
   }
 
   void c_api_end(c_api_cookie* cookie)
   {
     api_mock.c_api_end(cookie);
   }
 }
 ```
 
 A test program can place [expectations](reference.md/#expectation) on the
 mock object, and the tested functionality calls the C-API functions which
 dispatch to the mock object.
 
 ```Cpp
 #include "unit-test-C-API.h"
 
 void a_test()
 {
   REQUIRE_CALL(c_api_mock, create())
     .RETURN(nullptr);
 
   REQUIRE_CALL(c_api_mock, c_api_end(nullptr));
 
   function_under_test();
 }
 ```
 
 ### <A name="mocking_return_template"/> Mocking functions which return a template
 
 To use template as return type you have to put the signature into parentheses
 like this:
 
 ```Cpp
 struct M
 {
   MAKE_MOCK2(make, (std::pair<int,int>(int,int)));
 };
 ```
 
 ## <A name="setting_expectations"/> Setting Expectations
 
 It is with [expectations](reference.md/#expectation) you define the behaviour
 of your test. By default all calls to
 [mock functions](reference.md/#mock_function) are illegal and will be reported
 as violations. You use expectations, long or short lived, wide or narrow,
 to make some calls legal and define what happens.
 
 There are three basic types of expectations.
 
 - [**`ALLOW_CALL(...)`**](reference.md/#ALLOW_CALL)
 - [**`REQUIRE_CALL(...)`**](reference.md/#REQUIRE_CALL)
 - [**`FORBID_CALL(...)`**](reference.md/#FORBID_CALL)
 
 **`ALLOW_CALL(...)`** is often used for a default. It can match any number of
 times.
 
 **`REQUIRE_CALL(...)`** is stricter and defaults to match exactly once, although
 you can change that and control exactly [how many times](#match_count) you want
 the expectation to match.
 
 **`FORBID_CALL(...)`** may seem unnecessary since calls are forbidden by
 default, but it is useful in combination with **`ALLOW_CALL(...)`** or
 **`REQUIRE_CALL(...)`** to forbid something that would otherwise be accepted.
 
 If several expectations match a call, it is the last matching expectation
 created that is used. **`ALLOW_CALL(...)`**, **`REQUIRE_CALL(...)`** and
 **`FORBID_CALL(...)`** are active until the end of the scope. This means
 that you can place a wide default, and use temporary special expectations in
 local scopes, for example to temporarily forbid a call that is otherwise
 allowed.
 
 If the scoped lifetime rules are unsuitable, there are also thee named
 versions of the expectations.
 
 - [**`NAMED_ALLOW_CALL(...)`**](reference.md/#NAMED_ALLOW_CALL)
 - [**`NAMED_REQUIRE_CALL(...)`**](reference.md/#NAMED_REQUIRE_CALL)
 - [**`NAMED_FORBID_CALL(...)`**](reference.md/#NAMED_FORBID_CALL)
 
 These do the same, but they create a
 `std::unique_ptr<trompeloeil::expectation>`, which you can bind to variables
 that you control the life time of.
 
 ### <A name="matching_exact_values"/> Matching exact values
 
 The simplest [expectations](reference.md/#expectation) are for calls with exact
 expected parameter values. You just provide the expected values in the
 parameter list of the expectation.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int));
   MAKE_MOCK2(func, void(const char*));
 };
 
 void test()
 {
   Mock m;
   ALLOW_CALL(m, func(1));         // int version any number of times
   REQUIRE_CALL(m, func(nullptr)); // const char * version exactly once
   func(&m);
   // expectations must be met before end of scope
 }
 ```
 
 ### <A name="matching_conditions"/> Matching values with conditions
 
 Instead of using exact values of parameters to match calls with, *Trompeloeil*
 provides a set of [matchers](reference.md/#matcher). Simple value matchers are:
 
 - [**`eq(`** *value* **`)`**](reference.md/#eq) matches value equal (using `operator==()`)
 - [**`ne(`** *value* **`)`**](reference.md/#ne) matches value not equal (using `operator!=()`)
 - [**`gt(`** *value* **`)`**](reference.md/#gt) matches value greater than (using `operator>()`)
 - [**`ge(`** *value* **`)`**](reference.md/#ge) matches value greater than or equal (using `operator>=()`)
 - [**`lt(`** *value* **`)`**](reference.md/#lt) matches value less than (using `operator<()`)
 - [**`le(`** *value* **`)`**](reference.md/#le) matches value less than or equal (using `operator<=()`)
 
 By default, the matchers are [*duck typed*](
   https://en.wikipedia.org/wiki/Duck_typing
 ), i.e. they match a parameter that supports the operation. If disambiguation
 is necessary to resolve overloads, an explicit type can be specified.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int));
   MAKE_MOCK1(func, void(const char*));
   MAKE_MOCK1(func, void(const std::string&))
 };
 
 void test()
 {
   Mock m;
   ALLOW_CALL(m, func(trompeloeil::gt(1))); // int version any number of times
   REQUIRE_CALL(m, func(trompeloeil::ne<std::string>(""))); // const std::string& version once
   func(&m);
   // expectations must be met before end of scope
 }
 ```
 
 ### <A name="matching_regular_expressions"/> Matching strings with regular expressions
 
 Matching string parameters to regular expressions is convenient with
 *Trompeloeil* [**`re(`** *expression* **`)`**](reference.md/#re) regular
 expression matchers.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(const char*));
 };
 
 void test()
 {
   Mock m;
   REQUIRE_CALL(m, func(trompeloeil::re("^begin.*end$")));
   func(&m);
   // expectation must be met before end of scope
 }
 ```
 
 **TIP!** Using `C++` [raw string literals](
   http://www.stroustrup.com/C++11FAQ.html#raw-strings
 ) can massively help getting regular expression escapes right.
 
 ### <A name="matching_pointers"/> Matching pointers to values
 
 All [matchers](reference.md/#matcher) can be converted to a pointer matcher
 by using the dereference prefix operator [**`*`**](reference.md/#deref_matcher).
 This works for smart pointers too. These pointer matchers fail if the pointer parameter is `nullptr`.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int*));
   MAKE_MOCK2(func, void(std::unique_ptr<short>*));
 };
 
 using trompeloeil::eq;
 using trompeloeil::gt;
 
 void test()
 {
   Mock m;
   ALLOW_CALL(m, func(*eq(1))); // pointer to int value 1 any number of times
   REQUIRE_CALL(m, func(*gt<short>(5))); // unique_ptr<short> to >5 once
   func(&m);
   // expectations must be met before end of scope
 }
 ```
 
 ### <A name="negating_matchers"/> Matching the opposite of a matcher
 
 All [matchers](reference.md/#matcher) can be negated, allowing what the matcher
 disallows and disallowing what the matcher allows, using the operator
  [**`!`**](reference.md/#negate_matcher) on the matcher.
 
 Example:
 
 ```Cpp
 struct Mock {
   MAKE_MOCK1(func, void(const std::string&));
 };
 
 using trompeloeil::re; // matching regular expressions
 
 TEST(atest)
 {
   Mock m;
   REQUIRE_CALL(m, func(!re("^foo")));
   func(&m);
   // m.func() must've been called with a string not beginning with "foo"
 }
 ```
 
 ### <A name="matching_multiconditions"/> Matching calls with conditions depending on several parameters
 
 Some times a matching call cannot be judged for individual parameter values
 alone, but together they work. Assume for example a C-string API where you have
 a `const char*` and a length.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK2(func, void(const char*, size_t len));
 };
 
 using trompeloeil::ne;
 using trompeloeil::_;
 
 void test()
 {
   Mock m;
   REQUIRE_CALL(m, func(ne(nullptr), _)))  // once
     .WITH(std::string(_1, _2) == "meow"));
   func(&m);
   // expectations must be met before end of scope
 }
 ```
 
 [**`_`**](reference.md/#wildcard) is a special matcher that matches everything.
 [**`.WITH(...)`**](reference.md/#WITH) is a construction used for when simple
 matchers aren't enough. If a call is made which matches the values given in
 the [**`REQUIRE_CALL(...)`**](reference.md/#REQUIRE_CALL), the selection process
 continues in [**`.WITH(std::string(_1, _2) == "meow")`**](reference.md/#WITH).
 
 **`_1`** and **`_2`** are the parameters to the call, so in this case a
 `std::string` is constructed using the non-null `const char*` and the length,
 and its value is compared with `"meow"`.
 
 The expression in [**`.WITH(...)`**](reference.md/#WITH) can be anything at all
 that returns a boolean value. It can refer to global variables, for example.
 
 It is important to understand that [**`.WITH(...)`**](reference.md/#WITH)
 accesses any local variable used in the expression as a copy. If you want to
 refer to a local variable by reference, use
 [**`.LR_WITH(...)`**](reference.md/#LR_WITH) instead (`LR_` for
 "local reference").
 
 ### <A name="matching_non_copyable"/> Matching `std::unique_ptr<T>` and other non-copyable values
 
 Matching parameter values that you cannot copy, or do not want to copy,
 requires a bit of thought.
 
 The wildcards [**`_`**](reference.md/#wildcard) and
 [**`ANY(...)`**](reference.md/#ANY) works. For `std::unique_ptr<T>` and
 `std::shared_ptr<T>`, the matcher [**`ne(nullptr)`**](reference.md/#ne) also
 works.
 
 If you want to be more specific, you will need to use
 [**`.WITH(...)`**](reference.md/#WITH) or
 [**`.LR_WITH(...)`**](reference.md/#LR_WITH)
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(std::unique_ptr<int>));
 };
 
 using trompeloeil::ne;
 
 void test()
 {
   Mock m;
   REQUIRE_CALL(m, func(ne(nullptr)))
     .WITH(*_1 == 3);
   func(&m);
   // expectations must be met before end of scope
 }
 ```
 
 Above there is a requirement that the function is called with a non-null
 `std::unique_ptr<int>`, which points to a value of `3`.
 
 If the signature of the function is to a reference, you can also use
 [`std::ref()`](https://en.cppreference.com/w/cpp/utility/functional/ref) to
 bind a reference in the expectation.
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(std::unique_ptr<int>&));
 };
 
 void func_to_test(Mock& m, std::unique_ptr<int>& ptr);
 
 void test()
 {
   Mock m;
   auto p = std::make_unique<int>(3);
   {
     REQUIRE_CALL(m, func(std::ref(p)))
       .LR_WITH(&_1 == &p); // ensure same object, not just equal value
     func_to_test(m, p);
   }
 }
 ```
 
 Note that the check for a matching parameter defaults to using `operator==`.
 If you want to ensure that it is the exact same object, not just one with the
 same value, you need to compare the addresses of the parameter and the
 expected value, as shown in the example above.
 
 ### <A name="matching_overloads"/> Matching calls to overloaded member functions
 
 Distinguishing between overloads is simple when using exact values to match
 since the type follows the values. It is more difficult when you want to use
 wildcards and other [matchers](reference.md/#matcher).
 
 One useful matcher is [**`ANY(...)`**](reference.md/#ANY), which behaves
 like the open wildcard [**`_`**](reference.md/#wildcard), but has a type.
 It is also possible to specify types in the matchers.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int*));
   MAKE_MOCK1(func, void(char*));
 };
 
 using namespace trompeloeil;
 
 void test()
 {
   Mock m;
 
   REQUIRE_CALL(m, func(ANY(int*)));
   REQUIRE_CALL(m, func(ne<char*>(nullptr)));
 
   func(&m);
 }
 ```
 
 Above, each of the `func` overloads must be called once, the `int*` version with
 any pointer value at all, and the `char*` version with a non-null value.
 
 Matching overloads on constness is done by placing the expectation on
 a const or non-const object.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int));
   MAKE_CONST_MOCK1(func, void(int));
 };
 
 void test()
 {
   Mock m;
 
   REQUIRE_CALL(m, func(3));   // non-const overload
 
   const Mock& mc = m;
   REQUIRE_CALL(mc, func(-3)); // const overload
 
   m.func(3); // calls non-const overload
   mc.func(-3); // calls const overload
 }
 ```
 
 ### <A name="side_effects"/> Define side effects for matching calls
 
 A side effect, in *Trompeloeil* parlance, is something that is done after
 a match has been made for an [expectation](reference.md/#expectation), and
 before returning (or throwing).
 
 Typical side effects are:
 
 - Setting out parameters
 - Capturing in parameters
 - Calling other functions
 
 Example:
 
 ```Cpp
 class Dispatcher
 {
 public:
   MAKE_MOCK1(subscribe, void(std::function<void(const std::string&)>));
 };
 
 using trompeloeil::_;
 
 void test()
 {
   Dispatcher d;
 
   std::vector<std::function<void(const std::string&)>> clients;
 
   {
     REQUIRE_CALL(d, subscribe(_))
       .LR_SIDE_EFFECT(clients.push_back(std::move(_1)))
       .TIMES(AT_LEAST(1));
 
     func(&d);
   }
   for (auto& cb : clients) cb("meow");
 }
 ```
 
 Above, any call to `d.subscribe(...)` will have the side effect that the
 parameter value is stored in the local vector `clients`.
 
 The test then goes on to call all subscribers.
 
 [**`LR_SIDE_EFFECT(...)`**](reference.md/#LR_SIDE_EFFECT) accesses references
 to local variables. There is also
 [**`SIDE_EFFECT(...)`**](reference.md/#SIDE_EFFECT), which accesses copies of
 local variables.
 
 ### <A name="return_values"/> Return values from matching calls
 
 An [expectation](reference.md/#expectation) on a non-void function
 must return something or [throw](#throw) an exception. There are no default
 values. Returning is easy, however. Just use a
 [**`.RETURN(...)`**](reference.md/#RETURN) or
 [**`.LR_RETURN(...)`**](reference.md/#LR_RETURN) with an expression of
 the right type.
 
 Example:
 
 ```Cpp
 class Dictionary
 {
 public:
   using id_t = size_t;
   MAKE_MOCK1(lookup, std::string(id_t));
 };
 
 using trompeloeil::ge; // greater than or equal
 using trompeloeil::lt; // less than
 
 void test()
 {
   Dictionary d;
   std::vector<std::string> dict{...};
 
   ALLOW_CALL(d, lookup(ge(dict.size())))
     .RETURN("");                          // create std::string from ""
   ALLOW_CALL(d, lookup(lt(dict.size())))
     .LR_RETURN(dict[_1]);                 // access element in vector
   func(&d);
 }
 ```
 
 Above, the [matchers](reference.md/#matcher) [**`lt(...)`**](reference.md/#lt)
 and [**`ge(...)`**](reference.md/#ge) are used to ensure that the indexing
 in the local variable `dict` can be made safely. Note that the first
 [expectation](reference.md/#expectation) does not match the return type
 exactly, but is something that can be implicitly converted.
 
 [**`LR_RETURN(...)`**](reference.md/#LR_RETURN) is used in the second to
 avoid copying the vector, since [**`RETURN(...)`**](reference.md/#RETURN)
 always accesses copies of local variables.
 
 ### <A name="return_references"/> Return references from matching calls
 
 Returning references from matching [expectations](reference.md/#expectation)
 exposes some peculiarities in the language. Specifically, it is not
 allowed to return a captured local variable as a reference in
 [**`RETURN(...)`**](reference.md/#RETURN), and in
 [**`LR_RETURN(...)`**](reference.md/#LR_RETURN) a returned variable must be
 decorated to ensure that a reference is intended.
 
 Example:
 
 ```Cpp
 class Dictionary
 {
 public:
   using id_t = size_t;
   MAKE_MOCK1(lookup, const std::string&(id_t));
 };
 
 using trompeloeil::gt; // greater than or equal
 using trompeloeil::lt; // less than
 
 std::string global_empty;
 
 void test()
 {
   Dictionary d;
   std::vector<std::string> dict{...};
 
   std::string empty;
 
   ALLOW_CALL(d, lookup(gt(dict.size())))
     .LR_RETURN((empty));                // extra () -> reference to local variable
   ALLOW_CALL(d, lookup(dict.size()))
     .LR_RETURN(std::ref(empty));        // reference to local variable
   ALLOW_CALL(d, lookup(lt(dict.size())))
     .LR_RETURN(dict[_1]);               // result of function call
   ALLOW_CALL(d, lookup(0))
     .RETURN(std::ref(global_empty));    // reference to global variable
   func(&d);
 }
 ```
 
 Captured variables that are returned as references must either be enclosed in
 extra parenthesis, or
 [`std::ref()`](http://en.cppreference.com/w/cpp/utility/functional/ref).
 
 Returning a reference obtained from a function call, however, does not
 require any extra decoration, as the third
 [expectation](reference.md/#expectation) above, which looks up values in
 `dict` shows.
 
 ### <A name="throw"/> Throwing exceptions from matching calls
 
 To throw an exception, just add a [**`.THROW(...)`**](reference.md/#THROW)
 or [**`.LR_THROW(...)`**](reference.md/#LR_THROW), with the value to throw.
 For non-void functions, [**`.LR_THROW(...)`**](reference.md/#LR_THROW) and
 [**`.THROW(...)`**](reference.md/#THROW) takes the place of a
 [**`.RETURN(...)`**](reference.md/#RETURN) or
 [**`.LR_RETURN(...)`**](reference.md/#LR_RETURN).
 
 Example:
 
 ```Cpp
 class Dictionary
 {
 public:
   using id_t = size_t;
   MAKE_CONST_MOCK1(lookup, const std::string&(id_t));
 };
 
 using trompeloeil::_; // matches anything
 
 void test()
 {
   Dictionary d;
   std::vector<std::string> dict{...};
 
   ALLOW_CALL(d, lookup(_))
     .LR_WITH(_1 >= dict.size())
     .THROW(std::out_of_range("index too large for dictionary"));
 
   ALLOW_CALL(d, lookup(_))
     .LR_WITH(_1 < dict.size())
     .LR_RETURN(dict[_1]);
 
   func(&d);
 }
 ```
 
 Above, any call to `d.lookup(...)` with an index within the size of the
 vector will return the string reference, while any call with an index
 outside the size of the vector will throw a `std::out_of_range` exception.
 
 ### <A name="allowing_any"/> Allowing any call
 
 By default it is illegal to call any
 [mock function](reference.md/#mock_function) and you provide narrow specific
 expectations according to the needs of your test. However, sometimes it makes
 sense to have a wide-open default. That is done with the
 [expectations](reference.md/#expectation)
 [**`ALLOW_CALL(...)`**](reference.md/#ALLOW_CALL) and
 [**`NAMED_ALLOW_CALL(...)`**](reference.md/#NAMED_ALLOW_CALL). The difference
 between them is that **`ALLOW_CALL`** is local in nature and is only valid
 until the end of the scope, while **`NAMED_ALLOW_CALL(...)`** can be bound
 to a `std::unique_ptr<trompeloeil::expectation>`, which you can control the
 lifetime of.
 
 Example:
 
 ```Cpp
 template <typename T>
 class Allocator
 {
 public:
   MAKE_MOCK1(allocate, T*(size_t));
   MAKE_MOCK1(deallocate, void(T*));
 };
 
 using trompeloeil::_;
 
 void test_no_mem()
 {
   Allocator<int> ai;
 
   ALLOW_CALL(ai, allocate(_))
     .RETURN(nullptr);
 
   ALLOW_CALL(ai, deallocate(nullptr));
 
   hairy_int_job(&ai);
 }
 ```
 
 The simplistic allocator above is rigged to allow any attempts to allocate
 memory, but always return `nullptr`, and only allow deallocation of
 `nullptr`.
 
 ### <A name="temporary_disallow"/> Temporarily disallowing matching calls
 
 Just as it is sometimes convenient to provide a blanket default behaviour,
 it is sometimes desirable to temporarily ban calls.
 
 Example:
 
 ```Cpp
 #include "hairy_job.h"
 
 template <typename T>
 class Allocator
 {
 public:
   MAKE_MOCK1(allocate, T*(size_t));
   MAKE_MOCK1(deallocate, void(T*));
 };
 
 using trompeloeil::_;
 
 void test_restricted_mem()
 {
   Allocator<int> ai;
 
   ALLOW_CALL(ai, allocate(_))
     .RETURN(new int[_1]);
 
   ALLOW_CALL(ai, deallocate(_))
     .SIDE_EFFECT(delete[] _1);
 
   hairy_job<int, Allocator<int>> job(ai, initial_data);
 
   {
     FORBID_CALL(ai, allocate(_));
 
     job.churn(); // must not allocate memory
   }
 
   job.get_result(); // may allocate memory
 }
 ```
 
 Above we see a simplistic Allocator that by default allocates and deallocates
 arrays.
 
 The `hairy_job` uses the Allocator for its setup, and is expected to allocate
 all memory it needs for `churn()` in its constructor.
 
 That `churn()` doesn't use the allocator is ensured by the local scope, in
 which all calls to `allocate(...)` are forbidden.
 
 This pattern is quite common when writing tests with *Trompeloeil*. Use
 wide defaults in the scope of the test case (or in a fixture), and use
 local scopes with specifics, be they forbidden or exact requirements.
 
 ### <A name="sequences"/> Expecting several matching calls in some sequences
 
 By default all [expectations](reference.md/#expectation) are equal, and the
 only sequencing relationship is that if several match a call, the one last
 created is the one matched.
 
 This means that [expectations](reference.md/#expectation) that do not compete
 for matching the same call have no ordering relationship at all, they are
 logically parallel.
 
 Often this is exactly what you want. When you poke an object, you want this and
 that thing to happen and the order between them is irrelevant. For example,
 if calling callbacks stored in a hash table, you don't want to impose an
 order of those calls.
 
 There are two very different reasons for using sequence control with
 *Trompeloeil*.
 
 One is hinted at above, to impose an order between
 [expectations](reference.md/#expectation) that are logically parallel. The
 other is to set an exact order of indistinguishable
 [expectations](reference.md/#expectation). The latter can be achieved by setting
 them up in reverse order of matching, but this can make the test code very
 difficult to read.
 
 First example. Impose an order between logically parallel calls:
 
 ```Cpp
 class FileOps
 {
 public:
   using handle = int;
   MAKE_MOCK1(open, handle(const std::string&));
   MAKE_MOCK3(write, size_t(handle, const char*, size_t));
   MAKE_MOCK1(close, void(handle));
 };
 
 using trompeloeil::ne;
 
 void test()
 {
   FileOps ops;
 
   trompeloeil::sequence seq;
 
   int handle = 4711;
 
   REQUIRE_CALL(ops, open("name"))
     .RETURN(handle)
     .IN_SEQUENCE(seq);
 
   REQUIRE_CALL(ops, write(handle, ne(nullptr), ne(0)))
     .RETURN(_3)
     .IN_SEQUENCE(seq);
 
   REQUIRE_CALL(ops, close(handle))
     .IN_SEQUENCE(seq);
 
   test_writes(&ops);
 }
 ```
 
 Without the use of `trompeloeil::sequence` above, all three
 [expectations](reference.md/#expectation) would be logically parallel and
 all permutations of matches would be considered equally correct.
 
 By imposing an order between them, there is now only one legal sequence
 of calls.
 
 The other example is to provide an order between equally matching calls.
 Suppose we want the `write` function above to first return 0 once and then
 give the desired result:
 
 ```Cpp
 class FileOps
 {
 public:
   using handle = int;
   MAKE_MOCK1(open, handle(const std::string&));
   MAKE_MOCK3(write, size_t(handle, const char*, size_t));
   MAKE_MOCK1(close, void(handle));
 };
 
 using trompeloeil::ne;
 
 void test()
 {
   FileOps ops;
 
   trompeloeil::sequence seq;
 
   int handle = 4711;
 
   REQUIRE_CALL(ops, open("name"))
     .RETURN(handle)
     .IN_SEQUENCE(seq);
 
   REQUIRE_CALL(ops, write(handle, ne(nullptr), ne(0)))
     .RETURN(0)                                         // indicate failure
     .IN_SEQUENCE(seq);
 
   REQUIRE_CALL(ops, write(handle, ne(nullptr), ne(0)))
     .RETURN(_3)                                        // successful retry
     .IN_SEQUENCE(seq);
 
   REQUIRE_CALL(ops, close(handle))
     .IN_SEQUENCE(seq);
 
   test_writes(&ops);
 }
 ```
 
 Here the two calls to `write` are supposed to be made with exactly the same
 parameters, so they cannot be distinguished that way. We want the first
 call to indicate intermittent failure, and to be followed by a retry
 that will succeed.
 
 [**`.IN_SEQUENCE(...)`**](reference.md/#IN_SEQUENCE) can refer to several
 sequence objects, which is a way to allow some variation in order, without
 being too lax. For a more thorough walk through, see the blog post [Sequence
 control with the Trompeloeil C\+\+14 Mocking Framework](http://playfulprogramming.blogspot.se/2015/01/sequence-control-with-trompeloeil-c.html)
 
 [**`.IN_SEQUENCE(...)`**](reference.md/#IN_SEQUENCE) can also be used on
 [**`REQUIRE_DESTRUCTION(...)`**](reference.md/#REQUIRE_DESTRUCTION) and
 [**`NAMED_REQUIRE_DESTRUCTION(...)`**](reference.md/#NAMED_REQUIRE_DESTRUCTION).
 
 ### <A name="match_count"/> Expecting matching calls a certain number of times
 
 By default [**`REQUIRE_CALL(...)`**](reference.md/#REQUIRE_CALL) needs exactly
 one matching call, otherwise a violation is reported. Sometimes the need is
 for something else. A modifier [**`TIMES(...)`**](reference.md/#TIMES) is used
 to change that. You can either specify an exact number of times matching calls
 must be made, or a range of numbers.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int));
 };
 
 void some_test()
 {
   Mock m;
 
   REQUIRE_CALL(m, func(0))
     .TIMES(2);
 
   REQUIRE_CALL(m, func(1))
     .TIMES(3, 5);
 
   REQUIRE_CALL(m, func(2))
     .TIMES(AT_LEAST(3));
 
   REQUIRE_CALL(m, func(3))
     .TIMES(AT_MOST(4));
 
   func(&m);
 }
 ```
 
 Above, `m.func(0)` must be called exactly twice. `m.func(1)` must be called three,
 four or five times. The call `m.func(2)` must be made three or more times. Finally
 `m.func(4)` must not be called more than four times.
 
 ## <A name="lifetime"/> Controlling lifetime of mock objects
 
 If you test a case where you hand over ownership of a
 [mock object](reference.md/#mock_object), you may want to test that the mock
 object is destroyed when intended. For this there is a modifier class
 template `trompeloeil::deathwatched<T>` and the macros
 [**`REQUIRE_DESTRUCTION(...)`**](reference.md/#REQUIRE_DESTRUCTION) and
 [**`NAMED_REQUIRE_DESTRUCTION(...)`**](reference.md/#NAMED_REQUIRE_DESTRUCTION).
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   virtual ~Mock() {}          // virtual destructor required for deathwatched<>
   MAKE_MOCK1(func, void(int));
 }
 
 template <typename T>
 class consumer
 {
 public:
   consumer(T&&);
   void poke(int n);
 private:
   ...
 };
 
 void consume_test()
 {
   auto owner = std::make_unique<trompeloeil::deathwatched<Mock>>();
 
   auto mock = owner.get(); // use raw unowned pointer
 
   consumer<Mock> c(std::move(owner));
 
   {
     REQUIRE_CALL(*mock, func(3));
 
     c.poke(3);
   }
   {
     REQUIRE_CALL(*mock, func(-1));
     REQUIRE_DESTRUCTION(*mock);
 
     c.poke(0);
   }
 }
 ```
 
 Above, the constructor of object `c` takes ownership of the
 [mock object](reference.md/#mock_object).
 
 Since the mock object is on deathwatch, destruction is reported as a violation.
 Thus we can be sure that if the constructor destroys the mock object, the
 test will fail. Likewise if the call `c.poke(3)` would destroy the mock object.
 
 The local scope afterwards has a requirement that the mock object *is* destroyed.
 If the call `c.poke(0)` does not destroy the mock, a violation will be reported
 and fail the test. There is an implied order that the mock function
 `func(-1)` is called before the destruction of the mock object,
 since destroying any mock object that still has
 [expectations](reference.md/#expectation) is reported as a violation. It is also
 possible to be explicit with the sequencing by using
 [**`IN_SEQUENCE(...)`**](reference.md/#IN_SEQUENCE) on both
 [**`REQUIRE_CALL(...)`**](reference.md/#REQUIRE_CALL) and
 [**`REQUIRE_DESTRUCTION(...)`**](reference.md/#REQUIRE_DESTRUCTION), as below:
 
 ```Cpp
   {
     trompeloeil::sequence s;
     REQUIRE_CALL(*mock, func(-1));
       .IN_SEQUENCE(s);
     REQUIRE_DESTRUCTION(*mock);
       .IN_SEQUENCE(s);
 
     c.poke(0);
   }
 ```
 
 ## <A name="custom_formatting"/> Customize output format of values
 
 When [tracing](#tracing) or printing parameter values in violation reports,
 the values are printed using their
 [stream insertion operators](http://en.cppreference.com/w/cpp/io/basic_ostream/operator_ltlt),
 if available, or hexadecimal dumps otherwise. If this is not what you want, you
 can provide your own output formatting used solely for testing.
 
 The simple way to do this is to specialize a template [`printer<T>`](reference.md/#printer),
 in namespace `trompeloeil`, and its static member function `print`, for your type `T`.
 
 Example:
 
 ```Cpp
 class char_buff : public std::vector<char>
 {
   ...
 };
 
 namespace trompeloeil {
   template <>
   struct printer<char_buff>
   {
     static void print(std::ostream& os, const char_buff& b)
     {
       os << b.size() << "#{ ";
       for (auto v : b) { os << int(v) << " "; }
       os << "}";
     }
 };
 }
 ```
 
 Any reports involving the `char_buff` above will be printed using the
 `trompeloeil::print<char_buff>(...)` function, showing the size and integer values.
 
 Note that partial specializations also work. Example:
 
 ```Cpp
 template <typename T>
 class buff : public std::vector<T>
 {
   ...
 };
 
 namespace trompeloeil {
   template <typename T>
   struct printer<buff<T>>
   {
     static void print(std::ostream& os, const buff<T>& b)
     {
       os << b.size() << "#{ ";
       for (auto v : b) { os << v << " "; }
       os << "}";
     }
 };
 }
 ```
 
 **NOTE!** Older documentation refers to specializing a function
 [`trompeloeil::print(sd::ostream&, T const&)`](reference.md/#print). This still works, but has the
 disadvantage that partial specializations are not possible.
 
 ## <A name="tracing"/> Tracing mocks
 
 *Trompeloeil* offers tracing as a way of manually following the calls of mocks.
 In pure [TDD](https://en.wikipedia.org/wiki/Test-driven_development) this is
 hardly ever needed, but if you are in the undesirable situation of exploring
 the behaviour of code written without tests, tracing can vastly simplify your
 job.
 
 Simply put, tracing is exposing which mocks are called with which values.
 
 *Trompeloeil* offers a [*`stream_tracer`*](#stream_tracer), which outputs
 all calls to a
 [`std::ostream`](http://en.cppreference.com/w/cpp/io/basic_ostream), but you
 can also write your own [custom tracer](#custom_tracer).
 
 ### <A name="stream_tracer"/> Using `trompeloeil::stream_tracer`
 
 *`stream_tracer`* is a mechanism used to find out how
 [mock functions](reference.md/#mock_function) are called, by simply
 printing the calls with their parameter values on a
 [`std::ostream`](http://en.cppreference.com/w/cpp/io/basic_ostream) like
 [`std::cout`](http://en.cppreference.com/w/cpp/io/cout).
 
 There is no requirement from *Trompeloeil* on the
 [expectations](reference.md/#expectation) placed on the mocks, but open
 blanket [**`ALLOW_CALL(...)`**](reference.md/#ALLOW_CALL) can be a good
 start until more detailed tests can be written.
 
 Example:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(create, int(const std::string&));
   MAKE_MOCK1(func, std::string(int));
 };
 
 using trompeloeil::_;
 
 void tracing_test()
 {
   trompeloeil::stream_tracer tracer{std::cout};
 
   Mock m;
 
   ALLOW_CALL(m, create(_))
     .RETURN(3);
 
   ALLOW_CALL(m, func(_))
     .RETURN("value");
 
   weird_func(&m);
 }
 ```
 
 Running the above test will print on `std::cout` all calls made. A sample
 output may be:
 
 ```text
 /tmp/t.cpp:33
 m.create(_) with.
   param  _1 = hello
 
 /tmp/t.cpp:36
 m.func(_) with.
   param  _1 = 3
 
 /tmp/t.cpp:36
 m.func(_) with.
   param  _1 = 2
 
 /tmp/t.cpp:36
 m.func(_) with.
   param  _1 = 1
 ```
 
 ### <A name="custom_tracer"/> Writing custom tracers
 
 If tracing is important, but the `trompeloeil::stream_tracer` for some reason
 does not satisfy your needs, you can easily write your own tracer.
 
 There is a base class:
 
 ```Cpp
 namespace trompeloeil {
 
 class tracer {
 public:
   tracer();
   virtual ~tracer();
   virtual void trace(const char* file,
                      unsigned long line,
                      const std::string& call) = 0;
 };
 
 }
 ```
 
 Write your own class inheriting from `trompeloeil::tracer`, and implement the
 member function `trace`, to do what you need, and you're done.
 
 ## <A name="custom_matchers"/> Writing custom matchers
 
 If you need additional matchers over the ones provided by *Trompeloeil*
 ([**`eq(...)`**](reference.md/#eq), [**`ne(...)`**](reference.md/#ne),
 [**`lt(...)`**](reference.md/#lt), [**`le(...)`**](reference.md/#le),
 [**`gt(...)`**](reference.md/#gt) or [**`ge(...)`**](reference.md/#ge),
 and [**`re(...)`**](reference.md/#re)), you can easily do so.
 
 Matchers are created using the aptly named function template
 [**`trompeloeil::make_matcher<Type>(...)`**](reference.md/#make_matcher),
 which takes a predicate lambda to check the condition, a print lambda for
 error messages, and any number of stored values.
 
 All matchers, including your own custom designed matchers, can be used as
 [pointer matchers](#matching_pointers) by using the unary prefix `*`
 dereference operator.
 
 ### <A name="typed_matcher"/> Typed matcher
 
 The simplest matcher is a typed matcher. As an example of a typed matcher, an
 `any_of` matcher is shown, checking if a value is included in a range of
 values. It is implemented using the standard library algorithm
 [`std::any_of`](http://en.cppreference.com/w/cpp/algorithm/all_any_none_of),
 allowing a parameter to match any of a set of values.
 
 To create a matcher, you provide a function that calls
 [**`trompeloeil::make_matcher<Type>(...)`**](reference.md/#make_matcher).
 
 Below is the code for the function `any_of(std::initializer_list<int>)`
 which creates the matcher.
 
 ```Cpp
   inline auto any_of(std::initializer_list<int> elements)
   {
     return trompeloeil::make_matcher<int>( // matcher of int
 
       // predicate lambda that checks the condition
       [](int value, std::vector<int> const & alternatives) {
         return std::any_of(std::begin(alternatives), std::end(alternatives),
                            [&value](int element) { return value == element; });
       },
 
       // print lambda for error message
       [](std::ostream& os, std::vector<int> const& alternatives) {
         os << " matching any_of({";
         char const* prefix=" ";
         for (auto& element : alternatives)
         {
           os << prefix << element;
           prefix = ", ";
         }
         os << " }";
       },
 
       // stored value
       std::vector<int>(elements)
     )
   }
 ```
 
 The *predicate* lambda is called with the value to check, and the stored values
 in order.
 
 The *print* lambda is called with an `ostream&`, and the stored values in
 order.
 
 You can capture values in the lambdas instead of storing in the matcher, but
 capturing them twice wastes memory, and what's in the lambda capture for the
 *predicate* lambda is not accessible in the *print* lambda.
 
 Example usage:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int));
 };
 
 void test()
 {
   Mock m;
   REQUIRE_CALL(m, func(any_of({1, 2, 4, 8})));
 
   m.func(7);
 }
 ```
 
 The *print* lambda is only called if a failure is reported.
 The report in the above example will look like:
 
 ```text
 No match for call of m.func with signature void(int) with.
   param  _1 = 7
 
 Tried m.func(any_of({1, 2, 4, 8}) at file.cpp:12
   Expected _1 matching any_of({ 1, 2, 4, 8 });
 ```
 
 Where everything after `Expected _1` is the output from the *print* lambda.
 
 Extending the example above to work with any type, using a template, is
 straight forward:
 
 ```Cpp
   template <typename T>
   inline auto any_of(std::initializer_list<T> elements)
   {
     return trompeloeil::make_matcher<T>( // matcher of T
 
       // predicate lambda that checks the condition
       [](T const& value, std::vector<T> const & alternatives) {
         return std::any_of(std::begin(alternatives), std::end(alternatives),
                            [&value](T const& element) { return value == element; });
       },
 
       // print lambda for error message
       [](std::ostream& os, std::vector<T> const& alternatives) {
         os << " matching any_of({";
         char const* prefix=" ";
         for (auto& element : alternatives)
         {
           os << prefix;
           ::trompeloeil::print(os, element);
           prefix = ", ";
         }
         os << " }";
       },
 
       // stored value
       std::vector<T>(elements)
     )
   }
 ```
 
 The only difference compared to the `int` version, is that the *predicate*
 lambda accepts values by `const&` instead of by value, since `T` might be
 expensive to copy, and that the *print* lambda uses
 [**`trompeloeil::print(...)`**](reference.md/#print) to print the elements.
 
 ### <A name="duck_typed_matcher"/> Duck-typed matcher
 
 A duck-typed matcher accepts any type that matches a required set of
 operations. An example of a duck-typed matcher is a
 [`not_empty()`](#not_empty) matcher, requiring that a `.empty()` member function
 of the parameter returns false. Another example is an
 [`is_clamped(min, max)`](#is_clamped) matcher, that ensures
 `min <= value && value <= max`.
 
 A duck-typed matcher is created by specifying
 [**`trompeloeil::wildcard`**](reference.md/#wildcard) as the type to
 to [**`trompeloeil::make_matcher<Type>(...)`**](reference.md/#make_matcher).
 
 It is also important that the *predicate* lambda uses a
 [trailing return type](http://arne-mertz.de/2015/08/new-c-features-auto-for-functions)
 specifier, which uses the required operations, in order to filter out calls
 that would not compile.
 
 #### <A name="not_empty"/> A `not_empty()` matcher
 
 Here's an implementation of a `not_empty()` matcher.
 
 ```Cpp
   inline auto not_empty()
   {
     return trompeloeil::make_matcher<trompeloeil::wildcard>( // duck typed
 
       // predicate lambda that checks the condition
       [](auto const& value) -> decltype(!value.empty()) {
         return !value.empty();
       },
 
       // print lambda for error message
       [](std::ostream& os) {
         os << " is not empty";
       }
 
       // no stored values
     );
   }
 ```
 
 It is unfortunate that the `!value.empty()` condition is expressed twice,
 but those are the rules of the language.
 
 Here's an example of the usage.
 
 ```Cpp
   struct C
   {
     MAKE_MOCK1(func, void(int));
     MAKE_MOCK1(func, void(std::string&&));
     MAKE_MOCK1(func2, void(std::vector<int> const&);
   };
 
   void test()
   {
     C obj;
     REQUIRE_CALL(obj, func(not_empty()));  // std::string&&
     REQUIRE_CALL(obj, func2(not_empty())); // std::vector<int> const&
     func_under_test(&obj);
   }
 ```
 
 The expectation placed on `func()` is not ambiguous. While `func()` is
 overloaded on both `int` and `std::string&&`, the trailing return type
 specification on the *predicate* lambda causes
 [`SFINAE`](http://en.cppreference.com/w/cpp/language/sfinae) to kick in and
 chose only the `std::string&&` overload, since `.empty()` on an `int` would
 not compile.
 
 If you make a mistake and place an expectation with a duck-typed matcher
 that cannot be used, the
 [`SFINAE`](http://en.cppreference.com/w/cpp/language/sfinae) on the
 trailing return type specification of the *predicate* lambda, ensures a
 compilation error at the site of
 use ([**`REQUIRE_CALL()`**](reference.md/#REQUIRE_CALL),
 [**`ALLOW_CALL()`**](reference.md/#ALLOW_CALL) or
 [**`FORBID_CALL()`**](reference.md/#FORBID_CALL).)
 
 **TIP!** The expectation on `func()` in the example above is not
 ambiguous, as explained, but what if `func2` had been yet an overload of
 `func()` instead? You can easily make your matchers typed or duck-typed
 at the user's discretion. Alter the `not_empty()` to be a function template,
 with `trompeloeil::wildcard` as the default.
 
 ```Cpp
   template <typename Type = trompeloeil::wildcard>
   inline auto not_empty()
   {
     return trompeloeil::make_matcher<Type>( // typed or duck typed
 
       // predicate lambda that checks the condition
       [](auto const& value) -> decltype(!value.empty()) {
         return !value.empty();
       },
 
       // print lambda for error message
       [](std::ostream& os) {
         os << " is not empty";
       }
 
       // no stored values
     );
   }
 ```
 
 Now, if the user writes `EXPECT_CALL(obj, func(not_empty()))`, it is
 duck-typed, but if the user writes `EXPECT_CALL(obj, func<std::string&&>()`
 it will only match a call with a `std::string&&` parameter.
 
 #### <A name="is_clamped"/> An `is_clamped(min, max)` matcher
 
 Here's an implementation of an `is_clamped(min, max)` matcher.
 
 ```Cpp
   template <typename Type = trompeloeil::wildcard, typename T, typename U>
   inline auto is_clamped(T const& min, U const& max)
   {
     return trompeloeil::make_matcher<Type>( // typed or duck typed
 
       // predicate lambda that checks the condition
       [](auto const& value, auto const& lower, auto const& upper)
        -> decltype(lower <= value && value <= upper)
       {
         return !trompeloeil::is_null(value) && lower <= value && value <= upper;
       },
 
       // print lambda for error message
       [](std::ostream& os, auto const& lower, auto const& upper) {
         os << " clamped by [";
         trompeloeil::print(os, lower);
         os << ", ";
         trompeloeil::print(os, upper);
         os << "]";
       }
 
       // stored values
       min,
       max
     );
   }
 ```
 
 The [`trompeloeil::is_null(value)`](reference.md/#is_null) in the *predicate*
 lambda is there to prevent against e.g. clamp checks for `const char*` between
 two [`std::string`s](http://en.cppreference.com/w/cpp/string/basic_string),
 where the `const char*` may be *null*. The `is_null()` check is omitted in the
 trailing return specification,
 because it does not add anything to it - it always returns a `bool` and
 it works for all types.
 
 By allowing `min` and `max` to be different types, it becomes possible to,
 e.g. check that a
 [`std::string_view`](http://en.cppreference.com/w/cpp/string/basic_string_view)
 is clamped by a
 [`std::string`](http://en.cppreference.com/w/cpp/string/basic_string)
 and a `const char*`.
 
 **NOTE!** There is a bug in [GCC](https://gcc.gnu.org) versions 5.3 and
 lower, that does not allow trailing return type specifications in
 lambdas expressed in template functions. The work around is annoying but
 simple:
 
 ```Cpp
   inline auto is_clamped_predicate()
   {
     return [](auto const& value, auto const& lower, auto const& upper)
            -> decltype(lower <= value && value <= upper) {
              return !trompeloeil::is_null(value) && lower <= value && value <= upper;
            };
   }
 
   template <typename Type = trompeloeil::wildcard, typename T, typename U>
   inline auto is_clamped(T const& min, U const% max)
   {
     return trompeloeil::make_matcher<Type>( // duck typed
 
       // predicate lambda that checks the condition
       is_clamped_predicate(),
       ...
 ```
 
 **NOTE!** There is also a bug in
 [VisualStudio 2015 Update 3](https://www.visualstudio.com/en-us/news/releasenotes/vs2015-update3-vs),
 which does not respect the trailing return type specifications of
 lambdas in the context of template deduction. The work around is annoying but
 simple - use a `struct` instead:
 
 ```Cpp
   struct is_clamped_predicate
   {
     template <typename T, typename L, typename U>
     auto operator()(T const& value, L const& lower, U const& upper)
     -> decltype(lower <= value && value <= upper)
     {
       return !trompeloeil::is_null(value) && lower <= value && value <= upper;
     }
   };
 
   template <typename Type = trompeloeil::wildcard, typename T, typename U>
   inline auto is_clamped(T const& min, U const% max)
   {
     return trompeloeil::make_matcher<Type>( // duck typed
 
       // predicate lambda that checks the condition
       is_clamped_predicate(),
       ...
 ```
 
 ### <A name="legacy_matcher"/> Legacy Matchers
 
 Before [**`trompeloeil::make_matcher<Type>(...)`**](reference.md/#make_matcher)
 was introduced in *Trompeloeil* v18, writing matchers was more elaborate.
 This section is here for those who need to maintain old matcher code.
 
 All legacy matchers
 
 - inherit from `trompeloeil::matcher` or `trompeloeil::typed_matcher<T>`
 - implement a `bool matches(parameter_value) const` member function
 - implement an output stream insertion operator
 
 All legacy matchers can be used as
 [pointer matchers](#matching_pointers) by using the unary prefix `*` dereference
 operator.
 
 ### Typed legacy matcher
 
 Typed legacy matchers are relatively easy to understand. As an example of
 a typed matcher, an `any_of` matcher is shown, mimicking the behaviour of
 the standard library algorithm
 [`std::any_of`](http://en.cppreference.com/w/cpp/algorithm/all_any_none_of),
 allowing a parameter to match any of a set of values.
 
 For templated matchers, it is often convenient to provide a function that
 creates the matcher object. Below is the code for `any_of_t<T>`, which is the
 matcher created by the `any_of(std::vector<T>)` function template.
 
 ```Cpp
   template <typename T>
   class any_of_t : public trompeloeil::typed_matcher<T>
   {
   public:
     any_of_t(std::initializer_list<T> elements)
     : alternatives(elements)
     {
     }
     bool matches(T const& t) const
     {
       return std::any_of(std::begin(alternatives), std::end(alternatives),
                          [&t](T const& val) { return t == val; });
     }
     friend std::ostream& operator<<(std::ostream& os, any_of_t<T> const& t)
     {
       os << " matching any_of({";
       char const* prefix=" ";
       for (auto& n : t.alternatives)
       {
         os << prefix;
         trompeloeil::print(os, n);
         prefix = ", ";
       }
       return os << " })";
     }
   private:
     std::vector<T> alternatives;
   };
 
   template <typename T>
   auto any_of(std::initializer_list<T> elements)
   {
     return any_of_t<T>(elements);
   }
 ```
 
 The `matches` member function at accepts the parameter and returns
 `true` if the value is in the specified set, in this case if it is any
 of the values stored in the `alternatives` vector, otherwise `false`.
 
 Example usage:
 
 ```Cpp
 class Mock
 {
 public:
   MAKE_MOCK1(func, void(int));
 };
 
 void test()
 {
   Mock m;
   REQUIRE_CALL(m, func(any_of({1, 2, 4, 8}));
 
   m.func(7);
 }
 ```
 
 The output stream insertion operator is only called if a failure is reported.
 The report in the above example will look like:
 
 ```text
 No match for call of m.func with signature void(int) with.
   param  _1 = 7
 
 Tried m.func(any_of({1, 2, 4, 8}) at file.cpp:12
   Expected _1 matching any_of({ 1, 2, 4, 8 });
 ```
 
 Where everything after `Expected _1` is the output from the stream insertion
 operator.
 
 ### Duck-typed legacy matcher
 
 A duck-typed matcher accepts any type that matches a required set of
 operations. Duck-typed legacy matchers have a type conversion operator that
 selects which types it can operate on. The conversion operator is
 never implemented, but the signature must be available since it
 is used at compile time to select overload.
 
 As an example of a duck-typed matcher is a `not_empty` matcher, requiring
 that a `.empty()` member function of the parameter returns false.
 
 First the restricting
 [SFINAE](http://en.wikipedia.org/wiki/Substitution_failure_is_not_an_error)
 predicate used to match only types that has a `.empty()` member function.
 
 ```Cpp
   template <typename T>
   class has_empty
   {
     template <typename U>
     static constexpr std::false_type func(...) { return {}; }
     template <typename U>
     static constexpr auto func(U const* u) -> decltype(u->empty(),std::true_type{})
     {
       return {};
     }
   public:
     static const bool value = func<T>(nullptr);
   };
 ```
 
 Here `has_empty<T>::value` is true only for types `T` that has a `.empty()`
 member function callable on const objects.
 
 ```Cpp
   class not_empty : public trompeloeil::matcher
   {
   public:
     template <typename T,
               typename = std::enable_if_t<has_empty<T>::value>>
     operator T() const;            //1
     template <typename T>
     bool matches(T const& t) const //2
     {
       return !t.empty();
     }
     friend std::ostream& operator<<(std::ostream& os, not_empty const&)
     {
       return os << " is not empty";
     }
   };
 ```
 
 At **//1** the type conversion operator selects for types that has a
 `.empty()` member function.
 [`std::enable_if_t<>`](http://en.cppreference.com/w/cpp/types/enable_if)
 ensures that no calls to mismatching types will occur, and that if no
 matching call can be found, a compilation error is generated at the site of
 use ([**`REQUIRE_CALL()`**](reference.md/#REQUIRE_CALL),
 [**`ALLOW_CALL()`**](reference.md/#ALLOW_CALL) or
 [**`FORBID_CALL()`**](reference.md/#FORBID_CALL).)
 
 The `matches(T const&)` member function at **//2** becomes very simple. It
 does not need the [SFINAE](
   http://en.wikipedia.org/wiki/Substitution_failure_is_not_an_error
 ) [`std::enable_if_t<>`](
   http://en.cppreference.com/w/cpp/types/enable_if
 ) to select valid types, since a type mismatch gives a compilation error
 on the type conversion operator at **//1**.
 
 The output stream insertion operator is neither more or less tricky than with
 typed matchers. Making violation reports readable may require some thought,
 however.