readme and example

Author: me

README.md

@@ -3,7 +3,7 @@
 ![Windows](https://github.com/pfeatherstone/msgpack_cpp/actions/workflows/windows.yml/badge.svg)
 
 # msgpack_cpp
-C++ header-only msgpack library
+C++ header-only msgpack library that supports (de)serializing types directly, including custom types, as well as a dicitionary type `msgpackcpp::value` a la `nlohmann::json` or `boost::json::value`. 
 
 ## Examples
 
@@ -143,6 +143,61 @@ int main()
 }
 ```
 
+### Dictionary value
+
+```cpp
+#include "msgpack.h"
+#include "msgpack_sinks.h"
+
+const auto REQUIRE = [](auto res) {if (!res)throw std::runtime_error("bad");};
+
+int main()
+{
+    using msgpackcpp::serialize;
+    using msgpackcpp::deserialize;
+    using msgpackcpp::sink;
+    using msgpackcpp::source;
+
+    // Data
+    msgpackcpp::value jv0 = {
+        {"pi", 3.141},
+        {"happy", true},
+        {"name", "Niels"},
+        {"nothing", nullptr},
+        {"answer", {
+            {"everything", -42}
+        }},
+        {"list", {1, 0, 2}},
+        {"object", {
+            {"currency", "USD"},
+            {"value", 42.99}
+        }}
+    };
+
+    // Serialize (pack)
+    std::vector<char> buf;
+    auto out = sink(buf);
+    jv0.pack(out);
+
+    // Deserialize (unpack)
+    msgpackcpp::value jv1;
+    auto in = source(buf);
+    jv1.unpack(in);
+
+    // Check
+    REQUIRE(jv1.is_object());
+    REQUIRE(jv1.size() == 7);
+    REQUIRE(jv1.at("pi").as_real() == 3.141);
+    REQUIRE(jv1.at("happy").as_bool() == true);
+    REQUIRE(jv1.at("name").as_str() == "Niels");
+    REQUIRE(jv1.at("nothing").is_null());
+    REQUIRE(jv1.at("answer").at("everything").as_int64() == -42);
+    REQUIRE(jv1.at("list").as_array().size() == 3);
+    REQUIRE(jv1.at("object").at("currency").as_str() == "USD");
+    REQUIRE(jv1.at("object").at("value").as_real() == 42.99);
+}
+```
+
 ## Installation
 
 Just copy the contents of the include folder in your project with `msgpack_describe.h` as an optional header.

examples/CMakeLists.txt

@@ -28,4 +28,5 @@ endfunction()
 
 add_example(example1 example1.cpp)
 add_example(example2 example2.cpp)
-add_example(example3 example3.cpp)
+add_example(example3 example3.cpp)
+add_example(example4 example4.cpp)

examples/example4.cpp

@@ -0,0 +1,50 @@
+#include "msgpack.h"
+#include "msgpack_sinks.h"
+
+const auto REQUIRE = [](auto res) {if (!res)throw std::runtime_error("bad");};
+
+int main()
+{
+    using msgpackcpp::serialize;
+    using msgpackcpp::deserialize;
+    using msgpackcpp::sink;
+    using msgpackcpp::source;
+
+    // Data
+    msgpackcpp::value jv0 = {
+        {"pi", 3.141},
+        {"happy", true},
+        {"name", "Niels"},
+        {"nothing", nullptr},
+        {"answer", {
+            {"everything", -42}
+        }},
+        {"list", {1, 0, 2}},
+        {"object", {
+            {"currency", "USD"},
+            {"value", 42.99}
+        }}
+    };
+
+    // Serialize (pack)
+    std::vector<char> buf;
+    auto out = sink(buf);
+    jv0.pack(out);
+
+    // Deserialize (unpack)
+    msgpackcpp::value jv1;
+    auto in = source(buf);
+    jv1.unpack(in);
+
+    // Check
+    REQUIRE(jv1.is_object());
+    REQUIRE(jv1.size() == 7);
+    REQUIRE(jv1.at("pi").as_real() == 3.141);
+    REQUIRE(jv1.at("happy").as_bool() == true);
+    REQUIRE(jv1.at("name").as_str() == "Niels");
+    REQUIRE(jv1.at("nothing").is_null());
+    REQUIRE(jv1.at("answer").at("everything").as_int64() == -42);
+    REQUIRE(jv1.at("list").as_array().size() == 3);
+    REQUIRE(jv1.at("object").at("currency").as_str() == "USD");
+    REQUIRE(jv1.at("object").at("value").as_real() == 42.99);
+}