📝 add more examples

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/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::object_comparator_t{}("one", "two") << "\n"
+              << "three < four : " << json::object_comparator_t{}("three", "four") << std::endl;
+}

docs/examples/object_comparator_t.output

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

docs/mkdocs/docs/api/basic_json/basic_json.md

@@ -241,7 +241,7 @@ basic_json(basic_json&& other) noexcept;
 
 - Overload 5:
 
-    !!! note
+    !!! note "Empty initializer list"
 
         When used without parentheses around an empty initializer list, `basic_json()` is called instead of this
         function, yielding the JSON `#!json null` value.

docs/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md

@@ -20,6 +20,23 @@ ignore
 store
 :   store tagged values as binary container with subtype (for bytes 0xd8..0xdb)
 
+## Examples
+
+??? example
+
+    The example below shows how the different values of the `cbor_tag_handler_t` influence the behavior of
+    [`from_cbor`](from_cbor.md) when reading a tagged byte string.
+
+    ```cpp
+    --8<-- "examples/cbor_tag_handler_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/cbor_tag_handler_t.output"
+    ```
+
 ## Version history
 
 - Added in version 3.9.0. Added value `store` in 3.10.0.

docs/mkdocs/docs/api/basic_json/default_object_comparator_t.md

@@ -14,6 +14,22 @@ when looking up a key in an object.
 The actual comparator used depends on [`object_t`](object_t.md) and can be obtained via
 [`object_comparator_t`](object_comparator_t.md).
 
+## Examples
+
+??? example
+
+    The example below demonstrates the default comparator.
+
+    ```cpp
+    --8<-- "examples/default_object_comparator_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/default_object_comparator_t.output"
+    ```
+
 ## Version history
 
 - Added in version 3.11.0.

docs/mkdocs/docs/api/basic_json/error_handler_t.md

@@ -20,6 +20,23 @@ replace
 ignore
 :   ignore invalid UTF-8 sequences; all bytes are copied to the output unchanged
 
+## Examples
+
+??? example
+
+    The example below shows how the different values of the `error_handler_t` influence the behavior of
+    [`dump`](dump.md) when reading serializing an invalid UTF-8 sequence.
+
+    ```cpp
+    --8<-- "examples/error_handler_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/error_handler_t.output"
+    ```
+
 ## Version history
 
 - Added in version 3.4.0.

docs/mkdocs/docs/api/basic_json/object_comparator_t.md

@@ -9,6 +9,22 @@ using object_comparator_t = default_object_comparator_t;
 The comparator used by [`object_t`](object_t.md). Defined as `#!cpp typename object_t::key_compare` if available,
 and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
 
+## Examples
+
+??? example
+
+    The example below demonstrates the used object comparator.
+
+    ```cpp
+    --8<-- "examples/object_comparator_t.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/object_comparator_t.output"
+    ```
+
 ## Version history
 
 - Added in version 3.0.0.