Add Concat generator for combining multiple generators

21 files changed, 1020 insertions, 20 deletions

diff --git a/docs/generators.md b/docs/generators.md
index 27bedacc..b01ec906 100644
--- a/docs/generators.md
+++ b/docs/generators.md
@@ -1,6 +1,12 @@
 <a id="top"></a>
 # Data Generators
 
+**Contents**<br>
+[Combining `GENERATE` and `SECTION`.](#combining-generate-and-section)<br>
+[Provided generators](#provided-generators)<br>
+[Generator interface](#generator-interface)<br>
+[Other usage examples](#other-usage-examples)<br>
+
 > Introduced in Catch2 2.6.0.
 
 Data generators (also known as _data driven/parametrized test cases_)
@@ -106,7 +112,7 @@ a test case,
 * 2 fundamental generators
   * `SingleValueGenerator<T>` -- contains only single element
   * `FixedValuesGenerator<T>` -- contains multiple elements
-* 5 generic generators that modify other generators (defined in `catch2/generators/catch_generators_adapters.hpp`)
+* 6 generic generators that modify other generators (defined in `catch2/generators/catch_generators_adapters.hpp`)
   * `FilterGenerator<T, Predicate>` -- filters out elements from a generator
   for which the predicate returns "false"
   * `TakeGenerator<T>` -- takes first `n` elements from a generator
@@ -114,6 +120,7 @@ a test case,
   * `MapGenerator<T, U, Func>` -- returns the result of applying `Func`
   on elements from a different generator
   * `ChunkGenerator<T>` -- returns chunks (inside `std::vector`) of n elements from a generator
+  * `ConcatGenerator<T>` -- returns elements from multiple generators as if they were one
 * 2 random generators (defined in `catch2/generators/catch_generators_random.hpp`)
   * `RandomIntegerGenerator<Integral>` -- generates random Integrals from range
   * `RandomFloatGenerator<Float>` -- generates random Floats from range
@@ -125,6 +132,8 @@ a test case,
 
 > `IteratorGenerator<T>` was introduced in Catch2 2.10.0.
 
+> `ConcatGenerator<T>` was introduced in Catch2 X.Y.Z
+
 The generators also have associated helper functions that infer their
 type, making their usage much nicer. These are
 
@@ -142,6 +151,7 @@ type, making their usage much nicer. These are
 * `range(Arithmetic start, Arithmetic end, Arithmetic step)` for `RangeGenerator<Arithmetic>` with a custom step size
 * `from_range(InputIterator from, InputIterator to)` for `IteratorGenerator<T>`
 * `from_range(Container const&)` for `IteratorGenerator<T>`
+* `cat(GeneratorWrapper<T>&&...)` for `ConcatGenerator<T>`
 
 > `chunk()`, `random()` and both `range()` functions were introduced in Catch2 2.7.0.
 
@@ -149,6 +159,8 @@ type, making their usage much nicer. These are
 
 > `range()` for floating point numbers has been introduced in Catch2 2.11.0
 
+> `cat` has been introduced in Catch2 X.Y.Z
+
 And can be used as shown in the example below to create a generator
 that returns 100 odd random number:
 
@@ -278,6 +290,32 @@ to be an error or not.
  * If empty generator **is not** an error, use the [`SKIP` macro](skipping-passing-failing.md#skipping-test-cases-at-runtime) in constructor.
 
 
+## Other usage examples
+
+### Adding a reproducer to random tests
+
+If you use generators to generate random inputs for testing, you might
+want to combine them with specific inputs, e.g. reproducers for previously
+found issues.
+
+Because `GENERATE` accepts multiple values/generators, the basic case is simple:
+```cpp
+const int input = GENERATE(1, 2, take(10, random(10, 10'000'000)));
+```
+This will set `input` first to "1", then to "2", and then to 10 random
+integers.
+
+But if you process the random inputs further (e.g. via `map`), you can't
+rely on `GENERATE`'s support for multiple generators. In that case, you
+have to use the `cat` generator combinator.
+```cpp
+const auto input = GENERATE(
+    map( foo,
+         cat( value( 4 ), take( 10, random( 10, 10'000'000 ) ) ) ) );
+```
+This will set `input` first to `foo(4)`, before transforming the 10 random
+integers through `foo`.
+
 
 ---
 
diff --git a/src/catch2/generators/catch_generators_adapters.hpp b/src/catch2/generators/catch_generators_adapters.hpp
index e5ddc25e..01f7c622 100644
--- a/src/catch2/generators/catch_generators_adapters.hpp
+++ b/src/catch2/generators/catch_generators_adapters.hpp
@@ -234,6 +234,49 @@ namespace Generators {
         );
     }
 
+    template <typename T>
+    class ConcatGenerator final : public IGenerator<T> {
+        std::vector<GeneratorWrapper<T>> m_generators;
+        size_t m_current_generator = 0;
+
+        void InsertGenerators( GeneratorWrapper<T>&& gen ) {
+            m_generators.push_back( CATCH_MOVE( gen ) );
+        }
+
+        template <typename... Generators>
+        void InsertGenerators( GeneratorWrapper<T>&& gen, Generators&&... gens ) {
+            m_generators.push_back( CATCH_MOVE( gen ) );
+            InsertGenerators( CATCH_MOVE( gens )... );
+        }
+
+    public:
+        template <typename... Generators>
+        ConcatGenerator( Generators&&... generators ) {
+            InsertGenerators( CATCH_MOVE( generators )... );
+        }
+
+        T const& get() const override {
+            return m_generators[m_current_generator].get();
+        }
+        bool next() override {
+            const bool success = m_generators[m_current_generator].next();
+            if ( success ) { return true; }
+
+            // If current generator is used up, we have to move to the next one
+            ++m_current_generator;
+            return m_current_generator < m_generators.size();
+        }
+    };
+
+    template <typename T, typename... Generators>
+    GeneratorWrapper<T> cat( GeneratorWrapper<T>&& generator,
+                             Generators&&... generators ) {
+        return GeneratorWrapper<T>(
+            Catch::Detail::make_unique<ConcatGenerator<T>>(
+            CATCH_MOVE( generator ), CATCH_MOVE( generators )... ) );
+    }
+
+
 } // namespace Generators
 } // namespace Catch
 
diff --git a/tests/SelfTest/Baselines/automake.sw.approved.txt b/tests/SelfTest/Baselines/automake.sw.approved.txt
index 05c6384b..606d7ac3 100644
--- a/tests/SelfTest/Baselines/automake.sw.approved.txt
+++ b/tests/SelfTest/Baselines/automake.sw.approved.txt
@@ -131,6 +131,7 @@ Nor would this
 :test-result: PASS Comparisons with int literals don't warn when mixing signed/ unsigned
 :test-result: PASS Composed generic matchers shortcircuit
 :test-result: PASS Composed matchers shortcircuit
+:test-result: PASS ConcatGenerator
 :test-result: FAIL Contains string matcher
 :test-result: PASS Copy and then generate a range
 :test-result: PASS Cout stream properly declares it writes to stdout
@@ -334,6 +335,7 @@ Message from section two
 :test-result: PASS array<int, N> -> toString
 :test-result: PASS benchmark function call
 :test-result: PASS boolean member
+:test-result: PASS cat generator
 :test-result: PASS checkedElse
 :test-result: FAIL checkedElse, failing
 :test-result: PASS checkedIf
diff --git a/tests/SelfTest/Baselines/automake.sw.multi.approved.txt b/tests/SelfTest/Baselines/automake.sw.multi.approved.txt
index 75c116d5..fd146fe7 100644
--- a/tests/SelfTest/Baselines/automake.sw.multi.approved.txt
+++ b/tests/SelfTest/Baselines/automake.sw.multi.approved.txt
@@ -129,6 +129,7 @@
 :test-result: PASS Comparisons with int literals don't warn when mixing signed/ unsigned
 :test-result: PASS Composed generic matchers shortcircuit
 :test-result: PASS Composed matchers shortcircuit
+:test-result: PASS ConcatGenerator
 :test-result: FAIL Contains string matcher
 :test-result: PASS Copy and then generate a range
 :test-result: PASS Cout stream properly declares it writes to stdout
@@ -327,6 +328,7 @@
 :test-result: PASS array<int, N> -> toString
 :test-result: PASS benchmark function call
 :test-result: PASS boolean member
+:test-result: PASS cat generator
 :test-result: PASS checkedElse
 :test-result: FAIL checkedElse, failing
 :test-result: PASS checkedIf
diff --git a/tests/SelfTest/Baselines/compact.sw.approved.txt b/tests/SelfTest/Baselines/compact.sw.approved.txt
index ea8d519a..a366d006 100644
--- a/tests/SelfTest/Baselines/compact.sw.approved.txt
+++ b/tests/SelfTest/Baselines/compact.sw.approved.txt
@@ -540,6 +540,18 @@ Matchers.tests.cpp:<line number>: passed: !second.matchCalled for: true
 Matchers.tests.cpp:<line number>: passed: matcher.match( 1 ) for: true
 Matchers.tests.cpp:<line number>: passed: first.matchCalled for: true
 Matchers.tests.cpp:<line number>: passed: !second.matchCalled for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == 1 for: 1 == 1
+GeneratorsImpl.tests.cpp:<line number>: passed: !(c.next()) for: !false
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == i + 1 for: 1 == 1
+GeneratorsImpl.tests.cpp:<line number>: passed: c.next() for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == i + 1 for: 2 == 2
+GeneratorsImpl.tests.cpp:<line number>: passed: c.next() for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == i + 1 for: 3 == 3
+GeneratorsImpl.tests.cpp:<line number>: passed: c.next() for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == i + 1 for: 4 == 4
+GeneratorsImpl.tests.cpp:<line number>: passed: c.next() for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == 5 for: 5 == 5
+GeneratorsImpl.tests.cpp:<line number>: passed: !(c.next()) for: !false
 Matchers.tests.cpp:<line number>: failed: testStringForMatching(), ContainsSubstring( "not there", Catch::CaseSensitive::No ) for: "this string contains 'abc' as a substring" contains: "not there" (case insensitive)
 Matchers.tests.cpp:<line number>: failed: testStringForMatching(), ContainsSubstring( "STRING" ) for: "this string contains 'abc' as a substring" contains: "STRING"
 Generators.tests.cpp:<line number>: passed: elem % 2 == 1 for: 1 == 1
@@ -2483,6 +2495,14 @@ InternalBenchmark.tests.cpp:<line number>: passed: model.started == 0 for: 0 ==
 InternalBenchmark.tests.cpp:<line number>: passed: model.finished == 0 for: 0 == 0
 InternalBenchmark.tests.cpp:<line number>: passed: called == 1 for: 1 == 1
 Tricky.tests.cpp:<line number>: passed: obj.prop != 0 for: 0x<hex digits> != 0
+Generators.tests.cpp:<line number>: passed: input < 3 for: 0 < 3
+Generators.tests.cpp:<line number>: passed: input < 3 for: 1 < 3
+Generators.tests.cpp:<line number>: passed: input < 3 for: 2 < 3
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
 Misc.tests.cpp:<line number>: passed: flag for: true
 Misc.tests.cpp:<line number>: passed: testCheckedElse( true ) for: true
 Misc.tests.cpp:<line number>: failed - but was ok: flag for: false
@@ -2895,7 +2915,7 @@ InternalBenchmark.tests.cpp:<line number>: passed: med == 18. for: 18.0 == 18.0
 InternalBenchmark.tests.cpp:<line number>: passed: q3 == 23. for: 23.0 == 23.0
 Misc.tests.cpp:<line number>: passed:
 Misc.tests.cpp:<line number>: passed:
-test cases:  437 |  317 passed |  96 failed | 6 skipped | 18 failed as expected
-assertions: 2311 | 2110 passed | 158 failed | 43 failed as expected
+test cases:  439 |  319 passed |  96 failed | 6 skipped | 18 failed as expected
+assertions: 2331 | 2130 passed | 158 failed | 43 failed as expected
 
 
diff --git a/tests/SelfTest/Baselines/compact.sw.multi.approved.txt b/tests/SelfTest/Baselines/compact.sw.multi.approved.txt
index dbfab609..dab12a55 100644
--- a/tests/SelfTest/Baselines/compact.sw.multi.approved.txt
+++ b/tests/SelfTest/Baselines/compact.sw.multi.approved.txt
@@ -538,6 +538,18 @@ Matchers.tests.cpp:<line number>: passed: !second.matchCalled for: true
 Matchers.tests.cpp:<line number>: passed: matcher.match( 1 ) for: true
 Matchers.tests.cpp:<line number>: passed: first.matchCalled for: true
 Matchers.tests.cpp:<line number>: passed: !second.matchCalled for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == 1 for: 1 == 1
+GeneratorsImpl.tests.cpp:<line number>: passed: !(c.next()) for: !false
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == i + 1 for: 1 == 1
+GeneratorsImpl.tests.cpp:<line number>: passed: c.next() for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == i + 1 for: 2 == 2
+GeneratorsImpl.tests.cpp:<line number>: passed: c.next() for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == i + 1 for: 3 == 3
+GeneratorsImpl.tests.cpp:<line number>: passed: c.next() for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == i + 1 for: 4 == 4
+GeneratorsImpl.tests.cpp:<line number>: passed: c.next() for: true
+GeneratorsImpl.tests.cpp:<line number>: passed: c.get() == 5 for: 5 == 5
+GeneratorsImpl.tests.cpp:<line number>: passed: !(c.next()) for: !false
 Matchers.tests.cpp:<line number>: failed: testStringForMatching(), ContainsSubstring( "not there", Catch::CaseSensitive::No ) for: "this string contains 'abc' as a substring" contains: "not there" (case insensitive)
 Matchers.tests.cpp:<line number>: failed: testStringForMatching(), ContainsSubstring( "STRING" ) for: "this string contains 'abc' as a substring" contains: "STRING"
 Generators.tests.cpp:<line number>: passed: elem % 2 == 1 for: 1 == 1
@@ -2476,6 +2488,14 @@ InternalBenchmark.tests.cpp:<line number>: passed: model.started == 0 for: 0 ==
 InternalBenchmark.tests.cpp:<line number>: passed: model.finished == 0 for: 0 == 0
 InternalBenchmark.tests.cpp:<line number>: passed: called == 1 for: 1 == 1
 Tricky.tests.cpp:<line number>: passed: obj.prop != 0 for: 0x<hex digits> != 0
+Generators.tests.cpp:<line number>: passed: input < 3 for: 0 < 3
+Generators.tests.cpp:<line number>: passed: input < 3 for: 1 < 3
+Generators.tests.cpp:<line number>: passed: input < 3 for: 2 < 3
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
+Generators.tests.cpp:<line number>: passed: input % 2 == 0 for: 0 == 0
 Misc.tests.cpp:<line number>: passed: flag for: true
 Misc.tests.cpp:<line number>: passed: testCheckedElse( true ) for: true
 Misc.tests.cpp:<line number>: failed - but was ok: flag for: false
@@ -2884,7 +2904,7 @@ InternalBenchmark.tests.cpp:<line number>: passed: med == 18. for: 18.0 == 18.0
 InternalBenchmark.tests.cpp:<line number>: passed: q3 == 23. for: 23.0 == 23.0
 Misc.tests.cpp:<line number>: passed:
 Misc.tests.cpp:<line number>: passed:
-test cases:  437 |  317 passed |  96 failed | 6 skipped | 18 failed as expected
-assertions: 2311 | 2110 passed | 158 failed | 43 failed as expected
+test cases:  439 |  319 passed |  96 failed | 6 skipped | 18 failed as expected
+assertions: 2331 | 2130 passed | 158 failed | 43 failed as expected
 
 
diff --git a/tests/SelfTest/Baselines/console.std.approved.txt b/tests/SelfTest/Baselines/console.std.approved.txt
index 7de7b1f9..48bcec18 100644
--- a/tests/SelfTest/Baselines/console.std.approved.txt
+++ b/tests/SelfTest/Baselines/console.std.approved.txt
@@ -1743,6 +1743,6 @@ due to unexpected exception with message:
   Why would you throw a std::string?
 
 ===============================================================================
-test cases:  437 |  335 passed |  76 failed | 7 skipped | 19 failed as expected
-assertions: 2289 | 2110 passed | 136 failed | 43 failed as expected
+test cases:  439 |  337 passed |  76 failed | 7 skipped | 19 failed as expected
+assertions: 2309 | 2130 passed | 136 failed | 43 failed as expected
 
diff --git a/tests/SelfTest/Baselines/console.sw.approved.txt b/tests/SelfTest/Baselines/console.sw.approved.txt
index ab18d08c..eb9f7367 100644
--- a/tests/SelfTest/Baselines/console.sw.approved.txt
+++ b/tests/SelfTest/Baselines/console.sw.approved.txt
@@ -3912,6 +3912,80 @@ with expansion:
   true
 
 -------------------------------------------------------------------------------
+ConcatGenerator
+  Cat support single-generator construction
+-------------------------------------------------------------------------------
+GeneratorsImpl.tests.cpp:<line number>
+...............................................................................
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == 1 )
+with expansion:
+  1 == 1
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE_FALSE( c.next() )
+with expansion:
+  !false
+
+-------------------------------------------------------------------------------
+ConcatGenerator
+  Iterating over multiple generators
+-------------------------------------------------------------------------------
+GeneratorsImpl.tests.cpp:<line number>
+...............................................................................
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == i + 1 )
+with expansion:
+  1 == 1
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.next() )
+with expansion:
+  true
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == i + 1 )
+with expansion:
+  2 == 2
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.next() )
+with expansion:
+  true
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == i + 1 )
+with expansion:
+  3 == 3
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.next() )
+with expansion:
+  true
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == i + 1 )
+with expansion:
+  4 == 4
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.next() )
+with expansion:
+  true
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == 5 )
+with expansion:
+  5 == 5
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE_FALSE( c.next() )
+with expansion:
+  !false
+
+-------------------------------------------------------------------------------
 Contains string matcher
 -------------------------------------------------------------------------------
 Matchers.tests.cpp:<line number>
