matchers

Matchers check various argument properties. More...

Collaboration diagram for matchers:

Topics
	range matchers
	Range specific matchers.
	string matchers
	String specific matchers.

Classes
class	mimicpp::PredicateMatcher< Predicate, AdditionalArgs >
	Generic matcher and the basic building block of most of the built-in matchers. More...
class	mimicpp::WildcardMatcher
	Matcher, which never fails. More...

Functions
consteval auto	mimicpp::matches::NaN () noexcept
	Tests, whether the floating-point target is NaN.
constexpr auto	mimicpp::matches::approx_abs (const std::floating_point auto value, const std::floating_point auto epsilon)
	Tests, whether the floating-point target is approximately equal to value.
constexpr auto	mimicpp::matches::approx_rel (const std::floating_point auto value, const std::floating_point auto relEpsilon)
	Tests, whether the floating-point target is approximately equal to value.
template<std::floating_point Float>
constexpr auto	mimicpp::matches::approx_rel (const Float value)
	Tests, whether the floating-point target is approximately equal to value.
template<typename T>
constexpr auto	mimicpp::matches::eq (T &&value)
	Tests, whether the target compares equal to the expected value.
template<typename T>
constexpr auto	mimicpp::matches::ne (T &&value)
	Tests, whether the target compares not equal to the expected value.
template<typename T>
constexpr auto	mimicpp::matches::lt (T &&value)
	Tests, whether the target is less than the expected value.
template<typename T>
constexpr auto	mimicpp::matches::le (T &&value)
	Tests, whether the target is less than or equal to the expected value.
template<typename T>
constexpr auto	mimicpp::matches::gt (T &&value)
	Tests, whether the target is greater than the expected value.
template<typename T>
constexpr auto	mimicpp::matches::ge (T &&value)
	Tests, whether the target is greater than or equal to the expected value.
template<typename UnaryPredicate>
constexpr auto	mimicpp::matches::predicate (UnaryPredicate &&predicate, StringViewT description="passes predicate", StringViewT invertedDescription="fails predicate")
	Tests, whether the target fulfills the given predicate.
template<satisfies< std::is_lvalue_reference > T>
constexpr auto	mimicpp::matches::instance (T &&instance)
	Tests, whether the target is the expected instance.

Variables
constexpr WildcardMatcher	mimicpp::matches::_ {}
	The wildcard matcher, always matching.

Detailed Description

Matchers check various argument properties.

Matchers can be used to check various argument properties and are highly customizable. In general, they simply compare their arguments with a pre-defined predicate, but also provide a meaningful description.

Attention

Matchers receive their arguments as possibly non-const, which is due to workaround some restrictions on const qualified views. Either way, matchers should never modify any of their arguments.

Matching arguments

In general matchers can be applied via the expect::arg<n> factory, but they can also be directly used at the expect statement.

    using mimicpp::matches::_;
    namespace matches = mimicpp::matches;
    namespace expect = mimicpp::expect;
 
    mimicpp::Mock<void(int)> mock{};
 
    SCOPED_EXP mock.expect_call(_)
        and expect::arg<0>(matches::gt(42))
        and expect::arg<0>(matches::lt(1338));
    mock(1337);

    namespace matches = mimicpp::matches;
 
    mimicpp::Mock<void(int)> mock{};
 
    SCOPED_EXP mock.expect_call(matches::eq(42));
    mock(42);

For equality testing, there exists an even shorter syntax.

    mimicpp::Mock<void(int)> mock{};
 
    SCOPED_EXP mock.expect_call(42);
    mock(42);

Most of the built-in matchers support the inversion operator (operator !), which then tests for the opposite condition.

    using mimicpp::matches::_;
    namespace matches = mimicpp::matches;
    namespace expect = mimicpp::expect;
 
    mimicpp::Mock<void(int)> mock{};
 
    SCOPED_EXP mock.expect_call(_)            // in fact, the _ is the only built-in matcher, which isn't invertible
        and expect::arg<0>(!matches::le(42)); // note the !, as this makes it an actual > test
    mock(1337);

Custom Matcher

Matchers are highly customizable. In fact, any type which satisfies matcher_for concept can be used. There exists no base or interface type, but the PredicateMatcher servers as a convenient generic type, which simply contains a predicate, a format string and optional additional arguments. But, this is just one option. If you have some very specific needs, go and create your matcher from scratch.

    using mimicpp::matches::_;
    namespace matches = mimicpp::matches;
    namespace expect = mimicpp::expect;
 
    mimicpp::PredicateMatcher containsMatcher{
        // provide a test predicate
        [](const auto& target, const auto& element) // the left most param is the argument to be checked
        {
            return std::ranges::find(target, element) != std::ranges::end(target);
        },
        // specify a descriptive format message, which will be applied to std::format.
        "contains element {}",
        // specify the inverted message, which will also be applied to std::format, when inversion is used
        "contains not element {}",
        // capture additional data, which will be forwarded to both, the predicate and the description
        std::tuple{42}};
 
    mimicpp::Mock<void(std::span<int>)> mock{};
 
    SCOPED_EXP mock.expect_call(_)
        and expect::arg<0>(containsMatcher);
 
    std::vector collection{42, 1337};
    mock(collection);

Function Documentation

approx_abs()

