From 6cb91ea946dd89c7ce0607e798d3b00616e4991b Mon Sep 17 00:00:00 2001
From: Richard Ash <richard.ash@eatechnology.com>
Date: Fri, 19 Jun 2020 15:32:08 +0100
Subject: [PATCH] Add an example of using GENERATE(table())

There are some examples on issue #850 of using this feature, but they
are not easily found from the documentation. Adding them here as an
example makes them more findable and ensures they keep working if the
API changes.
---
 docs/list-of-examples.md   |  1 +
 examples/302-Gen-Table.cpp | 51 ++++++++++++++++++++++++++++++++++++++
 examples/CMakeLists.txt    |  1 +
 3 files changed, 53 insertions(+)
 create mode 100644 examples/302-Gen-Table.cpp

diff --git a/docs/list-of-examples.md b/docs/list-of-examples.md
index 95e7bda0ce..c3514ed5b5 100644
--- a/docs/list-of-examples.md
+++ b/docs/list-of-examples.md
@@ -16,6 +16,7 @@
 - Configuration: [Provide your own output streams](../examples/231-Cfg-OutputStreams.cpp)
 - Generators: [Create your own generator](../examples/300-Gen-OwnGenerator.cpp)
 - Generators: [Use map to convert types in GENERATE expression](../examples/301-Gen-MapTypeConversion.cpp)
+- Generators: [Run test with a table of input values](../examples/302-Gen-Table.cpp)
 - Generators: [Use variables in generator expressions](../examples/310-Gen-VariablesInGenerators.cpp)
 - Generators: [Use custom variable capture in generator expressions](../examples/311-Gen-CustomCapture.cpp)
 
diff --git a/examples/302-Gen-Table.cpp b/examples/302-Gen-Table.cpp
new file mode 100644
index 0000000000..afbbf83b39
--- /dev/null
+++ b/examples/302-Gen-Table.cpp
@@ -0,0 +1,51 @@
+// 302-Gen-Table.cpp
+// Shows how to use table to run a test many times with different inputs. Lifted from examples on
+// issue #850.
+
+// TODO
+
+#include <catch2/catch.hpp>
+
+#include <string>
+
+class TestSubject
+{
+public:
+    // this is the method we are going to test. It returns the length of the input string.
+    size_t GetLength(const std::string & input)
+    {
+        return input.size();
+    }
+};
+
+
+TEST_CASE("Table allows pre-computed test inputs and outputs", "[example][generator]") {
+    // do setup here as normal
+    TestSubject subj;
+
+    SECTION("This section is run for each row in the table") {
+        // C++17 alternative for the first three lines of code below using structured bindings:
+        // auto [test_input, expected] = GENERATE( table<std::string, size_t>({
+        std::string test_input;
+        size_t expected_output;
+        std::tie(test_input, expected_output) = GENERATE( table<std::string, size_t>({
+        /* In this case one of the parameters to our test case is the expected output, but this is
+         * not required. There could be multiple expected values in the table, which can have any
+         * (fixed) number of columns.
+         */
+                     {"one", 3},
+                     {"two", 3},
+                   {"three", 5},
+                    {"four", 4}
+                   }));
+        
+        // run the test
+        auto result = subj.GetLength(test_input);
+        // capture the input data to go with the outputs.
+        CAPTURE(test_input);
+        // check it matches the pre-calculated data
+        REQUIRE(result == expected_output);
+    }   // end section
+}
+
+// Compiling and running this file will result in 4 successful assertions
diff --git a/examples/CMakeLists.txt b/examples/CMakeLists.txt
index 65dc5f54ac..22cc4e8b50 100644
--- a/examples/CMakeLists.txt
+++ b/examples/CMakeLists.txt
@@ -46,6 +46,7 @@ set( SOURCES_IDIOMATIC_TESTS
     210-Evt-EventListeners.cpp
     300-Gen-OwnGenerator.cpp
     301-Gen-MapTypeConversion.cpp
+	302-Gen-Table.cpp
     310-Gen-VariablesInGenerators.cpp
     311-Gen-CustomCapture.cpp
 )