Feature: Enhance custom string- and char-type support

.gitignore

@@ -1,4 +1,5 @@
 out
 .vs
+.idea
 *.user
 CMakeSettings.json

README.md

@@ -327,6 +327,12 @@ The expectation policy has full control, whether a match can be made or shall be
 (like returning a value or throwing an exception). They can implement arbitrary logic, so feel free to experiment. There is no base type requirement,
 they simply have to satisfy either the ``mimicpp::expectation_policy_for``, ``mimicpp::control_policy`` or ``mimicpp::finalize_policy_for``.
 
+### Bring your own string- and char-types
+
+If you are working with a huge framework, chances are good, that this framework utilizes a custom string- or even char-type (like ``QChar`` and ``QString`` from Qt).
+They may look different, but in fact they are just strings, so it would be nice to make them fully compatible with the existing string-matchers.
+``mimic++`` supports that, users just have to provide some trait-specializations. For more infos, have a loook into the string section of the doxygen documentation.
+
 ---
 
 ## Documentation

examples/CMakeLists.txt

@@ -8,6 +8,7 @@ find_package(Catch2 REQUIRED)
 add_executable(
 	mimicpp-examples
 	"CustomPrinter.cpp"
+	"CustomString.cpp"
 	"Finalizers.cpp"
 	"InterfaceMock.cpp"
 	"Mock.cpp"

examples/CustomString.cpp

@@ -0,0 +1,200 @@
+// //          Copyright Dominic (DNKpp) Koepke 2024 - 2024.
+// // Distributed under the Boost Software License, Version 1.0.
+// //    (See accompanying file LICENSE_1_0.txt or copy at
+// //          https://www.boost.org/LICENSE_1_0.txt)
+
+#include "mimic++/String.hpp"
+
+#include <catch2/catch_test_macros.hpp>
+
+#include "mimic++/Mock.hpp"
+
+namespace
+{
+	//! [MyString]
+	class MyString
+	{
+	public:
+		explicit MyString(std::string str) noexcept
+			: m_Inner{std::move(str)}
+		{
+		}
+
+		std::string_view view() const noexcept
+		{
+			return std::string_view{m_Inner};
+		}
+
+	private:
+		std::string m_Inner{};
+	};
+
+	//! [MyString]
+}
+
+//! [MyString trait]
+template <>
+struct mimicpp::string_traits<MyString>
+{
+	// must be the underlying char type
+	using char_t = char;
+
+	// must be a std::ranges::view like type and must be contiguous
+	using view_t = std::string_view;
+
+	// must construct a view object
+	[[nodiscard]]
+	static view_t view(const MyString& str) noexcept
+	{
+		return str.view();
+	}
+};
+
+//! [MyString trait]
+
+TEST_CASE(
+	"mimic++ supports custom strings.",
+	"[example][example::string]"
+)
+{
+	//! [MyString example]
+	STATIC_REQUIRE(mimicpp::string<MyString>);
+
+	namespace expect = mimicpp::expect;
+	namespace matches = mimicpp::matches;
+	using matches::_;
+
+	mimicpp::Mock<void(MyString)> mock{};
+	SCOPED_EXP mock.expect_call("Hello, World!");
+	SCOPED_EXP mock.expect_call(matches::str::starts_with("Hi", mimicpp::case_insensitive));
+
+	mock(MyString{"Hello, World!"});	// matches the first expectation
+	mock(MyString{"hI, mimic++"});	// matches the second expectation (case-insensitive).
+	//! [MyString example]
+}
+
+//! [custom_char]
+struct my_char
+{
+	char c{};
+
+	bool operator==(const my_char&) const = default;
+};
+
+//! [custom_char]
+
+//! [custom_string]
+class ComplexString
+{
+public:
+	explicit ComplexString(std::vector<my_char> str) noexcept
+		: m_Inner{std::move(str)}
+	{
+	}
+
+	[[nodiscard]]
+	auto begin() const noexcept
+	{
+		return m_Inner.cbegin();
+	}
+
+	[[nodiscard]]
+	auto end() const noexcept
+	{
+		return m_Inner.cend();
+	}
+
+private:
+	std::vector<my_char> m_Inner{};
+};
+
+//! [custom_string]
+
+//! [custom_char trait]
+template <>
+struct mimicpp::is_character<my_char>
+	: public std::true_type
+{
+};
+
+//! [custom_char trait]
+
+//! [custom_string traits]
+template <>
+struct mimicpp::string_traits<ComplexString>
+{
+	// must be the underlying char type
+	using char_t = my_char;
+
+	// must be a std::ranges::view like type and must be contiguous
+	using view_t = std::span<const char_t>;
+
+	// must construct a view object
+	[[nodiscard]]
+	static view_t view(const ComplexString& str) noexcept
+	{
+		return std::span{
+			str.begin(),
+			str.end()
+		};
+	}
+};
+
+//! [custom_string traits]
+
+TEST_CASE(
+	"mimic++ supports complex custom strings.",
+	"[example][example::string]"
+)
+{
+	//! [custom_string example]
+	STATIC_REQUIRE(mimicpp::string<ComplexString>);
+
+	mimicpp::Mock<void(ComplexString)> mock{};
+	ComplexString s{{{'A'}, {'B'}, {'C'}}};
+	SCOPED_EXP mock.expect_call(s);
+
+	mock(s);
+	//! [custom_string example]
+}
+
+//! [custom_char case-folding]
+template <>
+struct mimicpp::string_case_fold_converter<my_char>
+{
+	// the string_case_fold_converter must expect the string's view-type and should return
+	// a forward-range with the underlying char-type.
+	[[nodiscard]]
+	auto operator ()(string_view_t<ComplexString> view) const
+	{
+		return view
+				| std::views::transform(
+					[](const my_char c)
+					{
+						// see notes of https://en.cppreference.com/w/cpp/string/byte/toupper
+						return my_char{
+							static_cast<char>(
+								static_cast<unsigned char>(std::toupper(c.c)))
+						};
+					});
+	}
+};
+
+//! [custom_char case-folding]
+
+TEST_CASE(
+	"mimic++ supports case-folding for custom char-types.",
+	"[example][example::string]"
+)
+{
+	//! [custom_string case-insensitive example]
+	STATIC_REQUIRE(mimicpp::case_foldable_string<ComplexString>);
+
+	namespace matches = mimicpp::matches;
+
+	mimicpp::Mock<void(ComplexString)> mock{};
+	SCOPED_EXP mock.expect_call(matches::str::starts_with(ComplexString{{{'A'}, {'B'}, {'C'}}}, mimicpp::case_insensitive));
+
+	mock(ComplexString{{{'a'}, {'B'}, {'c'}}});
+	//! [custom_string case-insensitive example]
+}

include/mimic++/Fwd.hpp

@@ -9,6 +9,7 @@
 #pragma once
 
 #include <string>
+#include <string_view>
 
 namespace mimicpp::call
 {
@@ -144,6 +145,22 @@ namespace mimicpp
 	template <typename First, typename... Others>
 	inline constexpr bool is_overload_set_v = is_overload_set<First, Others...>::value;
 
+	/**
+	 * \brief Primary template, purposely undefined.
+	 * \ingroup TYPE_TRAITS_UINT_WITH_SIZE
+	 * \tparam byteCount The expected size.
+	 */
+	template <std::size_t byteCount>
+	struct uint_with_size;
+
+	/**
+	 * \brief Convenience constant, exposing the ``value`` member of the actual type-trait.
+	 * \ingroup TYPE_TRAITS_UINT_WITH_SIZE
+	 * \tparam byteCount The expected size.
+	 */
+	template <std::size_t byteCount>
+	using uint_with_size_t  = typename uint_with_size<byteCount>::type;
+
 	template <typename T>
 	struct is_character;
 
@@ -188,6 +205,7 @@ namespace mimicpp
 	using CharT = char;
 	using CharTraitsT = std::char_traits<CharT>;
 	using StringT = std::basic_string<CharT, CharTraitsT>;
+	using StringViewT = std::basic_string_view<CharT, CharTraitsT>;
 }
 
 namespace mimicpp::sequence

include/mimic++/Matcher.hpp

@@ -293,7 +293,7 @@ namespace mimicpp::matches
 	 * \brief The wildcard matcher, always matching.
 	 * \snippet Requirements.cpp matcher wildcard
 	 */
-	inline constexpr WildcardMatcher _{};
+	[[maybe_unused]] inline constexpr WildcardMatcher _{};
 
 	/**
 	 * \brief Tests, whether the target compares equal to the expected value.