Document glz::convert_struct (#1491)

* Adding documentation for glz::convert_struct

* Adding comments for convert_struct

* Fix integer parsing test from float

Author: stephenberry

docs/reflection.md

@@ -14,3 +14,65 @@ static_assert(glz::refl<T>::size == 3);
 static_assert(glz::refl<T>::keys[0] == "a");
 ```
 
+## glz::convert_struct
+
+The `glz::convert_struct` function show a simple application of Glaze reflection at work. It allows two different structs with the same member names to convert from one to the other. If any of the fields don't have matching names, a compile time error will be generated.
+
+```c++
+struct a_type
+{
+   float fluff = 1.1f;
+   int goo = 1;
+   std::string stub = "a";
+};
+
+struct b_type
+{
+   float fluff = 2.2f;
+   int goo = 2;
+   std::string stub = "b";
+};
+
+struct c_type
+{
+   std::optional<float> fluff = 3.3f;
+   std::optional<int> goo = 3;
+   std::optional<std::string> stub = "c";
+};
+
+suite convert_tests = [] {
+   "convert a to b"_test = [] {
+      a_type in{};
+      b_type out{};
+
+      glz::convert_struct(in, out);
+
+      expect(out.fluff == 1.1f);
+      expect(out.goo == 1);
+      expect(out.stub == "a");
+   };
+
+   "convert a to c"_test = [] {
+      a_type in{};
+      c_type out{};
+
+      glz::convert_struct(in, out);
+
+      expect(out.fluff.value() == 1.1f);
+      expect(out.goo.value() == 1);
+      expect(out.stub.value() == "a");
+   };
+
+   "convert c to a"_test = [] {
+      c_type in{};
+      a_type out{};
+
+      glz::convert_struct(in, out);
+
+      expect(out.fluff == 3.3f);
+      expect(out.goo == 3);
+      expect(out.stub == "c");
+   };
+};
+```
+

include/glaze/core/convert_struct.hpp

@@ -6,12 +6,19 @@
 #include "glaze/core/common.hpp"
 #include "glaze/core/reflect.hpp"
 
-// For generic struct to struct conversion based on reflected fields
-// This will convert a struct with optionals to non-optionals
-// More conversion can be added in the future
-
 namespace glz
 {
+   /**
+    * @brief Provides generic struct to struct conversion based on reflected fields.
+    *
+    * Uses reflected fields to perform a generic conversion from `In` to `Out`.
+    * Additional conversion rules can be added in the future, but optional like types are supported.
+    *
+    * @tparam In  Type of the input struct with optional fields.
+    * @tparam Out Type of the output struct with non-optional fields.
+    * @param[in] in   The input struct instance.
+    * @param[out] out The output struct instance to be populated.
+    */
    template <class In, class Out>
    void convert_struct(In&& in, Out&& out)
    {

tests/json_test/json_test.cpp

@@ -2265,9 +2265,19 @@ suite read_tests = [] {
          for (size_t i = 0; i < 1000; ++i) {
             const auto f = dist(gen);
             expect(not glz::write_json(f, buffer));
+            
+            // Check if 'f' is exactly an integer
+            const bool is_integer = (std::floor(f) == f);
+
             int64_t integer{};
-            auto ec = glz::read_json(integer, buffer);
-            expect(ec);
+            if (is_integer) {
+              auto ec = glz::read_json(integer, buffer);
+              expect(!ec); // Expect no error when reading as integer
+              expect(integer == int64_t(f));
+            } else {
+              auto ec = glz::read_json(integer, buffer);
+              expect(ec); // Expect an error when reading a non-integer as integer
+            }
          }
       }
    };