mkdocs: add string_view examples

docs/examples/at__keytype.cpp

@@ -0,0 +1,50 @@
+#include <iostream>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create JSON object
+    json object =
+    {
+        {"the good", "il buono"},
+        {"the bad", "il cattivo"},
+        {"the ugly", "il brutto"}
+    };
+
+    // output element with key "the ugly" using string_view
+    std::cout << object.at("the ugly"sv) << '\n';
+
+    // change element with key "the bad" using string_view
+    object.at("the bad"sv) = "il cattivo";
+
+    // output changed array
+    std::cout << object << '\n';
+
+
+    // exception type_error.304
+    try
+    {
+        // use at() with string_view on a non-object type
+        json str = "I am a string";
+        str.at("the good"sv) = "Another string";
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // exception out_of_range.401
+    try
+    {
+        // try to write at a nonexisting key using string_view
+        object.at("the fast"sv) = "il rapido";
+    }
+    catch (json::out_of_range& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+}

docs/examples/at__keytype.output

@@ -0,0 +1,4 @@
+"il brutto"
+{"the bad":"il cattivo","the good":"il buono","the ugly":"il brutto"}
+[json.exception.type_error.304] cannot use at() with string
+[json.exception.out_of_range.403] key 'the fast' not found

docs/examples/at__keytype_const.cpp

@@ -0,0 +1,44 @@
+#include <iostream>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create JSON object
+    const json object =
+    {
+        {"the good", "il buono"},
+        {"the bad", "il cattivo"},
+        {"the ugly", "il brutto"}
+    };
+
+    // output element with key "the ugly" using string_view
+    std::cout << object.at("the ugly"sv) << '\n';
+
+
+    // exception type_error.304
+    try
+    {
+        // use at() with string_view on a non-object type
+        const json str = "I am a string";
+        std::cout << str.at("the good"sv) << '\n';
+    }
+    catch (json::type_error& e)
+    {
+        std::cout << e.what() << '\n';
+    }
+
+    // exception out_of_range.401
+    try
+    {
+        // try to read from a nonexisting key using string_view
+        std::cout << object.at("the fast"sv) << '\n';
+    }
+    catch (json::out_of_range)
+    {
+        std::cout << "out of range" << '\n';
+    }
+}

docs/examples/at__keytype_const.output

@@ -0,0 +1,3 @@
+"il brutto"
+[json.exception.type_error.304] cannot use at() with string
+out of range

docs/examples/contains__keytype.cpp

@@ -0,0 +1,19 @@
+#include <iostream>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create some JSON values
+    json j_object = R"( {"key": "value"} )"_json;
+    json j_array = R"( [1, 2, 3] )"_json;
+
+    // call contains
+    std::cout << std::boolalpha <<
+              "j_object contains 'key': " << j_object.contains("key"sv) << '\n' <<
+              "j_object contains 'another': " << j_object.contains("another"sv) << '\n' <<
+              "j_array contains 'key': " << j_array.contains("key"sv) << std::endl;
+}

docs/examples/contains__object_t_key_type.output

@@ -0,0 +1,3 @@
+j_object contains 'key': true
+j_object contains 'another': false
+j_array contains 'key': false

docs/examples/count__keytype.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON object
+    json j_object = {{"one", 1}, {"two", 2}};
+
+    // call count()
+    auto count_two = j_object.count("two"sv);
+    auto count_three = j_object.count("three"sv);
+
+    // print values
+    std::cout << "number of elements with key \"two\": " << count_two << '\n';
+    std::cout << "number of elements with key \"three\": " << count_three << '\n';
+}

docs/examples/count__object_t_key_type.output

@@ -0,0 +1,2 @@
+number of elements with key "two": 1
+number of elements with key "three": 0

docs/examples/erase__keytype.cpp

@@ -0,0 +1,20 @@
+#include <iostream>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON object
+    json j_object = {{"one", 1}, {"two", 2}};
+
+    // call erase()
+    auto count_one = j_object.erase("one"sv);
+    auto count_three = j_object.erase("three"sv);
+
+    // print values
+    std::cout << j_object << '\n';
+    std::cout << count_one << " " << count_three << '\n';
+}

docs/examples/erase__object_t_key_type.output

@@ -0,0 +1,2 @@
+{"two":2}
+1 0

docs/examples/find__keytype.cpp

