finalizer

Finalizers are the last step of a matching expectation. More...

Functions
template<typename Fun > requires std::invocable<std::remove_cvref_t<Fun>&> && (!std::is_void_v<std::invoke_result_t<std::remove_cvref_t<Fun>&>>)
constexpr auto	mimicpp::finally::returns_result_of (Fun &&fun) noexcept(std::is_nothrow_constructible_v< std::remove_cvref_t< Fun >, Fun >)
	During the finalization step, the invocation result of the given function is returned.
template<typename T > requires std::copyable<std::remove_cvref_t<T>>
constexpr auto	mimicpp::finally::returns (T &&value) noexcept(std::is_nothrow_constructible_v< std::remove_cvref_t< T >, T >)
	During the finalization step, the stored value is returned.
template<std::size_t index, std::size_t... otherIndices, typename Action >
constexpr auto	mimicpp::finally::returns_apply_result_of (Action &&action) noexcept(std::is_nothrow_constructible_v< std::remove_cvref_t< Action >, Action >)
	During the finalization step, the selected call arguments are applied on the given action.
template<typename Action >
constexpr auto	mimicpp::finally::returns_apply_all_result_of (Action &&action) noexcept(std::is_nothrow_constructible_v< std::remove_cvref_t< Action >, Action >)
	During the finalization step, all call arguments are applied on the given action.
template<std::size_t index>
constexpr auto	mimicpp::finally::returns_arg () noexcept
	During the finalization step, the selected call argument is returned.
template<typename T > requires std::copyable<std::remove_cvref_t<T>>
constexpr expectation_policies::Throws< std::remove_cvref_t< T > >	mimicpp::finally::throws (T &&exception) noexcept(std::is_nothrow_constructible_v< std::remove_cvref_t< T >, T >)
	During the finalization step, the given exception is thrown.

Detailed Description

Finalizers are the last step of a matching expectation.

Finalizers are executed for calls, which have a matching expectation. They are responsible for either returning an appropriate return value or leaving the call by throwing an exception.

An expectation must have exactly one finalizer applied. For mocks returning void, an appropriate finalizer is attached by default. This default finalizer can be exchanged once. If an expectation setup contains multiple finalize statements, a compile error is triggered.

Custom Finalizers

There are several provided finalizers, but user may create their own as desired. A valid finalizer has to satisfy the finalize_policy_for concept, which in fact requires the existence of a finalize_call member function.

    class MyFinalizer
    {
    public:
        int finalize_call(const mimicpp::call::Info<int>& callInfo)
        {
            return 1337;
        }
    };
 
    mimicpp::Mock<int()> mock{};
 
    SCOPED_EXP mock.expect_call()
                | MyFinalizer{};
 
    REQUIRE(1337 == mock());

Function Documentation

returns()

template<typename T >
requires std::copyable<std::remove_cvref_t<T>>

auto mimicpp::finally::returns ( T && value )

nodiscardconstexprnoexcept

During the finalization step, the stored value is returned.

Template Parameters

T	The value type.

Parameters

value

The value to be returned.

Returns

Returns a copy of value.

The provided value must be copyable, because multiple invocations must be possible.

    namespace finally = mimicpp::finally;
 
    mimicpp::Mock<int()> mock{};
 
    SCOPED_EXP mock.expect_call()
                | finally::returns(42);
 
    REQUIRE(42 == mock());

This finalizer is aware of std::reference_wrapper, which can be used to return values from the outer scope. Such values are explicitly unwrapped, before they are returned.

    namespace finally = mimicpp::finally;
 
    mimicpp::Mock<int&()> mock{};
 
    int myReturn{42};
    SCOPED_EXP mock.expect_call()
                | finally::returns(std::ref(myReturn));
 
    REQUIRE(&myReturn == &mock());

In fact any value category can be returned; it is the users responsibility to make sure, not to use any dangling references. If an actual value is stored and a reference is returned, this is fine until the expectation goes out of scope.

    namespace finally = mimicpp::finally;
    namespace expect = mimicpp::expect;
 
    mimicpp::Mock<int&()> mock{};
 
    SCOPED_EXP mock.expect_call()
                | expect::twice()   // we call the mock two times
                | finally::returns(42);
 
    int& result = mock();
    REQUIRE(42 == result);  // fine
 
    result = 1337;
    REQUIRE(1337 == mock());

