Complete documentation for 3.11.0 (#3464)

* 👥 update contributor and sponsor list

* 🚧 document BJData format

* 🚧 document BJData format

* 📝 clarified documentation of [json.exception.parse_error.112]

* ✏️ adjust titles

* 📝 add more examples

* 🚨 adjust warnings for index.md files

* 📝 add more examples

* 🔥 remove example for deprecated code

* 📝 add missing enum entry

* 📝 overwork table for binary formats

* ✅ add test to create table for binary formats

* 📝 fix wording in example

* 📝 add more examples

* Update iterators.md (#3481)

* ✨ add check for overloads to linter #3455

* 👥 update contributor list

* 📝 add more examples

* 📝 fix documentation

* 📝 add more examples

* 🎨 fix indentation

* 🔥 remove example for destructor

* 📝 overwork documentation

* Updated BJData documentation, #3464 (#3493)

* update bjdata.md for #3464

* Minor edit

* Fix URL typo

* Add info on demoting ND array to a 1-D optimized array when singleton dimension

Co-authored-by: Chaoqi Zhang <prncoprs@163.com>
Co-authored-by: Qianqian Fang <fangqq@gmail.com>

docs/examples/byte_container_with_subtype__byte_container_with_subtype.cpp

@@ -0,0 +1,23 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+using json = nlohmann::json;
+
+int main()
+{
+    // (1) create empty container
+    auto c1 = byte_container_with_subtype();
+
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // (2) create container
+    auto c2 = byte_container_with_subtype(bytes);
+
+    // (3) create container with subtype
+    auto c3 = byte_container_with_subtype(bytes, 42);
+
+    std::cout << json(c1) << "\n" << json(c2) << "\n" << json(c3) << std::endl;
+}

docs/examples/byte_container_with_subtype__byte_container_with_subtype.output

@@ -0,0 +1,3 @@
+{"bytes":[],"subtype":null}
+{"bytes":[202,254,186,190],"subtype":null}
+{"bytes":[202,254,186,190],"subtype":42}

docs/examples/byte_container_with_subtype__clear_subtype.cpp

@@ -0,0 +1,21 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // create container with subtype
+    auto c1 = byte_container_with_subtype(bytes, 42);
+
+    std::cout << "before calling clear_subtype(): " << json(c1) << '\n';
+
+    c1.clear_subtype();
+
+    std::cout << "after calling clear_subtype(): " << json(c1) << '\n';
+}

docs/examples/byte_container_with_subtype__clear_subtype.output

@@ -0,0 +1,2 @@
+before calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":42}
+after calling clear_subtype(): {"bytes":[202,254,186,190],"subtype":null}

docs/examples/byte_container_with_subtype__has_subtype.cpp

@@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+int main()
+{
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // create container
+    auto c1 = byte_container_with_subtype(bytes);
+
+    // create container with subtype
+    auto c2 = byte_container_with_subtype(bytes, 42);
+
+    std::cout << std::boolalpha << "c1.has_subtype() = " << c1.has_subtype()
+              << "\nc2.has_subtype() = " << c2.has_subtype() << std::endl;
+}

docs/examples/byte_container_with_subtype__has_subtype.output

@@ -0,0 +1,2 @@
+c1.has_subtype() = false
+c2.has_subtype() = true

docs/examples/byte_container_with_subtype__set_subtype.cpp

@@ -0,0 +1,22 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // create container without subtype
+    auto c = byte_container_with_subtype(bytes);
+
+    std::cout << "before calling set_subtype(42): " << json(c) << '\n';
+
+    // set the subtype
+    c.set_subtype(42);
+
+    std::cout << "after calling set_subtype(42): " << json(c) << '\n';
+}

docs/examples/byte_container_with_subtype__set_subtype.output

@@ -0,0 +1,2 @@
+before calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":null}
+after calling set_subtype(42): {"bytes":[202,254,186,190],"subtype":42}

docs/examples/byte_container_with_subtype__subtype.cpp

@@ -0,0 +1,22 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// define a byte container based on std::vector
+using byte_container_with_subtype = nlohmann::byte_container_with_subtype<std::vector<std::uint8_t>>;
+
+int main()
+{
+    std::vector<std::uint8_t> bytes = {{0xca, 0xfe, 0xba, 0xbe}};
+
+    // create container
+    auto c1 = byte_container_with_subtype(bytes);
+
+    // create container with subtype
+    auto c2 = byte_container_with_subtype(bytes, 42);
+
+    std::cout << "c1.subtype() = " << c1.subtype()
+              << "\nc2.subtype() = " << c2.subtype() << std::endl;
+
+    // in case no subtype is set, return special value
+    assert(c1.subtype() == static_cast<byte_container_with_subtype::subtype_type>(-1));
+}