@@ -16441,6 +16515,102 @@ with expansion:
   0x<hex digits> != 0
 
 -------------------------------------------------------------------------------
+cat generator
+  Simple usage
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input < 3 )
+with expansion:
+  0 < 3
+
+-------------------------------------------------------------------------------
+cat generator
+  Simple usage
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input < 3 )
+with expansion:
+  1 < 3
+
+-------------------------------------------------------------------------------
+cat generator
+  Simple usage
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input < 3 )
+with expansion:
+  2 < 3
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
 checkedElse
 -------------------------------------------------------------------------------
 Misc.tests.cpp:<line number>
@@ -19372,6 +19542,6 @@ Misc.tests.cpp:<line number>
 Misc.tests.cpp:<line number>: PASSED:
 
 ===============================================================================
-test cases:  437 |  317 passed |  96 failed | 6 skipped | 18 failed as expected
-assertions: 2311 | 2110 passed | 158 failed | 43 failed as expected
+test cases:  439 |  319 passed |  96 failed | 6 skipped | 18 failed as expected
+assertions: 2331 | 2130 passed | 158 failed | 43 failed as expected
 
diff --git a/tests/SelfTest/Baselines/console.sw.multi.approved.txt b/tests/SelfTest/Baselines/console.sw.multi.approved.txt
index 05d6eb6c..4d0bd8f4 100644
--- a/tests/SelfTest/Baselines/console.sw.multi.approved.txt
+++ b/tests/SelfTest/Baselines/console.sw.multi.approved.txt
@@ -3910,6 +3910,80 @@ with expansion:
   true
 
 -------------------------------------------------------------------------------
