From f6c2947f1ef63d051a767394682dd7854417394d Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Fri, 14 Aug 2020 13:47:54 +0200 Subject: [PATCH] :memo: add more API documentation --- doc/docset/docSet.sql | 9 ++- doc/mkdocs/docs/api/basic_json/get.md | 97 +++++++++++++++++++++++++ doc/mkdocs/docs/api/basic_json/index.md | 2 +- doc/mkdocs/mkdocs.yml | 1 + 4 files changed, 104 insertions(+), 5 deletions(-) create mode 100644 doc/mkdocs/docs/api/basic_json/get.md diff --git a/doc/docset/docSet.sql b/doc/docset/docSet.sql index 47d893e98..0c3233510 100644 --- a/doc/docset/docSet.sql +++ b/doc/docset/docSet.sql @@ -32,7 +32,12 @@ INSERT INTO searchIndex(name, type, path) VALUES ('error_handler_t', 'Enum', 'ap INSERT INTO searchIndex(name, type, path) VALUES ('exception', 'Class', 'api/basic_json/exception/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('find', 'Method', 'api/basic_json/find/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('flatten', 'Method', 'api/basic_json/flatten/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('from_bson', 'Function', 'api/basic_json/from_bson/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('from_cbor', 'Function', 'api/basic_json/from_cbor/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('from_msgpack', 'Function', 'api/basic_json/from_msgpack/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('from_ubjson', 'Function', 'api/basic_json/from_ubjson/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('front', 'Method', 'api/basic_json/front/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('get', 'Method', 'api/basic_json/get/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('get_allocator', 'Function', 'api/basic_json/get_allocator/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('input_format_t', 'Enum', 'api/basic_json/input_format_t/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('insert', 'Method', 'api/basic_json/insert/index.html'); @@ -89,10 +94,6 @@ INSERT INTO searchIndex(name, type, path) VALUES ('type_error', 'Class', 'api/ba INSERT INTO searchIndex(name, type, path) VALUES ('type_name', 'Method', 'api/basic_json/type_name/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('unflatten', 'Method', 'api/basic_json/unflatten/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('update', 'Method', 'api/basic_json/update/index.html'); -INSERT INTO searchIndex(name, type, path) VALUES ('from_bson', 'Function', 'api/basic_json/from_bson/index.html'); -INSERT INTO searchIndex(name, type, path) VALUES ('from_cbor', 'Function', 'api/basic_json/from_cbor/index.html'); -INSERT INTO searchIndex(name, type, path) VALUES ('from_msgpack', 'Function', 'api/basic_json/from_msgpack/index.html'); -INSERT INTO searchIndex(name, type, path) VALUES ('from_ubjson', 'Function', 'api/basic_json/from_ubjson/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('to_bson', 'Function', 'api/basic_json/to_bson/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('to_cbor', 'Function', 'api/basic_json/to_cbor/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('to_msgpack', 'Function', 'api/basic_json/to_msgpack/index.html'); diff --git a/doc/mkdocs/docs/api/basic_json/get.md b/doc/mkdocs/docs/api/basic_json/get.md new file mode 100644 index 000000000..71541095b --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/get.md @@ -0,0 +1,97 @@ +# basic_json::get + +```cpp +// (1) +template +ValueType get() const noexcept( + noexcept(JSONSerializer::from_json( + std::declval(), std::declval()))); + +// (2) +template +BasicJsonType get() const; +``` + +1. Explicit type conversion between the JSON value and a compatible value which is + [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible) and + [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible). The value is converted by + calling the `json_serializer` `from_json()` method. + + The function is equivalent to executing + ```cpp + ValueType ret; + JSONSerializer::from_json(*this, ret); + return ret; + ``` + + This overloads is chosen if: + + - `ValueType` is not `basic_json`, + - `json_serializer` has a `from_json()` method of the form + `void from_json(const basic_json&, ValueType&)`, and + - `json_serializer` does not have a `from_json()` method of the form + `ValueType from_json(const basic_json&)` + + If the type is **not** [CopyConstructible](https://en.cppreference.com/w/cpp/named_req/CopyConstructible) and + **not** [DefaultConstructible](https://en.cppreference.com/w/cpp/named_req/DefaultConstructible), the value is + converted by calling the `json_serializer` `from_json()` method. + + The function is then equivalent to executing + ```cpp + return JSONSerializer::from_json(*this); + ``` + + This overloads is chosen if: + + - `ValueType` is not `basic_json` and + - `json_serializer` has a `from_json()` method of the form + `ValueType from_json(const basic_json&)` + + If `json_serializer` has both overloads of `from_json()`, the latter one is chosen. + +2. Overload for `basic_json` specializations. The function is equivalent to executing + ```cpp + return *this; + ``` + +## Template parameters + +`ValueType` +: the value type to return + +`BasicJsonType` +: a specialization of `basic_json` + +## Return value + +1. copy of the JSON value, converted to `ValueType` +2. a copy of `#!cpp *this`, converted into `BasicJsonType` + +## Exceptions + +Depends on what `json_serializer` `from_json()` method throws + +## Example + +??? example + + The example below shows several conversions from JSON values + to other types. There a few things to note: (1) Floating-point numbers can + be converted to integers, (2) A JSON array can be converted to a standard + `std::vector`, (3) A JSON object can be converted to C++ + associative containers such as `std::unordered_map`. + + ```cpp + --8<-- "examples/get__ValueType_const.cpp" + ``` + + Output: + + ```json + --8<-- "examples/get__ValueType_const.output" + ``` + +## Version history + +1. Since version 2.1.0. +2. Since version 2.1.0. Extended to work with other specializations of `basic_json` in version 3.2.0. diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 55851ab33..582517709 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -135,7 +135,7 @@ Functions to inspect the type of a JSON value. Direct access to the stored value of a JSON value. -- get - get a value +- [**get**](get.md) - get a value - get_to - get a value - get_ptr - get a pointer value - get_ref - get a reference value diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 115bfbde5..caeb812af 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -106,6 +106,7 @@ nav: - api/basic_json/from_msgpack.md - api/basic_json/from_ubjson.md - api/basic_json/front.md + - api/basic_json/get.md - api/basic_json/get_allocator.md - api/basic_json/input_format_t.md - api/basic_json/insert.md