docs/examples/byte_container_with_subtype__subtype.output

@@ -0,0 +1,2 @@
+c1.subtype() = 18446744073709551615
+c2.subtype() = 42

docs/examples/cbor_tag_handler_t.cpp

@@ -0,0 +1,28 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // tagged byte string
+    std::vector<std::uint8_t> vec = {{0xd8, 0x42, 0x44, 0xcA, 0xfe, 0xba, 0xbe}};
+
+    // cbor_tag_handler_t::error throws
+    try
+    {
+        auto b_throw_on_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::error);
+    }
+    catch (json::parse_error& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+
+    // cbor_tag_handler_t::ignore ignores the tag
+    auto b_ignore_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::ignore);
+    std::cout << b_ignore_tag << std::endl;
+
+    // cbor_tag_handler_t::store stores the tag as binary subtype
+    auto b_store_tag = json::from_cbor(vec, true, true, json::cbor_tag_handler_t::store);
+    std::cout << b_store_tag << std::endl;
+}

docs/examples/cbor_tag_handler_t.output

@@ -0,0 +1,3 @@
+[json.exception.parse_error.112] parse error at byte 1: syntax error while parsing CBOR value: invalid byte: 0xD8
+{"bytes":[202,254,186,190],"subtype":null}
+{"bytes":[202,254,186,190],"subtype":66}

docs/examples/default_object_comparator_t.cpp

@@ -0,0 +1,11 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << "one < two : " << json::default_object_comparator_t{}("one", "two") << "\n"
+              << "three < four : " << json::default_object_comparator_t{}("three", "four") << std::endl;
+}

docs/examples/default_object_comparator_t.output

@@ -0,0 +1,2 @@
+one < two : true
+three < four : false

docs/examples/error_handler_t.cpp

@@ -0,0 +1,24 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create JSON value with invalid UTF-8 byte sequence
+    json j_invalid = "ä\xA9ü";
+    try
+    {
+        std::cout << j_invalid.dump() << std::endl;
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << std::endl;
+    }
+
+    std::cout << "string with replaced invalid characters: "
+              << j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
+              << "\nstring with ignored invalid characters: "
+              << j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
+              << '\n';
+}

docs/examples/error_handler_t.output

@@ -0,0 +1,3 @@
+[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
+string with replaced invalid characters: "ä<>ü"
+string with ignored invalid characters: "äü"

docs/examples/from_bjdata.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // create byte vector
+    std::vector<std::uint8_t> v = {0x7B, 0x69, 0x07, 0x63, 0x6F, 0x6D, 0x70, 0x61,
+                                   0x63, 0x74, 0x54, 0x69, 0x06, 0x73, 0x63, 0x68,
+                                   0x65, 0x6D, 0x61, 0x69, 0x00, 0x7D
+                                  };
+
+    // deserialize it with BJData
+    json j = json::from_bjdata(v);
+
+    // print the deserialized JSON value
+    std::cout << std::setw(2) << j << std::endl;
+}

docs/examples/from_bjdata.output

@@ -0,0 +1,4 @@
+{
+  "compact": true,
+  "schema": 0
+}

docs/examples/get_allocator.cpp

@@ -0,0 +1,18 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    auto alloc = json::get_allocator();
+    using traits_t = std::allocator_traits<decltype(alloc)>;
+
+    json* j = traits_t::allocate(alloc, 1);
+    traits_t::construct(alloc, j, "Hello, world!");
+
+    std::cout << *j << std::endl;
+
+    traits_t::destroy(alloc, j);
+    traits_t::deallocate(alloc, j, 1);
+}

docs/examples/get_allocator.output

@@ -0,0 +1 @@
+"Hello, world!"

docs/examples/iterator_wrapper.cpp

@@ -1,29 +0,0 @@
-#include <iostream>
-#include <nlohmann/json.hpp>
-
-using json = nlohmann::json;
-
-int main()
-{
-    // create JSON values
-    json j_object = {{"one", 1}, {"two", 2}};
-    json j_array = {1, 2, 4, 8, 16};
-
-    //////////////////////////////////////////////////////////////////////////
-    // The static function iterator_wrapper was deprecated in version 3.1.0
-    // and will be removed in version 4.0.0. Please replace all occurrences
-    // of iterator_wrapper(j) with j.items().
-    //////////////////////////////////////////////////////////////////////////
-
-    // example for an object
-    for (auto& x : json::iterator_wrapper(j_object))
-    {
-        std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
-    }
-
-    // example for an array
-    for (auto& x : json::iterator_wrapper(j_array))
-    {
-        std::cout << "key: " << x.key() << ", value: " << x.value() << '\n';
-    }
-}

