More documentation updates for 3.11.0 (#3553)

* mkdocs: add string_view examples

* mkdocs: reference underlying operators

* mkdocs: add operator<=> examples

* mkdocs: fix style check issues

* mkdocs: tweak BJData page

* mkdocs: add CMake option hints to macros

* mkdocs: fix JSON_DISABLE_ENUM_SERIALIZATION definition

* mkdocs: fix link to unit-udt.cpp

* mkdocs: fix "Arbitrary Type Conversions" title

* mkdocs: link to api/macros/*.md instead of features/macros.md

* mkdocs: document JSON_DisableEnumSerialization CMake option

* mkdocs: encode required C++ standard in example files

* docset: detect gsed/sed

* docset: update index

* docset: fix CSS patching

* docset: add list_missing_pages make target

* docset: add list_removed_paths make target

* docset: replace page titles with name from index

* docset: add install target for Zeal docset browser

* Use GCC_TOOL in ci_test_documentation target

docs/examples/at__keytype.c++17.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.c++17.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.c++17.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.c++17.output

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

docs/examples/contains__keytype.c++17.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.c++17.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.c++17.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.c++17.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.c++17.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.c++17.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/operator_spaceship__const_reference.c++20.cpp

@@ -0,0 +1,41 @@
+#include <compare>
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+const char* to_string(const std::partial_ordering& po)
+{
+    if (std::is_lt(po))
+    {
+        return "less";
+    }
+    else if (std::is_gt(po))
+    {
+        return "greater";
+    }
+    else if (std::is_eq(po))
+    {
+        return "equivalent";
+    }
+    return "unordered";
+}
+
+int main()
+{
+    // create several JSON values
+    json array_1 = {1, 2, 3};
+    json array_2 = {1, 2, 4};
+    json object_1 = {{"A", "a"}, {"B", "b"}};
+    json object_2 = {{"B", "b"}, {"A", "a"}};
+    json number = 17;
+    json string = "foo";
+    json discarded = json(json::value_t::discarded);
+
+
+    // output values and comparisons
+    std::cout << array_1 << " <=> " << array_2 << " := " << to_string(array_1 <=> array_2) << '\n'; // *NOPAD*
+    std::cout << object_1 << " <=> " << object_2 << " := " << to_string(object_1 <=> object_2) << '\n'; // *NOPAD*
+    std::cout << string << " <=> " << number << " := " << to_string(string <=> number) << '\n'; // *NOPAD*
+    std::cout << string << " <=> " << discarded << " := " << to_string(string <=> discarded) << '\n'; // *NOPAD*
+}

docs/examples/operator_spaceship__const_reference.c++20.output

@@ -0,0 +1,4 @@
+[1,2,3] <=> [1,2,4] := less
+{"A":"a","B":"b"} <=> {"A":"a","B":"b"} := equivalent
+"foo" <=> 17 := greater
+"foo" <=> <discarded> := unordered

docs/examples/operator_spaceship__scalartype.c++20.cpp

@@ -0,0 +1,41 @@
+#include <compare>
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+const char* to_string(const std::partial_ordering& po)
+{
+    if (std::is_lt(po))
+    {
+        return "less";
+    }
+    else if (std::is_gt(po))
+    {
+        return "greater";
+    }
+    else if (std::is_eq(po))
+    {
+        return "equivalent";
+    }
+    return "unordered";
+}
+
+int main()
+{
+    using float_limits = std::numeric_limits<json::number_float_t>;
+    constexpr auto nan = float_limits::quiet_NaN();
+
+    // create several JSON values
+    json boolean = false;
+    json number = 17;
+    json string = "17";
+
+
+    // output values and comparisons
+    std::cout << std::boolalpha << std::fixed;
+    std::cout << boolean << " <=> " << true << " := " << to_string(boolean <=> true) << '\n'; // *NOPAD*
+    std::cout << number << " <=> " << 17.0 << " := " << to_string(number <=> 17.0) << '\n'; // *NOPAD*
+    std::cout << number << " <=> " << nan << " := " << to_string(number <=> nan) << '\n'; // *NOPAD*
+    std::cout << string << " <=> " << 17 << " := " << to_string(string <=> 17) << '\n'; // *NOPAD*
+}

docs/examples/operator_spaceship__scalartype.c++20.output

@@ -0,0 +1,4 @@
+false <=> true := less
+17 <=> 17.000000 := equivalent
+17 <=> nan := unordered
+"17" <=> 17 := greater

docs/examples/value__keytype.c++17.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