docs: write std::chrono durations as unit/value objects; reword a title with escaped quotes (#5911)

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/examples/type_recipes_chrono.cpp

@@ -1,9 +1,38 @@
 #include <chrono>
 #include <iostream>
+#include <stdexcept>
+#include <string>
 #include <nlohmann/json.hpp>
 
 using json = nlohmann::json;
 
+// the name of a period; extend the list for the periods you use
+template <typename Period> const char* unit_name();
+template <> const char* unit_name<std::nano>()
+{
+    return "ns";
+}
+template <> const char* unit_name<std::micro>()
+{
+    return "us";
+}
+template <> const char* unit_name<std::milli>()
+{
+    return "ms";
+}
+template <> const char* unit_name<std::ratio<1>>()
+{
+    return "s";
+}
+template <> const char* unit_name<std::ratio<60>>()
+{
+    return "min";
+}
+template <> const char* unit_name<std::ratio<3600>>()
+{
+    return "h";
+}
+
 namespace nlohmann
 {
 template <typename Rep, typename Period>
@@ -11,12 +40,16 @@ struct adl_serializer<std::chrono::duration<Rep, Period>>
 {
     static void to_json(json& j, const std::chrono::duration<Rep, Period>& d)
     {
-        j = d.count();
+        j = {{"unit", unit_name<Period>()}, {"value", d.count()}};
     }
 
     static void from_json(const json& j, std::chrono::duration<Rep, Period>& d)
     {
-        d = std::chrono::duration<Rep, Period>(j.get<Rep>());
+        if (j.at("unit").get<std::string>() != unit_name<Period>())
+        {
+            throw std::invalid_argument("unexpected unit " + j.at("unit").dump());
+        }
+        d = std::chrono::duration<Rep, Period>(j.at("value").get<Rep>());
     }
 };
 
@@ -41,11 +74,21 @@ int main()
 
     std::cout << std::boolalpha;
 
-    // the unit is not part of the JSON value
+    // the unit is part of the JSON value
     const json timeout = milliseconds(1500);
     std::cout << "duration: " << timeout << '\n';
     std::cout << "as milliseconds: " << timeout.get<milliseconds>().count() << '\n';
 
+    // reading with a different unit is rejected
+    try
+    {
+        timeout.get<seconds>();
+    }
+    catch (const std::invalid_argument& e)
+    {
+        std::cout << "error: " << e.what() << '\n';
+    }
+
     // a system_clock time point is the time since the Unix epoch
     const time_point<system_clock, milliseconds> t(milliseconds(1700000000123));
     const json stamp = t;

docs/mkdocs/docs/examples/type_recipes_chrono.output

@@ -1,4 +1,5 @@
-duration: 1500
+duration: {"unit":"ms","value":1500}
 as milliseconds: 1500
-time point: 1700000000123
+error: unexpected unit "ms"
+time point: {"unit":"ms","value":1700000000123}
 round trip: true