docs/examples/iterator_wrapper.output

@@ -1,7 +0,0 @@
-key: one, value: 1
-key: two, value: 2
-key: 0, value: 1
-key: 1, value: 2
-key: 2, value: 4
-key: 3, value: 8
-key: 4, value: 16

docs/examples/json_pointer__operator_string.cpp

@@ -0,0 +1,19 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    // different JSON Pointers
+    json::json_pointer ptr1("/foo/0");
+    json::json_pointer ptr2("/a~1b");
+
+    // implicit conversion to string
+    std::string s;
+    s += ptr1;
+    s += "\n";
+    s += ptr2;
+
+    std::cout << s << std::endl;
+}

docs/examples/json_pointer__operator_string.output

@@ -0,0 +1,2 @@
+/foo/0
+/a~1b

docs/examples/json_pointer__string_t.cpp

@@ -0,0 +1,13 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    json::json_pointer::string_t s = "This is a string.";
+
+    std::cout << s << std::endl;
+
+    std::cout << std::boolalpha << std::is_same<json::json_pointer::string_t, json::string_t>::value << std::endl;
+}

docs/examples/json_pointer__string_t.output

@@ -0,0 +1,2 @@
+This is a string.
+true

docs/examples/json_pointer__to_string.cpp

@@ -19,7 +19,6 @@ int main()
     json::json_pointer ptr11("/ ");
     json::json_pointer ptr12("/m~0n");
 
-
     std::cout << ptr1.to_string() << '\n'
               << ptr2.to_string() << '\n'
               << ptr3.to_string() << '\n'

docs/examples/nlohmann_json_version.cpp

@@ -0,0 +1,12 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << "JSON for Modern C++ version "
+              << NLOHMANN_JSON_VERSION_MAJOR << "."
+              << NLOHMANN_JSON_VERSION_MINOR << "."
+              << NLOHMANN_JSON_VERSION_PATCH << std::endl;
+}

docs/examples/nlohmann_json_version.output

@@ -0,0 +1 @@
+JSON for Modern C++ version 3.10.5

docs/examples/object_comparator_t.cpp

@@ -0,0 +1,11 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+int main()
+{
+    std::cout << std::boolalpha
+              << "json::object_comparator_t(\"one\", \"two\") = " << json::object_comparator_t{}("one", "two") << "\n"
+              << "json::object_comparator_t(\"three\", \"four\") = " << json::object_comparator_t{}("three", "four") << std::endl;
+}

docs/examples/object_comparator_t.output

@@ -0,0 +1,2 @@
+json::object_comparator_t("one", "two") = true
+json::object_comparator_t("three", "four") = false

docs/examples/ordered_json.cpp

@@ -0,0 +1,14 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using ordered_json = nlohmann::ordered_json;
+
+int main()
+{
+    ordered_json j;
+    j["one"] = 1;
+    j["two"] = 2;
+    j["three"] = 3;
+
+    std::cout << j.dump(2) << '\n';
+}

docs/examples/ordered_json.output

@@ -0,0 +1,5 @@
+{
+  "one": 1,
+  "two": 2,
+  "three": 3
+}

docs/examples/sax_parse.cpp

@@ -6,7 +6,7 @@
 using json = nlohmann::json;
 
 // a simple event consumer that collects string representations of the passed
