Support for constexpr matchers in C++20 (P0784)

To make this all work, I had to remove the stringification cache
from matchers. In theory, this can cause performance penalty in
cases where single matcher instance is stringified multiple times,
but in practice this does not happen much, and the difference is
surprisingly small anyway, because the performance of stringification
is already horrible and full of allocating strings just to throw
them away.

The matcher combinators need P2738 from C++26 to be `constexpr`.

Closes #3091

2 files changed, 45 insertions, 0 deletions

diff --git a/docs/matchers.md b/docs/matchers.md
index 4b9445ae..a013245c 100644
--- a/docs/matchers.md
+++ b/docs/matchers.md
@@ -6,6 +6,7 @@
 [Built-in matchers](#built-in-matchers)<br>
 [Writing custom matchers (old style)](#writing-custom-matchers-old-style)<br>
 [Writing custom matchers (new style)](#writing-custom-matchers-new-style)<br>
+[Constexpr matchers](#constexpr-matchers)<br>
 
 Matchers, as popularized by the [Hamcrest](https://en.wikipedia.org/wiki/Hamcrest)
 framework are an alternative way to write assertions, useful for tests
@@ -471,6 +472,26 @@ and new style matchers arbitrarily.
 > `MatcherGenericBase` lives in `catch2/matchers/catch_matchers_templated.hpp`
 
 
+## Constexpr matchers
+
+> Support for constexpr matchers was introduced in Catch2 vX.Y.Z
+
+When compiled for C++20, the new-style matchers (can) support `constexpr`
+matching, albeit not `constexpr` stringification. The matcher combinators
+require C++26 (or at least P2738) to be `constexpr` compatible.
+
+This can be used together with the `STATIC_REQUIRE_THAT` macro to write
+matcher-based static assertions like this:
+
+```cpp
+TEST_CASE("Constexpr support for matchers", "[constexpr][matchers]") {
+    STATIC_REQUIRE_THAT( 1, MatchAll() );
+    STATIC_REQUIRE_THAT( 1, MatchAll() || MatchAll() );
+    STATIC_REQUIRE_THAT( 1, !!MatchAll() );
+}
+```
+
+
 ---
 
 [Home](Readme.md#top)
diff --git a/docs/other-macros.md b/docs/other-macros.md
index 79990a6a..de7e4bc6 100644
--- a/docs/other-macros.md
+++ b/docs/other-macros.md
@@ -91,6 +91,30 @@ TEST_CASE("STATIC_CHECK showcase", "[traits]") {
 }
 ```
 
+* `STATIC_REQUIRE_THAT` and `STATIC_CHECK_THAT`
+
+> `STATIC_REQUIRE_THAT` and `STATIC_CHECK_THAT` was introduced in Catch2 X.Y.Z
+
+`STATIC_{REQUIRE,CHECK}_THAT` are analogous to `STATIC_{REQUIRE,CHECK}`,
+but for matchers. They are always defined, even if the current compiler
+does not support `constexpr` matchers, but in that case the compilation
+will always fail.
+
+Just like `STATIC_{REQUIRE,CHECK}`, `STATIC_{REQUIRE,CHECK}_THAT` can be
+delayed into runtime through the `CATCH_CONFIG_RUNTIME_STATIC_REQUIRE`
+configuration option.
+
+Example:
+```cpp
+TEST_CASE("Constexpr support for matchers", "[constexpr][matchers]") {
+    STATIC_REQUIRE_THAT( 1, MatchAll() );
+    STATIC_REQUIRE_THAT( 1, MatchAll() && MatchAll() );
+    STATIC_REQUIRE_THAT( 1, MatchAll() || MatchAll() );
+    STATIC_REQUIRE_THAT( 1, !!MatchAll() );
+}
+```
+
+
 ## Test case related macros
 
 * `REGISTER_TEST_CASE`