@@ -0,0 +1,22 @@
+#include <iostream>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON object
+    json j_object = {{"one", 1}, {"two", 2}};
+
+    // call find
+    auto it_two = j_object.find("two"sv);
+    auto it_three = j_object.find("three"sv);
+
+    // print values
+    std::cout << std::boolalpha;
+    std::cout << "\"two\" was found: " << (it_two != j_object.end()) << '\n';
+    std::cout << "value at key \"two\": " << *it_two << '\n';
+    std::cout << "\"three\" was found: " << (it_three != j_object.end()) << '\n';
+}

docs/examples/find__object_t_key_type.output

@@ -0,0 +1,3 @@
+"two" was found: true
+value at key "two": 2
+"three" was found: false

docs/examples/operator_array__keytype.cpp

@@ -0,0 +1,34 @@
+#include <iostream>
+#include <iomanip>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON object
+    json object =
+    {
+        {"one", 1}, {"two", 2}, {"three", 2.9}
+    };
+
+    // output element with key "two"
+    std::cout << object["two"sv] << "\n\n";
+
+    // change element with key "three"
+    object["three"sv] = 3;
+
+    // output changed array
+    std::cout << std::setw(4) << object << "\n\n";
+
+    // mention nonexisting key
+    object["four"sv];
+
+    // write to nonexisting key
+    object["five"sv]["really"sv]["nested"sv] = true;
+
+    // output changed object
+    std::cout << std::setw(4) << object << '\n';
+}

docs/examples/operator_array__keytype_const.cpp

@@ -0,0 +1,18 @@
+#include <iostream>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON object
+    const json object =
+    {
+        {"one", 1}, {"two", 2}, {"three", 2.9}
+    };
+
+    // output element with key "two"
+    std::cout << object["two"sv] << '\n';
+}

docs/examples/operator_array__object_t_key_type.output

@@ -0,0 +1,19 @@
+2
+
+{
+    "one": 1,
+    "three": 3,
+    "two": 2
+}
+
+{
+    "five": {
+        "really": {
+            "nested": true
+        }
+    },
+    "four": null,
+    "one": 1,
+    "three": 3,
+    "two": 2
+}

docs/examples/operator_array__object_t_key_type_const.output

@@ -0,0 +1 @@
+2

docs/examples/value__keytype.cpp

@@ -0,0 +1,32 @@
+#include <iostream>
+#include <string_view>
+#include <nlohmann/json.hpp>
+
+using namespace std::string_view_literals;
+using json = nlohmann::json;
+
+int main()
+{
+    // create a JSON object with different entry types
+    json j =
+    {
+        {"integer", 1},
+        {"floating", 42.23},
+        {"string", "hello world"},
+        {"boolean", true},
+        {"object", {{"key1", 1}, {"key2", 2}}},
+        {"array", {1, 2, 3}}
+    };
+
+    // access existing values
+    int v_integer = j.value("integer"sv, 0);
+    double v_floating = j.value("floating"sv, 47.11);
+
+    // access nonexisting values and rely on default value
+    std::string v_string = j.value("nonexisting"sv, "oops");
+    bool v_boolean = j.value("nonexisting"sv, false);
+
+    // output values
+    std::cout << std::boolalpha << v_integer << " " << v_floating
+              << " " << v_string << " " << v_boolean << "\n";
+}

docs/examples/value__object_t_key_type.output

@@ -0,0 +1 @@
+1 42.23 oops false

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

@@ -137,7 +137,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at__object_t_key_type.output"
     ```
 
-??? example "Example (2) access specified object element with bounds checking"
+??? example "Example: (2) access specified object element with bounds checking"
 
     The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
     that can be thrown.
@@ -152,34 +152,64 @@ Strong exception safety: if an exception occurs, the original value stays intact
     --8<-- "examples/at__object_t_key_type_const.output"
     ```
 
-??? example "Example (4) access specified element via JSON Pointer"
+??? example "Example: (3) access specified object element using string_view with bounds checking"
 
     The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
     exceptions that can be thrown.
     
     ```cpp
-    --8<-- "examples/at_json_pointer.cpp"
+    --8<-- "examples/at__keytype.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/at_json_pointer.output"
+    --8<-- "examples/at__keytype.output"
     ```
 