+ConcatGenerator
+  Cat support single-generator construction
+-------------------------------------------------------------------------------
+GeneratorsImpl.tests.cpp:<line number>
+...............................................................................
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == 1 )
+with expansion:
+  1 == 1
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE_FALSE( c.next() )
+with expansion:
+  !false
+
+-------------------------------------------------------------------------------
+ConcatGenerator
+  Iterating over multiple generators
+-------------------------------------------------------------------------------
+GeneratorsImpl.tests.cpp:<line number>
+...............................................................................
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == i + 1 )
+with expansion:
+  1 == 1
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.next() )
+with expansion:
+  true
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == i + 1 )
+with expansion:
+  2 == 2
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.next() )
+with expansion:
+  true
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == i + 1 )
+with expansion:
+  3 == 3
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.next() )
+with expansion:
+  true
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == i + 1 )
+with expansion:
+  4 == 4
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.next() )
+with expansion:
+  true
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE( c.get() == 5 )
+with expansion:
+  5 == 5
+
+GeneratorsImpl.tests.cpp:<line number>: PASSED:
+  REQUIRE_FALSE( c.next() )
+with expansion:
+  !false
+
+-------------------------------------------------------------------------------
 Contains string matcher
 -------------------------------------------------------------------------------
 Matchers.tests.cpp:<line number>
@@ -16434,6 +16508,102 @@ with expansion:
   0x<hex digits> != 0
 
 -------------------------------------------------------------------------------
+cat generator
+  Simple usage
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input < 3 )
+with expansion:
+  0 < 3
+
+-------------------------------------------------------------------------------
+cat generator
+  Simple usage
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input < 3 )
+with expansion:
+  1 < 3
+
+-------------------------------------------------------------------------------
+cat generator
+  Simple usage
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input < 3 )
+with expansion:
+  2 < 3
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:
+  0 == 0
+
+-------------------------------------------------------------------------------
+cat generator
+  Used in map
+-------------------------------------------------------------------------------
+Generators.tests.cpp:<line number>
+...............................................................................
+
+Generators.tests.cpp:<line number>: PASSED:
+  REQUIRE( input % 2 == 0 )
+with expansion:<