Documentation change

docs/examples/from_json__default_constructible.cpp

@@ -0,0 +1,37 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+// a simple struct to model a person
+struct person
+{
+    std::string name;
+    std::string address;
+    int age;
+};
+} // namespace ns
+
+namespace ns
+{
+void from_json(const json& j, person& p)
+{
+    j.at("name").get_to(p.name);
+    j.at("address").get_to(p.address);
+    j.at("age").get_to(p.age);
+}
+} // namespace ns
+
+int main()
+{
+    json j;
+    j["name"] = "Ned Flanders";
+    j["address"] = "744 Evergreen Terrace";
+    j["age"] = 60;
+
+    auto p = j.get<ns::person>();
+
+    std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
+}

docs/examples/from_json__default_constructible.output

@@ -0,0 +1 @@
+Ned Flanders (60) lives in 744 Evergreen Terrace

docs/examples/from_json__non_default_constructible.cpp

@@ -0,0 +1,53 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+// a simple struct to model a person (not default constructible)
+struct person
+{
+    person(std::string n, std::string a, int aa)
+        : name(std::move(n)), address(std::move(a)), age(aa)
+    {}
+
+    std::string name;
+    std::string address;
+    int age;
+};
+} // namespace ns
+
+namespace nlohmann
+{
+template <>
+struct adl_serializer<ns::person>
+{
+    static ns::person from_json(const json& j)
+    {
+        return {j.at("name"), j.at("address"), j.at("age")};
+    }
+
+    // Here's the catch! You must provide a to_json method! Otherwise, you
+    // will not be able to convert person to json, since you fully
+    // specialized adl_serializer on that type
+    static void to_json(json& j, ns::person p)
+    {
+        j["name"] = p.name;
+        j["address"] = p.address;
+        j["age"] = p.age;
+    }
+};
+} // namespace nlohmann
+
+int main()
+{
+    json j;
+    j["name"] = "Ned Flanders";
+    j["address"] = "744 Evergreen Terrace";
+    j["age"] = 60;
+
+    auto p = j.get<ns::person>();
+
+    std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl;
+}

docs/examples/from_json__non_default_constructible.output

@@ -0,0 +1 @@
+Ned Flanders (60) lives in 744 Evergreen Terrace

docs/examples/nlohmann_json_namespace.cpp

@@ -0,0 +1,14 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+// possible use case: use NLOHMANN_JSON_NAMESPACE instead of nlohmann
+using json = NLOHMANN_JSON_NAMESPACE::json;
+
+// macro needed to output the NLOHMANN_JSON_NAMESPACE as string literal
+#define Q(x) #x
+#define QUOTE(x) Q(x)
+
+int main()
+{
+    std::cout << QUOTE(NLOHMANN_JSON_NAMESPACE) << std::endl;
+}

docs/examples/nlohmann_json_namespace.output

@@ -0,0 +1 @@
+nlohmann::json_v3_11_1

docs/examples/nlohmann_json_namespace_begin.c++17.cpp

@@ -0,0 +1,33 @@
+#include <iostream>
+#include <optional>
+#include <nlohmann/json.hpp>
+
+// partial specialization (see https://json.nlohmann.me/features/arbitrary_types/)
+NLOHMANN_JSON_NAMESPACE_BEGIN
+template <typename T>
+struct adl_serializer<std::optional<T>>
+{
+    static void to_json(json& j, const std::optional<T>& opt)
+    {
+        if (opt == std::nullopt)
+        {
+            j = nullptr;
+        }
+        else
+        {
+            j = *opt;
+        }
+    }
+};
+NLOHMANN_JSON_NAMESPACE_END
+
+int main()
+{
+    std::optional<int> o1 = 1;
+    std::optional<int> o2 = std::nullopt;
+
+    NLOHMANN_JSON_NAMESPACE::json j;
+    j.push_back(o1);
+    j.push_back(o2);
+    std::cout << j << std::endl;
+}

docs/examples/nlohmann_json_namespace_begin.c++17.output

@@ -0,0 +1 @@
+[1,null]

docs/examples/to_json.cpp

@@ -0,0 +1,32 @@
+#include <iostream>
+#include <nlohmann/json.hpp>
+
+using json = nlohmann::json;
+
+namespace ns
+{
+// a simple struct to model a person
+struct person
+{
+    std::string name;
+    std::string address;
+    int age;
+};
+} // namespace ns
+
+namespace ns
+{
+void to_json(json& j, const person& p)
+{
+    j = json{ {"name", p.name}, {"address", p.address}, {"age", p.age} };
+}
+} // namespace ns
+
+int main()
+{
+    ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};
+
+    json j = p;
+
+    std::cout << j << std::endl;
+}

docs/examples/to_json.output

@@ -0,0 +1 @@
+{"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"}

docs/mkdocs/docs/api/adl_serializer/from_json.md

