From ce139af67a94e9fea0c708ef6c5b091030cbf435 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Thu, 4 Aug 2022 23:46:17 +0200 Subject: [PATCH] :memo: add more missing examples --- .../from_json__default_constructible.cpp | 37 +++++++++++++ .../from_json__default_constructible.output | 1 + .../from_json__non_default_constructible.cpp | 53 +++++++++++++++++++ ...rom_json__non_default_constructible.output | 1 + docs/examples/to_json.cpp | 32 +++++++++++ docs/examples/to_json.output | 1 + .../docs/api/adl_serializer/from_json.md | 40 ++++++++++++-- .../mkdocs/docs/api/adl_serializer/to_json.md | 21 +++++++- .../docs/api/basic_json/json_serializer.md | 17 ++++++ docs/mkdocs/docs/features/arbitrary_types.md | 2 +- 10 files changed, 198 insertions(+), 7 deletions(-) create mode 100644 docs/examples/from_json__default_constructible.cpp create mode 100644 docs/examples/from_json__default_constructible.output create mode 100644 docs/examples/from_json__non_default_constructible.cpp create mode 100644 docs/examples/from_json__non_default_constructible.output create mode 100644 docs/examples/to_json.cpp create mode 100644 docs/examples/to_json.output diff --git a/docs/examples/from_json__default_constructible.cpp b/docs/examples/from_json__default_constructible.cpp new file mode 100644 index 000000000..17c0551c8 --- /dev/null +++ b/docs/examples/from_json__default_constructible.cpp @@ -0,0 +1,37 @@ +#include +#include + +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(); + + std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl; +} diff --git a/docs/examples/from_json__default_constructible.output b/docs/examples/from_json__default_constructible.output new file mode 100644 index 000000000..b92452326 --- /dev/null +++ b/docs/examples/from_json__default_constructible.output @@ -0,0 +1 @@ +Ned Flanders (60) lives in 744 Evergreen Terrace diff --git a/docs/examples/from_json__non_default_constructible.cpp b/docs/examples/from_json__non_default_constructible.cpp new file mode 100644 index 000000000..6cb86153c --- /dev/null +++ b/docs/examples/from_json__non_default_constructible.cpp @@ -0,0 +1,53 @@ +#include +#include + +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 +{ + 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(); + + std::cout << p.name << " (" << p.age << ") lives in " << p.address << std::endl; +} diff --git a/docs/examples/from_json__non_default_constructible.output b/docs/examples/from_json__non_default_constructible.output new file mode 100644 index 000000000..b92452326 --- /dev/null +++ b/docs/examples/from_json__non_default_constructible.output @@ -0,0 +1 @@ +Ned Flanders (60) lives in 744 Evergreen Terrace diff --git a/docs/examples/to_json.cpp b/docs/examples/to_json.cpp new file mode 100644 index 000000000..1f82a4de4 --- /dev/null +++ b/docs/examples/to_json.cpp @@ -0,0 +1,32 @@ +#include +#include + +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; +} diff --git a/docs/examples/to_json.output b/docs/examples/to_json.output new file mode 100644 index 000000000..e9c5bf381 --- /dev/null +++ b/docs/examples/to_json.output @@ -0,0 +1 @@ +{"address":"744 Evergreen Terrace","age":60,"name":"Ned Flanders"} diff --git a/docs/mkdocs/docs/api/adl_serializer/from_json.md b/docs/mkdocs/docs/api/adl_serializer/from_json.md index 7657855a3..3cd34963a 100644 --- a/docs/mkdocs/docs/api/adl_serializer/from_json.md +++ b/docs/mkdocs/docs/api/adl_serializer/from_json.md @@ -14,8 +14,8 @@ noexcept(::nlohmann::from_json(std::forward(j), detail::identity_ -> decltype(::nlohmann::from_json(std::forward(j), detail::identity_tag {})) ``` -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()` 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 diff --git a/docs/mkdocs/docs/api/adl_serializer/to_json.md b/docs/mkdocs/docs/api/adl_serializer/to_json.md index d39f72525..f8419bd81 100644 --- a/docs/mkdocs/docs/api/adl_serializer/to_json.md +++ b/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 +## Examples - This documentation page is a stub. +??? 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 diff --git a/docs/mkdocs/docs/api/basic_json/json_serializer.md b/docs/mkdocs/docs/api/basic_json/json_serializer.md index f09115567..b8b67c5cc 100644 --- a/docs/mkdocs/docs/api/basic_json/json_serializer.md +++ b/docs/mkdocs/docs/api/basic_json/json_serializer.md @@ -19,6 +19,23 @@ using json_serializer = JSONSerializer; 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. diff --git a/docs/mkdocs/docs/features/arbitrary_types.md b/docs/mkdocs/docs/features/arbitrary_types.md index 2d2e6f28b..046a597a3 100644 --- a/docs/mkdocs/docs/features/arbitrary_types.md +++ b/docs/mkdocs/docs/features/arbitrary_types.md @@ -10,7 +10,7 @@ namespace ns { std::string address; int age; }; -} +} // namespace ns ns::person p = {"Ned Flanders", "744 Evergreen Terrace", 60};