-// values; not inheriting from json::json_sax_t is not required, but can
+// values; note inheriting from json::json_sax_t is not required, but can
 // help not to forget a required function
 class sax_event_consumer : public json::json_sax_t
 {
@@ -15,79 +15,79 @@ class sax_event_consumer : public json::json_sax_t
 
     bool null() override
     {
-        events.push_back("value: null");
+        events.push_back("null()");
         return true;
     }
 
     bool boolean(bool val) override
     {
-        events.push_back("value: " + std::string(val ? "true" : "false"));
+        events.push_back("boolean(val=" + std::string(val ? "true" : "false") + ")");
         return true;
     }
 
     bool number_integer(number_integer_t val) override
     {
-        events.push_back("value: " + std::to_string(val));
+        events.push_back("number_integer(val=" + std::to_string(val) + ")");
         return true;
     }
 
     bool number_unsigned(number_unsigned_t val) override
     {
-        events.push_back("value: " + std::to_string(val));
+        events.push_back("number_unsigned(val=" + std::to_string(val) + ")");
         return true;
     }
 
     bool number_float(number_float_t val, const string_t& s) override
     {
-        events.push_back("value: " + s);
+        events.push_back("number_float(val=" + std::to_string(val) + ", s=" + s + ")");
         return true;
     }
 
     bool string(string_t& val) override
     {
-        events.push_back("value: " + val);
+        events.push_back("string(val=" + val + ")");
         return true;
     }
 
     bool start_object(std::size_t elements) override
     {
-        events.push_back("start: object");
+        events.push_back("start_object(elements=" + std::to_string(elements) + ")");
         return true;
     }
 
     bool end_object() override
     {
-        events.push_back("end: object");
+        events.push_back("end_object()");
         return true;
     }
 
     bool start_array(std::size_t elements) override
     {
-        events.push_back("start: array");
+        events.push_back("start_array(elements=" + std::to_string(elements) + ")");
         return true;
     }
 
     bool end_array() override
     {
-        events.push_back("end: array");
+        events.push_back("end_array()");
         return true;
     }
 
     bool key(string_t& val) override
     {
-        events.push_back("key: " + val);
+        events.push_back("key(val=" + val + ")");
         return true;
     }
 
     bool binary(json::binary_t& val) override
     {
-        events.push_back("binary");
+        events.push_back("binary(val=[...])");
         return true;
     }
 
     bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
     {
-        events.push_back("error: " + std::string(ex.what()));
+        events.push_back("parse_error(position=" + std::to_string(position) + ", last_token=" + last_token + ",\n            ex=" + std::string(ex.what()) + ")");
         return false;
     }
 };
@@ -107,22 +107,23 @@ int main()
                 "Width":  100
             },
             "Animated" : false,
-            "IDs": [116, 943, 234, 38793],
+            "IDs": [116, 943, 234, -38793],
+            "DeletionDate": null,
             "Distance": 12.723374634
         }
-    }
+    }]
     )";
 
     // create a SAX event consumer object
     sax_event_consumer sec;
 
-    // parse and serialize JSON
+    // parse JSON
     bool result = json::sax_parse(text, &sec);
 
     // output the recorded events
     for (auto& event : sec.events)
     {
-        std::cout << "(" << event << ") ";
+        std::cout << event << "\n";
     }
 
     // output the result of sax_parse

docs/examples/sax_parse.output

@@ -1,2 +1,37 @@
-(start: object) (key: Image) (start: object) (key: Width) (value: 800) (key: Height) (value: 600) (key: Title) (value: View from 15th Floor) (key: Thumbnail) (start: object) (key: Url) (value: http://www.example.com/image/481989943) (key: Height) (value: 125) (key: Width) (value: 100) (end: object) (key: Animated) (value: false) (key: IDs) (start: array) (value: 116) (value: 943) (value: 234) (value: 38793) (end: array) (key: Distance) (value: 12.723374634) (end: object) (end: object) 
-result: true
+start_object(elements=18446744073709551615)
+key(val=Image)
+start_object(elements=18446744073709551615)
+key(val=Width)
+number_unsigned(val=800)
+key(val=Height)
+number_unsigned(val=600)
+key(val=Title)
+string(val=View from 15th Floor)
+key(val=Thumbnail)
+start_object(elements=18446744073709551615)
+key(val=Url)
+string(val=http://www.example.com/image/481989943)
+key(val=Height)
+number_unsigned(val=125)
+key(val=Width)
+number_unsigned(val=100)
+end_object()
+key(val=Animated)
+boolean(val=false)
+key(val=IDs)
+start_array(elements=18446744073709551615)
+number_unsigned(val=116)
+number_unsigned(val=943)
+number_unsigned(val=234)
+number_integer(val=-38793)
+end_array()
+key(val=DeletionDate)
+null()
+key(val=Distance)
+number_float(val=12.723375, s=12.723374634)
+end_object()
+end_object()
+parse_error(position=460, last_token=12.723374634<U+000A>        }<U+000A>    }],
+            ex=[json.exception.parse_error.101] parse error at line 17, column 6: syntax error while parsing value - unexpected ']'; expected end of input)
+
+result: false

docs/examples/sax_parse__binary.cpp