-??? example "Example (4) access specified element via JSON Pointer"
+??? example "Example: (3) access specified object element using string_view with bounds checking"
 
     The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
     that can be thrown.
     
     ```cpp
-    --8<-- "examples/at_json_pointer_const.cpp"
+    --8<-- "examples/at__keytype_const.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/at_json_pointer_const.output"
+    --8<-- "examples/at__keytype_const.output"
+    ```
+
+??? example "Example: (4) access specified element via JSON Pointer"
+
+    The example below shows how object elements can be read and written using `at()`. It also demonstrates the different
+    exceptions that can be thrown.
+        
+    ```cpp
+    --8<-- "examples/at__json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at__json_pointer.output"
+    ```
+
+??? example "Example: (4) access specified element via JSON Pointer"
+
+    The example below shows how object elements can be read using `at()`. It also demonstrates the different exceptions
+    that can be thrown.
+        
+    ```cpp
+    --8<-- "examples/at__json_pointer_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/at__json_pointer_const.output"
     ```
 
 ## See also

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

@@ -69,32 +69,46 @@ Logarithmic in the size of the JSON object.
 
 ## Examples
 
-??? example "Example (1) check with key"
+??? example "Example: (1) check with key"
 
     The example shows how `contains()` is used.
     
     ```cpp
-    --8<-- "examples/contains.cpp"
+    --8<-- "examples/contains__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/contains.output"
+    --8<-- "examples/contains__object_t_key_type.output"
     ```
 
-??? example "Example (3) check with JSON pointer"
+??? example "Example: (2) check with key using string_view"
 
     The example shows how `contains()` is used.
     
     ```cpp
-    --8<-- "examples/contains_json_pointer.cpp"
+    --8<-- "examples/contains__keytype.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/contains_json_pointer.output"
+    --8<-- "examples/contains__keytype.output"
+    ```
+
+??? example "Example: (3) check with JSON pointer"
+
+    The example shows how `contains()` is used.
+    
+    ```cpp
+    --8<-- "examples/contains__json_pointer.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/contains__json_pointer.output"
     ```
 
 ## Version history

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

@@ -44,18 +44,32 @@ This method always returns `0` when executed on a JSON type that is not an objec
 
 ## Examples
 
-??? example
+??? example "Example: (1) count number of elements"
 
     The example shows how `count()` is used.
     
     ```cpp
-    --8<-- "examples/count.cpp"
+    --8<-- "examples/count__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/count.output"
+    --8<-- "examples/count__object_t_key_type.output"
+    ```
+
+??? example "Example: (2) count number of elements using string_view"
+
+    The example shows how `count()` is used.
+    
+    ```cpp
+    --8<-- "examples/count__keytype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/count__keytype.output"
     ```
 
 ## Version history

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

@@ -165,13 +165,27 @@ Strong exception safety: if an exception occurs, the original value stays intact
     The example shows the effect of `erase()` for different JSON types using an object key.
     
     ```cpp
-    --8<-- "examples/erase__key_type.cpp"
+    --8<-- "examples/erase__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/erase__key_type.output"
+    --8<-- "examples/erase__object_t_key_type.output"
+    ```
+
+??? example "Example: (4) remove element from a JSON object given a key using string_view"
+
+    The example shows the effect of `erase()` for different JSON types using an object key.
+    
+    ```cpp
+    --8<-- "examples/erase__keytype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/erase__keytype.output"
     ```
 
 ??? example "Example: (5) remove element from a JSON array given an index"

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

@@ -48,18 +48,32 @@ This method always returns `end()` when executed on a JSON type that is not an o
 
 ## Examples
 
-??? example
+??? example "Example: (1) find object element by key"
 
     The example shows how `find()` is used.
     
     ```cpp
-    --8<-- "examples/find__key_type.cpp"
+    --8<-- "examples/find__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/find__key_type.output"
+    --8<-- "examples/find__object_t_key_type.output"
+    ```
+
+??? example "Example: (2) find object element by key using string_view"
+
+    The example shows how `find()` is used.
+    
+    ```cpp
+    --8<-- "examples/find__keytype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/find__keytype.output"
     ```
 
 ## See also

docs/mkdocs/docs/api/basic_json/operator[].md

@@ -111,89 +111,117 @@ Strong exception safety: if an exception occurs, the original value stays intact
 
 ## Examples
 