@@ -14,8 +14,8 @@ noexcept(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_
 -> decltype(::nlohmann::from_json(std::forward<BasicJsonType>(j), detail::identity_tag<TargetType> {}))
 ```
 
-This function is usually called by the [`get()`](../basic_json/get.md) function of the
-[basic_json](../basic_json) class (either explicit or via conversion operators).
+This function is usually called by the [`get()`](../basic_json/get.md) function of the [basic_json](../basic_json)
+class (either explicit or via conversion operators).
 
 1. This function is chosen for default-constructible value types.
 2. This function is chosen for value types which are not default-constructible.
@@ -32,9 +32,41 @@ This function is usually called by the [`get()`](../basic_json/get.md) function
 
 Copy of the JSON value, converted to `ValueType`
 
-!!! note
+## Examples
 
-    This documentation page is a stub.
+??? example "Example: (1) Default-constructible type"
+
+    The example below shows how a `from_json` function can be implemented for a user-defined type. This function is
+    called by the `adl_serializer` when `get<ns::person>()` is called.
+
+    ```cpp
+    --8<-- "examples/from_json__default_constructible.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/from_json__default_constructible.output"
+    ```
+
+??? example "Example: (2) Non-default-constructible type"
+
+    The example below shows how a `from_json` is implemented as part of a specialization of the `adl_serializer` to
+    realize the conversion of a non-default-constructible type.
+
+    ```cpp
+    --8<-- "examples/from_json__non_default_constructible.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/from_json__non_default_constructible.output"
+    ```
+
+## See also
+
+- [to_json](to_json.md)
 
 ## Version history
 

docs/mkdocs/docs/api/adl_serializer/to_json.md

@@ -17,9 +17,26 @@ This function is usually called by the constructors of the [basic_json](../basic
 `val` (in)
 :   value to read from
 
-!!! note
-
-    This documentation page is a stub.
+## Examples
+
+??? example
+
+    The example below shows how a `to_json` function can be implemented for a user-defined type. This function is called
+    by the `adl_serializer` when the constructor `basic_json(ns::person)` is called.
+
+    ```cpp
+    --8<-- "examples/to_json.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/to_json.output"
+    ```
+
+## See also
+
+- [from_json](from_json.md)
 
 ## Version history
 

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

@@ -6,8 +6,8 @@ using boolean_t = BooleanType;
 
 The type used to store JSON booleans.
 
-[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two literals
-`#!json true` and `#!json false`.
+[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two
+literals`#!json true` and `#!json false`.
 
 To store objects in C++, a type is defined by the template parameter  `BooleanType` which chooses the type to use.
 

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

@@ -19,6 +19,23 @@ using json_serializer = JSONSerializer<T, SFINAE>;
 
 The default values for `json_serializer` is [`adl_serializer`](../adl_serializer).
 
+## Examples
+
+??? example
+
+    The example below shows how a conversion of a non-default-constructible type is implemented via a specialization of
+    the `adl_serializer`.
+
+    ```cpp
+    --8<-- "examples/from_json__non_default_constructible.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/from_json__non_default_constructible.output"
+    ```
+
 ## Version history
 
 - Since version 2.0.0.

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

@@ -28,4 +28,5 @@ and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise.
 ## Version history
 
 - Added in version 3.0.0.
-- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in version 3.11.0.
+- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in
+  version 3.11.0.

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

@@ -90,7 +90,8 @@ Objects are stored as pointers in a `basic_json` type. That is, for any access t
 The order name/value pairs are added to the object is *not* preserved by the library. Therefore, iterating an object may
 return name/value pairs in a different order than they were originally stored. In fact, keys will be traversed in
 alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to
-[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON objects.
+[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON
+objects.
 
 ## Examples
 

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

@@ -21,7 +21,8 @@ const_reference operator[](const json_pointer& ptr) const;
 ```
 
 1. Returns a reference to the array element at specified location `idx`.
-2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by value.
+2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by
+   value.
 3. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and
    `#!cpp typename object_comparator_t::is_transparent` denotes a type.
 4. Returns a reference to the element with specified JSON pointer `ptr`.
@@ -234,6 +235,7 @@ Strong exception safety: if an exception occurs, the original value stays intact
 ## Version history
 
 1. Added in version 1.0.0.
-2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) in version 3.11.0.
+2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3)
+   in version 3.11.0.
 3. Added in version 3.11.0.
 4. Added in version 2.0.0.

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

@@ -20,8 +20,8 @@ class basic_json {
 ```
 
 1. Compares two JSON values for equality according to the following rules:
-    - Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same
-      type and their stored values are the same according to their respective `operator==`.
+    - Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same type and their stored
+      values are the same according to their respective `operator==`.
     - Integer and floating-point numbers are automatically converted before comparison.
 
 2. Compares a JSON value and a scalar or a scalar and a JSON value for equality by converting the

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

@@ -11,15 +11,14 @@ template<typename ScalarType>
 bool operator>=(ScalarType lhs, const const_reference rhs) noexcept;  // (2)
 ```
 
-1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs`
-   according to the following rules:
-    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
-      operand is `NaN` and the other operand is either `NaN` or any other number.
+1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs` according to the following
+   rules:
+    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either operand is `NaN` and
+      the other operand is either `NaN` or any other number.
     - Otherwise, returns the result of `#!cpp !(lhs < rhs)` (see [**operator<**](operator_lt.md)).
 
-2. Compares wether a JSON value is greater than or equal to a scalar or a scalar is greater than or
-   equal to a JSON value by converting the scalar to a JSON value and comparing both JSON values
-   according to 1.
+2. Compares whether a JSON value is greater than or equal to a scalar or a scalar is greater than or equal to a JSON
+   value by converting the scalar to a JSON value and comparing both JSON values according to 1.
 
 ## Template parameters
 

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

@@ -20,13 +20,12 @@ class basic_json {
 ```
 
 1. Compares two JSON values for inequality according to the following rules:
-    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either
-      operand is `NaN` and the other operand is either `NaN` or any other number.
-    - Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or
-      `#!cpp !(*this == rhs)` (since C++20).
+    - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either operand is `NaN` and
+      the other operand is either `NaN` or any other number.
+    - Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or `#!cpp !(*this == rhs)` (since C++20).
 
-2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the
-   scalar to a JSON value and comparing both JSON values according to 1.
+2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the scalar to a JSON
+   value and comparing both JSON values according to 1.
 
 ## Template parameters