Created Examples (markdown)

2024-11-24 06:29:03 +08:00 · 2018-06-19 23:09:08 +02:00 · 2018-06-19 23:09:08 +02:00 · 2bfcbda674
commit 2bfcbda674
parent 18eee36d58
1 changed files with 695 additions and 0 deletions
--- a/Examples.md
+++ b/Examples.md
@ -0,0 +1,695 @@
+Beside the examples below, you may want to check the [documentation](https://nlohmann.github.io/json/) where each function contains a separate code example (e.g., check out [`emplace()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a5338e282d1d02bed389d852dd670d98d.html#a5338e282d1d02bed389d852dd670d98d)). All [example files](https://github.com/nlohmann/json/tree/develop/doc/examples) can be compiled and executed on their own (e.g., file [emplace.cpp](https://github.com/nlohmann/json/blob/develop/doc/examples/emplace.cpp)).
+
+### JSON as first-class data type
+
+Here are some examples to give you an idea how to use the class.
+
+Assume you want to create the JSON object
+
+```json
+{
+  "pi": 3.141,
+  "happy": true,
+  "name": "Niels",
+  "nothing": null,
+  "answer": {
+    "everything": 42
+  },
+  "list": [1, 0, 2],
+  "object": {
+    "currency": "USD",
+    "value": 42.99
+  }
+}
+```
+
+With this library, you could write:
+
+```cpp
+// create an empty structure (null)
+json j;
+
+// add a number that is stored as double (note the implicit conversion of j to an object)
+j["pi"] = 3.141;
+
+// add a Boolean that is stored as bool
+j["happy"] = true;
+
+// add a string that is stored as std::string
+j["name"] = "Niels";
+
+// add another null object by passing nullptr
+j["nothing"] = nullptr;
+
+// add an object inside the object
+j["answer"]["everything"] = 42;
+
+// add an array that is stored as std::vector (using an initializer list)
+j["list"] = { 1, 0, 2 };
+
+// add another object (using an initializer list of pairs)
+j["object"] = { {"currency", "USD"}, {"value", 42.99} };
+
+// instead, you could also write (which looks very similar to the JSON above)
+json j2 = {
+  {"pi", 3.141},
+  {"happy", true},
+  {"name", "Niels"},
+  {"nothing", nullptr},
+  {"answer", {
+    {"everything", 42}
+  }},
+  {"list", {1, 0, 2}},
+  {"object", {
+    {"currency", "USD"},
+    {"value", 42.99}
+  }}
+};
+```
+
+Note that in all these cases, you never need to "tell" the compiler which JSON value type you want to use. If you want to be explicit or express some edge cases, the functions [`json::array`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_aa80485befaffcadaa39965494e0b4d2e.html#aa80485befaffcadaa39965494e0b4d2e) and [`json::object`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_aa13f7c0615867542ce80337cbcf13ada.html#aa13f7c0615867542ce80337cbcf13ada) will help:
+
+```cpp
+// a way to express the empty array []
+json empty_array_explicit = json::array();
+
+// ways to express the empty object {}
+json empty_object_implicit = json({});
+json empty_object_explicit = json::object();
+
+// a way to express an _array_ of key/value pairs [["currency", "USD"], ["value", 42.99]]
+json array_not_object = json::array({ {"currency", "USD"}, {"value", 42.99} });
+```
+
+
+### Serialization / Deserialization
+
+#### To/from strings
+
+You can create a JSON value (deserialization) by appending `_json` to a string literal:
+
+```cpp
+// create object from string literal
+json j = "{ \"happy\": true, \"pi\": 3.141 }"_json;
+
+// or even nicer with a raw string literal
+auto j2 = R"(
+  {
+    "happy": true,
+    "pi": 3.141
+  }
+)"_json;
+```
+
+Note that without appending the `_json` suffix, the passed string literal is not parsed, but just used as JSON string value. That is, `json j = "{ \"happy\": true, \"pi\": 3.141 }"` would just store the string `"{ "happy": true, "pi": 3.141 }"` rather than parsing the actual object.
+
+The above example can also be expressed explicitly using [`json::parse()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_aa9676414f2e36383c4b181fe856aa3c0.html#aa9676414f2e36383c4b181fe856aa3c0):
+
+```cpp
+// parse explicitly
+auto j3 = json::parse("{ \"happy\": true, \"pi\": 3.141 }");
+```
+
+You can also get a string representation of a JSON value (serialize):
+
+```cpp
+// explicit conversion to string
+std::string s = j.dump();    // {\"happy\":true,\"pi\":3.141}
+
+// serialization with pretty printing
+// pass in the amount of spaces to indent
+std::cout << j.dump(4) << std::endl;
+// {
+//     "happy": true,
+//     "pi": 3.141
+// }
+```
+
+Note the difference between serialization and assignment:
+
+```cpp
+// store a string in a JSON value
+json j_string = "this is a string";
+
+// retrieve the string value (implicit JSON to std::string conversion)
+std::string cpp_string = j_string;
+// retrieve the string value (explicit JSON to std::string conversion)
+auto cpp_string2 = j_string.get<std::string>();
+
+// retrieve the serialized value (explicit JSON serialization)
+std::string serialized_string = j_string.dump();
+
+// output of original string
+std::cout << cpp_string << " == " << cpp_string2 << " == " << j_string.get<std::string>() << '\n';
+// output of serialized value
+std::cout << j_string << " == " << serialized_string << std::endl;
+```
+
+[`.dump()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a5adea76fedba9898d404fef8598aa663.html#a5adea76fedba9898d404fef8598aa663) always returns the serialized value, and [`.get<std::string>()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a16f9445f7629f634221a42b967cdcd43.html#a16f9445f7629f634221a42b967cdcd43) returns the originally stored string value.
+
+
+#### To/from streams (e.g. files, string streams)
+
+You can also use streams to serialize and deserialize:
+
+```cpp
+// deserialize from standard input
+json j;
+std::cin >> j;
+
+// serialize to standard output
+std::cout << j;
+
+// the setw manipulator was overloaded to set the indentation for pretty printing
+std::cout << std::setw(4) << j << std::endl;
+```
+
+These operators work for any subclasses of `std::istream` or `std::ostream`. Here is the same example with files:
+
+```cpp
+// read a JSON file
+std::ifstream i("file.json");
+json j;
+i >> j;
+
+// write prettified JSON to another file
+std::ofstream o("pretty.json");
+o << std::setw(4) << j << std::endl;
+```
+
+Please note that setting the exception bit for `failbit` is inappropriate for this use case. It will result in program termination due to the `noexcept` specifier in use.
+
+#### Read from iterator range
+
+You can also parse JSON from an iterator range; that is, from any container accessible by iterators whose content is stored as contiguous byte sequence, for instance a `std::vector<std::uint8_t>`:
+
+```cpp
+std::vector<std::uint8_t> v = {'t', 'r', 'u', 'e'};
+json j = json::parse(v.begin(), v.end());
+```
+
+You may leave the iterators for the range [begin, end):
+
+```cpp
+std::vector<std::uint8_t> v = {'t', 'r', 'u', 'e'};
+json j = json::parse(v);
+```
+
+
+### STL-like access
+
+We designed the JSON class to behave just like an STL container. In fact, it satisfies the [**ReversibleContainer**](http://en.cppreference.com/w/cpp/concept/ReversibleContainer) requirement.
+
+```cpp
+// create an array using push_back
+json j;
+j.push_back("foo");
+j.push_back(1);
+j.push_back(true);
+
+// also use emplace_back
+j.emplace_back(1.78);
+
+// iterate the array
+for (json::iterator it = j.begin(); it != j.end(); ++it) {
+  std::cout << *it << '\n';
+}
+
+// range-based for
+for (auto& element : j) {
+  std::cout << element << '\n';
+}
+
+// getter/setter
+const std::string tmp = j[0];
+j[1] = 42;
+bool foo = j.at(2);
+
+// comparison
+j == "[\"foo\", 1, true]"_json;  // true
+
+// other stuff
+j.size();     // 3 entries
+j.empty();    // false
+j.type();     // json::value_t::array
+j.clear();    // the array is empty again
+
+// convenience type checkers
+j.is_null();
+j.is_boolean();
+j.is_number();
+j.is_object();
+j.is_array();
+j.is_string();
+
+// create an object
+json o;
+o["foo"] = 23;
+o["bar"] = false;
+o["baz"] = 3.141;
+
+// also use emplace
+o.emplace("weather", "sunny");
+
+// special iterator member functions for objects
+for (json::iterator it = o.begin(); it != o.end(); ++it) {
+  std::cout << it.key() << " : " << it.value() << "\n";
+}
+
+// find an entry
+if (o.find("foo") != o.end()) {
+  // there is an entry with key "foo"
+}
+
+// or simpler using count()
+int foo_present = o.count("foo"); // 1
+int fob_present = o.count("fob"); // 0
+
+// delete an entry
+o.erase("foo");
+```
+
+
+### Conversion from STL containers
+
+Any sequence container (`std::array`, `std::vector`, `std::deque`, `std::forward_list`, `std::list`) whose values can be used to construct JSON values (e.g., integers, floating point numbers, Booleans, string types, or again STL containers described in this section) can be used to create a JSON array. The same holds for similar associative containers (`std::set`, `std::multiset`, `std::unordered_set`, `std::unordered_multiset`), but in these cases the order of the elements of the array depends on how the elements are ordered in the respective STL container.
+
+```cpp
+std::vector<int> c_vector {1, 2, 3, 4};
+json j_vec(c_vector);
+// [1, 2, 3, 4]
+
+std::deque<double> c_deque {1.2, 2.3, 3.4, 5.6};
+json j_deque(c_deque);
+// [1.2, 2.3, 3.4, 5.6]
+
+std::list<bool> c_list {true, true, false, true};
+json j_list(c_list);
+// [true, true, false, true]
+
+std::forward_list<int64_t> c_flist {12345678909876, 23456789098765, 34567890987654, 45678909876543};
+json j_flist(c_flist);
+// [12345678909876, 23456789098765, 34567890987654, 45678909876543]
+
+std::array<unsigned long, 4> c_array {{1, 2, 3, 4}};
+json j_array(c_array);
+// [1, 2, 3, 4]
+
+std::set<std::string> c_set {"one", "two", "three", "four", "one"};
+json j_set(c_set); // only one entry for "one" is used
+// ["four", "one", "three", "two"]
+
+std::unordered_set<std::string> c_uset {"one", "two", "three", "four", "one"};
+json j_uset(c_uset); // only one entry for "one" is used
+// maybe ["two", "three", "four", "one"]
+
+std::multiset<std::string> c_mset {"one", "two", "one", "four"};
+json j_mset(c_mset); // both entries for "one" are used
+// maybe ["one", "two", "one", "four"]
+
+std::unordered_multiset<std::string> c_umset {"one", "two", "one", "four"};
+json j_umset(c_umset); // both entries for "one" are used
+// maybe ["one", "two", "one", "four"]
+```
+
+Likewise, any associative key-value containers (`std::map`, `std::multimap`, `std::unordered_map`, `std::unordered_multimap`) whose keys can construct an `std::string` and whose values can be used to construct JSON values (see examples above) can be used to create a JSON object. Note that in case of multimaps only one key is used in the JSON object and the value depends on the internal order of the STL container.
+
+```cpp
+std::map<std::string, int> c_map { {"one", 1}, {"two", 2}, {"three", 3} };
+json j_map(c_map);
+// {"one": 1, "three": 3, "two": 2 }
+
+std::unordered_map<const char*, double> c_umap { {"one", 1.2}, {"two", 2.3}, {"three", 3.4} };
+json j_umap(c_umap);
+// {"one": 1.2, "two": 2.3, "three": 3.4}
+
+std::multimap<std::string, bool> c_mmap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
+json j_mmap(c_mmap); // only one entry for key "three" is used
+// maybe {"one": true, "two": true, "three": true}
+
+std::unordered_multimap<std::string, bool> c_ummap { {"one", true}, {"two", true}, {"three", false}, {"three", true} };
+json j_ummap(c_ummap); // only one entry for key "three" is used
+// maybe {"one": true, "two": true, "three": true}
+```
+
+### JSON Pointer and JSON Patch
+
+The library supports **JSON Pointer** ([RFC 6901](https://tools.ietf.org/html/rfc6901)) as alternative means to address structured values. On top of this, **JSON Patch** ([RFC 6902](https://tools.ietf.org/html/rfc6902)) allows to describe differences between two JSON values - effectively allowing patch and diff operations known from Unix.
+
+```cpp
+// a JSON value
+json j_original = R"({
+  "baz": ["one", "two", "three"],
+  "foo": "bar"
+})"_json;
+
+// access members with a JSON pointer (RFC 6901)
+j_original["/baz/1"_json_pointer];
+// "two"
+
+// a JSON patch (RFC 6902)
+json j_patch = R"([
+  { "op": "replace", "path": "/baz", "value": "boo" },
+  { "op": "add", "path": "/hello", "value": ["world"] },
+  { "op": "remove", "path": "/foo"}
+])"_json;
+
+// apply the patch
+json j_result = j_original.patch(j_patch);
+// {
+//    "baz": "boo",
+//    "hello": ["world"]
+// }
+
+// calculate a JSON patch from two JSON values
+json::diff(j_result, j_original);
+// [
+//   { "op":" replace", "path": "/baz", "value": ["one", "two", "three"] },
+//   { "op": "remove","path": "/hello" },
+//   { "op": "add", "path": "/foo", "value": "bar" }
+// ]
+```
+
+### JSON Merge Patch
+
+The library supports **JSON Merge Patch** ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format. Instead of using JSON Pointer (see above) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
+
+```cpp
+// a JSON value
+json j_document = R"({
+  "a": "b",
+  "c": {
+    "d": "e",
+    "f": "g"
+  }
+})"_json;
+
+// a patch
+json j_patch = R"({
+  "a":"z",
+  "c": {
+    "f": null
+  }
+})"_json;
+
+// apply the patch
+j_original.merge_patch(j_patch);
+// {
+//  "a": "z",
+//  "c": {
+//    "d": "e"
+//  }
+// }
+```
+
+### Implicit conversions
+
+The type of the JSON object is determined automatically by the expression to store. Likewise, the stored value is implicitly converted.
+
+```cpp
+// strings
+std::string s1 = "Hello, world!";
+json js = s1;
+std::string s2 = js;
+
+// Booleans
+bool b1 = true;
+json jb = b1;
+bool b2 = jb;
+
+// numbers
+int i = 42;
+json jn = i;
+double f = jn;
+
+// etc.
+```
+
+You can also explicitly ask for the value:
+
+```cpp
+std::string vs = js.get<std::string>();
+bool vb = jb.get<bool>();
+int vi = jn.get<int>();
+
+// etc.
+```
+
+### Arbitrary types conversions
+
+Every type can be serialized in JSON, not just STL containers and scalar types. Usually, you would do something along those lines:
+
+```cpp
+namespace ns {
+    // a simple struct to model a person
+    struct person {
+        std::string name;
+        std::string address;
+        int age;
+    };
+}
+
+ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+// convert to JSON: copy each value into the JSON object
+json j;
+j["name"] = p.name;
+j["address"] = p.address;
+j["age"] = p.age;
+
+// ...
+
+// convert from JSON: copy each value from the JSON object
+ns::person p {
+    j["name"].get<std::string>(),
+    j["address"].get<std::string>(),
+    j["age"].get<int>()
+};
+```
+
+It works, but that's quite a lot of boilerplate... Fortunately, there's a better way:
+
+```cpp
+// create a person
+ns::person p {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+// conversion: person -> json
+json j = p;
+
+std::cout << j << std::endl;
+// {"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}
+
+// conversion: json -> person
+ns::person p2 = j;
+
+// that's it
+assert(p == p2);
+```
+
+#### Basic usage
+
+To make this work with one of your types, you only need to provide two functions:
+
+```cpp
+using nlohmann::json;
+
+namespace ns {
+    void to_json(json& j, const person& p) {
+        j = json{{"name", p.name}, {"address", p.address}, {"age", p.age}};
+    }
+
+    void from_json(const json& j, person& p) {
+        p.name = j.at("name").get<std::string>();
+        p.address = j.at("address").get<std::string>();
+        p.age = j.at("age").get<int>();
+    }
+} // namespace ns
+```
+
+That's all! When calling the `json` constructor with your type, your custom `to_json` method will be automatically called.
+Likewise, when calling `get<your_type>()`, the `from_json` method will be called.
+
+Some important things:
+
+* Those methods **MUST** be in your type's namespace (which can be the global namespace), or the library will not be able to locate them (in this example, they are in namespace `ns`, where `person` is defined).
+* Those methods **MUST** be available (e.g., properly headers must be included) everywhere you use the implicit conversions. Look at [issue 1108](https://github.com/nlohmann/json/issues/1108) for errors that may occur otherwise.
+* When using `get<your_type>()`, `your_type` **MUST** be [DefaultConstructible](http://en.cppreference.com/w/cpp/concept/DefaultConstructible). (There is a way to bypass this requirement described later.)
+* In function `from_json`, use function [`at()`](https://nlohmann.github.io/json/classnlohmann_1_1basic__json_a93403e803947b86f4da2d1fb3345cf2c.html#a93403e803947b86f4da2d1fb3345cf2c) to access the object values rather than `operator[]`. In case a key does not exist, `at` throws an exception that you can handle, whereas `operator[]` exhibits undefined behavior.
+* In case your type contains several `operator=` definitions, code like `your_variable = your_json;` [may not compile](https://github.com/nlohmann/json/issues/667). You need to write `your_variable = your_json.get<decltype your_variable>();` instead.
+* You do not need to add serializers or deserializers for STL types like `std::vector`: the library already implements these.
+* Be careful with the definition order of the `from_json`/`to_json` functions: If a type `B` has a member of type `A`, you **MUST** define `to_json(A)` before `to_json(B)`. Look at [issue 561](https://github.com/nlohmann/json/issues/561) for more details.
+
+
+#### How do I convert third-party types?
+
+This requires a bit more advanced technique. But first, let's see how this conversion mechanism works:
+
+The library uses **JSON Serializers** to convert types to json.
+The default serializer for `nlohmann::json` is `nlohmann::adl_serializer` (ADL means [Argument-Dependent Lookup](http://en.cppreference.com/w/cpp/language/adl)).
+
+It is implemented like this (simplified):
+
+```cpp
+template <typename T>
+struct adl_serializer {
+    static void to_json(json& j, const T& value) {
+        // calls the "to_json" method in T's namespace
+    }
+
+    static void from_json(const json& j, T& value) {
+        // same thing, but with the "from_json" method
+    }
+};
+```
+
+This serializer works fine when you have control over the type's namespace. However, what about `boost::optional` or `std::filesystem::path` (C++17)? Hijacking the `boost` namespace is pretty bad, and it's illegal to add something other than template specializations to `std`...
+
+To solve this, you need to add a specialization of `adl_serializer` to the `nlohmann` namespace, here's an example:
+
+```cpp
+// partial specialization (full specialization works too)
+namespace nlohmann {
+    template <typename T>
+    struct adl_serializer<boost::optional<T>> {
+        static void to_json(json& j, const boost::optional<T>& opt) {
+            if (opt == boost::none) {
+                j = nullptr;
+            } else {
+              j = *opt; // this will call adl_serializer<T>::to_json which will
+                        // find the free function to_json in T's namespace!
+            }
+        }
+
+        static void from_json(const json& j, boost::optional<T>& opt) {
+            if (j.is_null()) {
+                opt = boost::none;
+            } else {
+                opt = j.get<T>(); // same as above, but with
+                                  // adl_serializer<T>::from_json
+            }
+        }
+    };
+}
+```
+
+#### How can I use `get()` for non-default constructible/non-copyable types?
+
+There is a way, if your type is [MoveConstructible](http://en.cppreference.com/w/cpp/concept/MoveConstructible). You will need to specialize the `adl_serializer` as well, but with a special `from_json` overload:
+
+```cpp
+struct move_only_type {
+    move_only_type() = delete;
+    move_only_type(int ii): i(ii) {}
+    move_only_type(const move_only_type&) = delete;
+    move_only_type(move_only_type&&) = default;
+
+    int i;
+};
+
+namespace nlohmann {
+    template <>
+    struct adl_serializer<move_only_type> {
+        // note: the return type is no longer 'void', and the method only takes
+        // one argument
+        static move_only_type from_json(const json& j) {
+            return {j.get<int>()};
+        }
+
+        // Here's the catch! You must provide a to_json method! Otherwise you
+        // will not be able to convert move_only_type to json, since you fully
+        // specialized adl_serializer on that type
+        static void to_json(json& j, move_only_type t) {
+            j = t.i;
+        }
+    };
+}
+```
+
+#### Can I write my own serializer? (Advanced use)
+
+Yes. You might want to take a look at [`unit-udt.cpp`](https://github.com/nlohmann/json/blob/develop/test/src/unit-udt.cpp) in the test suite, to see a few examples.
+
+If you write your own serializer, you'll need to do a few things:
+
+- use a different `basic_json` alias than `nlohmann::json` (the last template parameter of `basic_json` is the `JSONSerializer`)
+- use your `basic_json` alias (or a template parameter) in all your `to_json`/`from_json` methods
+- use `nlohmann::to_json` and `nlohmann::from_json` when you need ADL
+
+Here is an example, without simplifications, that only accepts types with a size <= 32, and uses ADL.
+
+```cpp
+// You should use void as a second template argument
+// if you don't need compile-time checks on T
+template<typename T, typename SFINAE = typename std::enable_if<sizeof(T) <= 32>::type>
+struct less_than_32_serializer {
+    template <typename BasicJsonType>
+    static void to_json(BasicJsonType& j, T value) {
+        // we want to use ADL, and call the correct to_json overload
+        using nlohmann::to_json; // this method is called by adl_serializer,
+                                 // this is where the magic happens
+        to_json(j, value);
+    }
+
+    template <typename BasicJsonType>
+    static void from_json(const BasicJsonType& j, T& value) {
+        // same thing here
+        using nlohmann::from_json;
+        from_json(j, value);
+    }
+};
+```
+
+Be **very** careful when reimplementing your serializer, you can stack overflow if you don't pay attention:
+
+```cpp
+template <typename T, void>
+struct bad_serializer
+{
+    template <typename BasicJsonType>
+    static void to_json(BasicJsonType& j, const T& value) {
+      // this calls BasicJsonType::json_serializer<T>::to_json(j, value);
+      // if BasicJsonType::json_serializer == bad_serializer ... oops!
+      j = value;
+    }
+
+    template <typename BasicJsonType>
+    static void to_json(const BasicJsonType& j, T& value) {
+      // this calls BasicJsonType::json_serializer<T>::from_json(j, value);
+      // if BasicJsonType::json_serializer == bad_serializer ... oops!
+      value = j.template get<T>(); // oops!
+    }
+};
+```
+
+### Binary formats (CBOR, MessagePack, and UBJSON)
+
+Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance over a network. Hence, the library supports [CBOR](http://cbor.io) (Concise Binary Object Representation), [MessagePack](http://msgpack.org), and [UBJSON](http://ubjson.org) (Universal Binary JSON Specification) to efficiently encode JSON values to byte vectors and to decode such vectors.
+
+```cpp
+// create a JSON value
+json j = R"({"compact": true, "schema": 0})"_json;
+
+// serialize to CBOR
+std::vector<std::uint8_t> v_cbor = json::to_cbor(j);
+
+// 0xA2, 0x67, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0xF5, 0x66, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00
+
+// roundtrip
+json j_from_cbor = json::from_cbor(v_cbor);
+
+// serialize to MessagePack
+std::vector<std::uint8_t> v_msgpack = json::to_msgpack(j);
+
+// 0x82, 0xA7, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0xC3, 0xA6, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x00
+
+// roundtrip
+json j_from_msgpack = json::from_msgpack(v_msgpack);
+
+// serialize to UBJSON
+std::vector<std::uint8_t> v_ubjson = json::to_ubjson(j);
+
+// 0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61, 0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68, 0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D
+
+// roundtrip
+json j_from_ubjson = json::from_ubjson(v_ubjson);
+```