auto mimicpp::matches::approx_abs ( const std::floating_point auto value, const std::floating_point auto epsilon )

nodiscardconstexpr

Tests, whether the floating-point target is approximately equal to value.

Parameters

value	The value to compare to.
epsilon	The maximum absolute difference.

Exceptions

std::runtime_error	When value is NaN or infinity.
std::runtime_error	When epsilon is NaN, infinity or non-positive.

Returns

The newly created matcher.

approx_rel() [1/2]

template<std::floating_point Float>

auto mimicpp::matches::approx_rel ( const Float value )

nodiscardconstexpr

Tests, whether the floating-point target is approximately equal to value.

Parameters

value

The value to compare against.

Returns

The newly created matcher.

Exceptions

std::runtime_error

When value is NaN or infinity.

This overload sets 100 * std::numeric_limits<Float>::epsilon() as the relative epsilon value. This seems like a reasonable choice, which is also used by the catch2's WithinRel matcher.

See also

https://github.com/catchorg/Catch2/blob/devel/docs/comparing-floating-point-numbers.md#withinrel

For detailed information about the underlying algorithm, have a look at the primary overload.

See also

approx_rel(std::floating_point auto, std::floating_point auto)

Here is the call graph for this function:

approx_rel() [2/2]

auto mimicpp::matches::approx_rel ( const std::floating_point auto value, const std::floating_point auto relEpsilon )

nodiscardconstexpr

Tests, whether the floating-point target is approximately equal to value.

Parameters

value	The value to compare against.
relEpsilon	The maximum relative difference.

Returns

The newly created matcher.

Exceptions

std::runtime_error	When value is NaN or infinity.
std::runtime_error	When relEpsilon is NaN, infinity or non-positive.

This functions compares both floating-point values with a scaled epsilon. In fact:

|a-b| <= eps * max(|a|, |b|),

where a and b are the operands and eps denotes the factor of the maximum input by which a and b may differ.

Note

This algorithm was published by Donald Knuth in his book “The Art of Computer Programming, Volume II: Seminumerical Algorithms (Addison-Wesley, 1969)”.

Here is the caller graph for this function:

eq()

template<typename T>

auto mimicpp::matches::eq ( T && value )

nodiscardconstexpr

Tests, whether the target compares equal to the expected value.

Template Parameters

T	Expected type.

Parameters

value

Expected value.

ge()

template<typename T>

auto mimicpp::matches::ge ( T && value )

nodiscardconstexpr

Tests, whether the target is greater than or equal to the expected value.

Template Parameters

T	Expected type.

Parameters

value

Expected value.

gt()

template<typename T>

auto mimicpp::matches::gt ( T && value )

nodiscardconstexpr

Tests, whether the target is greater than the expected value.

Template Parameters

T	Expected type.

Parameters

value

Expected value.

instance()

template<satisfies< std::is_lvalue_reference > T>

auto mimicpp::matches::instance ( T && instance )

nodiscardconstexpr

Tests, whether the target is the expected instance.

Template Parameters

T	Instance type.

Parameters

instance

The instance to be compared to. namespace matches = mimicpp::matches; mimicpp::Mock<void(const int&)> mock{}; int myInt{}; SCOPED_EXP mock.expect_call(matches::instance(myInt)); mock(myInt);

Here is the call graph for this function:

Here is the caller graph for this function:

le()

template<typename T>

auto mimicpp::matches::le ( T && value )

nodiscardconstexpr

Tests, whether the target is less than or equal to the expected value.

Template Parameters

T	Expected type.

Parameters

value

Expected value.

lt()

template<typename T>

auto mimicpp::matches::lt ( T && value )

nodiscardconstexpr

Tests, whether the target is less than the expected value.

Template Parameters

T	Expected type.

Parameters

value

Expected value.

NaN()

auto mimicpp::matches::NaN ( )

nodiscardconstevalnoexcept

Tests, whether the floating-point target is NaN.

ne()

template<typename T>

auto mimicpp::matches::ne ( T && value )

nodiscardconstexpr

Tests, whether the target compares not equal to the expected value.

Template Parameters

T	Expected type.

Parameters

value

Expected value.

predicate()

template<typename UnaryPredicate>

auto mimicpp::matches::predicate ( UnaryPredicate && predicate, StringViewT description = "passes predicate", StringViewT invertedDescription = "fails predicate" )

nodiscardconstexpr

Tests, whether the target fulfills the given predicate.

Template Parameters

UnaryPredicate

Predicate type.

Parameters

predicate	The predicate to test.
description	The formatting string.
invertedDescription	The formatting string for the inversion. using mimicpp::matches::_; namespace matches = mimicpp::matches; namespace expect = mimicpp::expect; mimicpp::Mock<void(int)> mock{}; constexpr auto isOdd = [](int val) { return 0 != val % 2; }; SCOPED_EXP mock.expect_call(_) and expect::arg<0>(matches::predicate(isOdd)); mock(1337);

Here is the call graph for this function:

Here is the caller graph for this function:

Variable Documentation

_

WildcardMatcher mimicpp::matches::_ {}

inlineconstexpr

The wildcard matcher, always matching.

    using mimicpp::matches::_;
 
    mimicpp::Mock<void(int)> mock{};
 
    SCOPED_EXP mock.expect_call(_);
    mock(1337);