returns_apply_all_result_of()

template<typename Action >

auto mimicpp::finally::returns_apply_all_result_of ( Action && action )

nodiscardconstexprnoexcept

During the finalization step, all call arguments are applied on the given action.

Template Parameters

Action

The action type.

Parameters

action

The action to be applied to.

Returns

Returns the invocation result of the given action.

All call arguments are applied as (possibly const qualified) lvalue-references. The action may proceed with them as desired, but be aware that this may actually affect objects outside the call (e.g. if call arguments are lvalues.).

    namespace finally = mimicpp::finally;
 
    mimicpp::Mock<int(int, int)> mock{};
 
    SCOPED_EXP mock.expect_call(1337, 42)
                | finally::returns_apply_all_result_of(std::plus{});
 
    REQUIRE(1379 == mock(1337, 42));

returns_apply_result_of()

template<std::size_t index, std::size_t... otherIndices, typename Action >

auto mimicpp::finally::returns_apply_result_of ( Action && action )

nodiscardconstexprnoexcept

During the finalization step, the selected call arguments are applied on the given action.

Template Parameters

index	The first selected argument index.
otherIndices	Addition selected arguments.
Action	The action type.

Parameters

action

The action to be applied to.

Returns

Returns the invocation result of the given action.

The selected call arguments are applied as (possibly const qualified) lvalue-references. The action may proceed with them as desired, but be aware that this may actually affect objects outside the call (e.g. if call arguments are lvalues.).

    namespace finally = mimicpp::finally;
 
    mimicpp::Mock<int(int, int)> mock{};
 
    SCOPED_EXP mock.expect_call(1337, 42)
                | finally::returns_apply_result_of<0, 1>(std::plus{});
 
    REQUIRE(1379 == mock(1337, 42));

returns_arg()

template<std::size_t index>

auto mimicpp::finally::returns_arg ( )

nodiscardconstexprnoexcept

During the finalization step, the selected call argument is returned.

Returns

Returns the forwarded and explicitly converted argument.

The selected call argument is forwarded and explicitly converted to the mocks return type.

    namespace finally = mimicpp::finally;
 
    mimicpp::Mock<int(int, int)> mock{};
 
    SCOPED_EXP mock.expect_call(1337, 42)
                | finally::returns_arg<1>();
 
    REQUIRE(42 == mock(1337, 42));

returns_result_of()

template<typename Fun >
requires std::invocable<std::remove_cvref_t<Fun>&> && (!std::is_void_v<std::invoke_result_t<std::remove_cvref_t<Fun>&>>)

auto mimicpp::finally::returns_result_of ( Fun && fun )

nodiscardconstexprnoexcept

During the finalization step, the invocation result of the given function is returned.

    namespace finally = mimicpp::finally;
 
    mimicpp::Mock<std::string()> mock{};
 
    SCOPED_EXP mock.expect_call()
                | finally::returns_result_of([] { return "Hello, World!"; });
 
    REQUIRE("Hello, World!" == mock());

Template Parameters

Fun	The function type.

Parameters

fun	The function to be invoked.

Returns

Forward returns the invocation result of fun.

The provided functions must be invocable without arguments, but may return any type, which is explicitly convertible to the mocks return type.

throws()

template<typename T >
requires std::copyable<std::remove_cvref_t<T>>

expectation_policies::Throws< std::remove_cvref_t< T > > mimicpp::finally::throws ( T && exception )

nodiscardconstexprnoexcept

During the finalization step, the given exception is thrown.

Template Parameters

T	The exception type.

Parameters

exception

The exception to be thrown.

Exceptions

A	copy of exception.

The provided exception must be copyable, because multiple invocations must be possible.

    namespace finally = mimicpp::finally;
 
    mimicpp::Mock<int()> mock{};
 
    SCOPED_EXP mock.expect_call()
                | finally::throws(std::runtime_error{"Something happened."});
 
    REQUIRE_THROWS_AS(
        mock(),
        std::runtime_error);