@@ -0,0 +1,114 @@
+#include <iostream>
+#include <iomanip>
+#include <sstream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+// a simple event consumer that collects string representations of the passed
+// values; note inheriting from json::json_sax_t is not required, but can
+// help not to forget a required function
+class sax_event_consumer : public json::json_sax_t
+{
+  public:
+    std::vector<std::string> events;
+
+    bool null() override
+    {
+        events.push_back("null()");
+        return true;
+    }
+
+    bool boolean(bool val) override
+    {
+        events.push_back("boolean(val=" + std::string(val ? "true" : "false") + ")");
+        return true;
+    }
+
+    bool number_integer(number_integer_t val) override
+    {
+        events.push_back("number_integer(val=" + std::to_string(val) + ")");
+        return true;
+    }
+
+    bool number_unsigned(number_unsigned_t val) override
+    {
+        events.push_back("number_unsigned(val=" + std::to_string(val) + ")");
+        return true;
+    }
+
+    bool number_float(number_float_t val, const string_t& s) override
+    {
+        events.push_back("number_float(val=" + std::to_string(val) + ", s=" + s + ")");
+        return true;
+    }
+
+    bool string(string_t& val) override
+    {
+        events.push_back("string(val=" + val + ")");
+        return true;
+    }
+
+    bool start_object(std::size_t elements) override
+    {
+        events.push_back("start_object(elements=" + std::to_string(elements) + ")");
+        return true;
+    }
+
+    bool end_object() override
+    {
+        events.push_back("end_object()");
+        return true;
+    }
+
+    bool start_array(std::size_t elements) override
+    {
+        events.push_back("start_array(elements=" + std::to_string(elements) + ")");
+        return true;
+    }
+
+    bool end_array() override
+    {
+        events.push_back("end_array()");
+        return true;
+    }
+
+    bool key(string_t& val) override
+    {
+        events.push_back("key(val=" + val + ")");
+        return true;
+    }
+
+    bool binary(json::binary_t& val) override
+    {
+        events.push_back("binary(val=[...])");
+        return true;
+    }
+
+    bool parse_error(std::size_t position, const std::string& last_token, const json::exception& ex) override
+    {
+        events.push_back("parse_error(position=" + std::to_string(position) + ", last_token=" + last_token + ",\n            ex=" + std::string(ex.what()) + ")");
+        return false;
+    }
+};
+
+int main()
+{
+    // CBOR byte string
+    std::vector<std::uint8_t> vec = {{0x44, 0xcA, 0xfe, 0xba, 0xbe}};
+
+    // create a SAX event consumer object
+    sax_event_consumer sec;
+
+    // parse CBOR
+    bool result = json::sax_parse(vec, &sec, json::input_format_t::cbor);
+
+    // output the recorded events
+    for (auto& event : sec.events)
+    {
+        std::cout << event << "\n";
+    }
+
+    // output the result of sax_parse
+    std::cout << "\nresult: " << std::boolalpha << result << std::endl;
+}

docs/examples/sax_parse__binary.output

@@ -0,0 +1,3 @@
+binary(val=[...])
+
+result: true

docs/examples/to_bjdata.cpp

@@ -0,0 +1,63 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+// function to print BJData's diagnostic format
+void print_byte(uint8_t byte)
+{
+    if (32 < byte and byte < 128)
+    {
+        std::cout << (char)byte;
+    }
+    else
+    {
+        std::cout << (int)byte;
+    }
+}
+
+int main()
+{
+    // create a JSON value
+    json j = R"({"compact": true, "schema": false})"_json;
+
+    // serialize it to BJData
+    std::vector<std::uint8_t> v = json::to_bjdata(j);
+
+    // print the vector content
+    for (auto& byte : v)
+    {
+        print_byte(byte);
+    }
+    std::cout << std::endl;
+
+    // create an array of numbers
+    json array = {1, 2, 3, 4, 5, 6, 7, 8};
+
+    // serialize it to BJData using default representation
+    std::vector<std::uint8_t> v_array = json::to_bjdata(array);
+    // serialize it to BJData using size optimization
+    std::vector<std::uint8_t> v_array_size = json::to_bjdata(array, true);
+    // serialize it to BJData using type optimization
+    std::vector<std::uint8_t> v_array_size_and_type = json::to_bjdata(array, true, true);
+
+    // print the vector contents
+    for (auto& byte : v_array)
+    {
+        print_byte(byte);
+    }
+    std::cout << std::endl;
+
+    for (auto& byte : v_array_size)
+    {
+        print_byte(byte);
+    }
+    std::cout << std::endl;
+
+    for (auto& byte : v_array_size_and_type)
+    {
+        print_byte(byte);
+    }
+    std::cout << std::endl;
+}

docs/examples/to_bjdata.output

@@ -0,0 +1,4 @@
+{i7compactTi6schemaF}
+[i1i2i3i4i5i6i7i8]
+[#i8i1i2i3i4i5i6i7i8
+[$i#i812345678