-??? example "Example (1): access specified array element"
+??? example "Example: (1) access specified array element"
 
     The example below shows how array elements can be read and written using `[]` operator. Note the addition of
     `#!json null` values.
         
     ```cpp
-    --8<-- "examples/operatorarray__size_type.cpp"
+    --8<-- "examples/operator_array__size_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorarray__size_type.output"
+    --8<-- "examples/operator_array__size_type.output"
     ```
 
-??? example "Example (1): access specified array element"
+??? example "Example: (1) access specified array element (const)"
 
     The example below shows how array elements can be read using the `[]` operator.
 
     ```cpp
-    --8<-- "examples/operatorarray__size_type_const.cpp"
+    --8<-- "examples/operator_array__size_type_const.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorarray__size_type_const.output"
+    --8<-- "examples/operator_array__size_type_const.output"
     ```
 
-??? example "Example (2): access specified object element"
+??? example "Example: (2) access specified object element"
 
     The example below shows how object elements can be read and written using the `[]` operator.
     
     ```cpp
-    --8<-- "examples/operatorarray__key_type.cpp"
+    --8<-- "examples/operator_array__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorarray__key_type.output"
+    --8<-- "examples/operator_array__object_t_key_type.output"
     ```
 
-??? example "Example (2): access specified object element (const)"
+??? example "Example: (2) access specified object element (const)"
 
     The example below shows how object elements can be read using the `[]` operator.
     
     ```cpp
-    --8<-- "examples/operatorarray__key_type_const.cpp"
+    --8<-- "examples/operator_array__object_t_key_type_const.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorarray__key_type_const.output"
+    --8<-- "examples/operator_array__object_t_key_type_const.output"
     ```
 
-??? example "Example (4): access specified element via JSON Pointer"
+??? example "Example: (3) access specified object element using string_view"
+
+    The example below shows how object elements can be read using the `[]` operator.
+    
+    ```cpp
+    --8<-- "examples/operator_array__keytype.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_array__keytype.output"
+    ```
+
+??? example "Example: (3) access specified object element using string_view (const)"
+
+    The example below shows how object elements can be read using the `[]` operator.
+    
+    ```cpp
+    --8<-- "examples/operator_array__keytype_const.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/operator_array__keytype_const.output"
+    ```
+
+??? example "Example: (4) access specified element via JSON Pointer"
 
     The example below shows how values can be read and written using JSON Pointers.
     
     ```cpp
-    --8<-- "examples/operatorjson_pointer.cpp"
+    --8<-- "examples/operator_array__json_pointer.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorjson_pointer.output"
+    --8<-- "examples/operator_array__json_pointer.output"
     ```
 
-??? example "Example (4): access specified element via JSON Pointer (const)"
+??? example "Example: (4) access specified element via JSON Pointer (const)"
 
     The example below shows how values can be read using JSON Pointers.
     
     ```cpp
-    --8<-- "examples/operatorjson_pointer_const.cpp"
+    --8<-- "examples/operator_array__json_pointer_const.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/operatorjson_pointer_const.output"
+    --8<-- "examples/operator_array__json_pointer_const.output"
     ```
 
 ## See also

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

@@ -105,32 +105,46 @@ changes to any JSON value.
 
 ## Examples
 
-??? example "Example (1): access specified object element with default value"
+??? example "Example: (1) access specified object element with default value"
 
     The example below shows how object elements can be queried with a default value.
     
     ```cpp
-    --8<-- "examples/basic_json__value.cpp"
+    --8<-- "examples/value__object_t_key_type.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/basic_json__value.output"
+    --8<-- "examples/value__object_t_key_type.output"
     ```
 
-??? example "Example (3): access specified object element via JSON Pointer with default value"
+??? example "Example: (2) access specified object element using string_view with default value"
 
     The example below shows how object elements can be queried with a default value.
     
     ```cpp
-    --8<-- "examples/basic_json__value_ptr.cpp"
+    --8<-- "examples/value__keytype.cpp"
     ```
     
     Output:
     
     ```json
-    --8<-- "examples/basic_json__value_ptr.output"
+    --8<-- "examples/value__keytype.output"
+    ```
+
+??? example "Example: (3) access specified object element via JSON Pointer with default value"
+
+    The example below shows how object elements can be queried with a default value.
+    
+    ```cpp
+    --8<-- "examples/value__json_ptr.cpp"
+    ```
+    
+    Output:
+    
+    ```json
+    --8<-- "examples/value__json_ptr.output"
     ```
 
 ## See also