From fb5c20134f55add4315ffcc4533632a4d3525be0 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sun, 16 Aug 2020 14:27:26 +0200 Subject: [PATCH] :memo: add more API documentation --- doc/docset/docSet.sql | 3 + doc/mkdocs/docs/api/adl_serializer.md | 31 ++++++++++ doc/mkdocs/docs/api/basic_json/get.md | 5 +- doc/mkdocs/docs/api/basic_json/get_ptr.md | 5 +- doc/mkdocs/docs/api/basic_json/get_ref.md | 2 +- doc/mkdocs/docs/api/basic_json/get_to.md | 58 +++++++++++++++++++ doc/mkdocs/docs/api/basic_json/index.md | 13 +++-- .../docs/api/basic_json/json_serializer.md | 24 ++++++++ doc/mkdocs/mkdocs.yml | 3 + 9 files changed, 133 insertions(+), 11 deletions(-) create mode 100644 doc/mkdocs/docs/api/adl_serializer.md create mode 100644 doc/mkdocs/docs/api/basic_json/get_to.md create mode 100644 doc/mkdocs/docs/api/basic_json/json_serializer.md diff --git a/doc/docset/docSet.sql b/doc/docset/docSet.sql index e350bafff..b48394099 100644 --- a/doc/docset/docSet.sql +++ b/doc/docset/docSet.sql @@ -4,6 +4,7 @@ CREATE UNIQUE INDEX anchor ON searchIndex (name, type, path); -- API INSERT INTO searchIndex(name, type, path) VALUES ('accept', 'Function', 'api/basic_json/accept/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('adl_serializer', 'Class', 'api/adl_serializer/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('array', 'Function', 'api/basic_json/array/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('array_t', 'Type', 'api/basic_json/array_t/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('at', 'Method', 'api/basic_json/at/index.html'); @@ -43,6 +44,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('get_allocator', 'Function', ' INSERT INTO searchIndex(name, type, path) VALUES ('get_binary', 'Method', 'api/basic_json/get_binary/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('get_ptr', 'Method', 'api/basic_json/get_ptr/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('get_ref', 'Method', 'api/basic_json/get_ref/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('get_to', 'Method', 'api/basic_json/get_to/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'); INSERT INTO searchIndex(name, type, path) VALUES ('invalid_iterator', 'Class', 'api/basic_json/invalid_iterator/index.html'); @@ -62,6 +64,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('is_structured', 'Method', 'ap INSERT INTO searchIndex(name, type, path) VALUES ('items', 'Method', 'api/basic_json/items/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('json', 'Class', 'api/json/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('json_pointer', 'Class', 'api/json_pointer/index.html'); +INSERT INTO searchIndex(name, type, path) VALUES ('json_serializer', 'Type', 'api/basic_json/json_serializer/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('max_size', 'Method', 'api/basic_json/max_size/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('merge_patch', 'Method', 'api/basic_json/merge_patch/index.html'); INSERT INTO searchIndex(name, type, path) VALUES ('meta', 'Function', 'api/basic_json/meta/index.html'); diff --git a/doc/mkdocs/docs/api/adl_serializer.md b/doc/mkdocs/docs/api/adl_serializer.md new file mode 100644 index 000000000..7b79747f5 --- /dev/null +++ b/doc/mkdocs/docs/api/adl_serializer.md @@ -0,0 +1,31 @@ +# adl_serializer + +```cpp +template +struct adl_serializer; +``` + +Serializer that uses ADL ([Argument-Dependent Lookup](https://en.cppreference.com/w/cpp/language/adl)) to choose +`to_json`/`from_json` functions from the types' namespaces. + +It is implemented similar to + +```cpp +template +struct adl_serializer { + template + static void to_json(BasicJsonType& j, const T& value) { + // calls the "to_json" method in T's namespace + } + + template + static void from_json(const BasicJsonType& j, T& value) { + // same thing, but with the "from_json" method + } +}; +``` + +## Member functions + +- **from_json** - convert a JSON value to any value type +- **to_json** - convert any value type to a JSON value diff --git a/doc/mkdocs/docs/api/basic_json/get.md b/doc/mkdocs/docs/api/basic_json/get.md index 4b1703706..6cd663056 100644 --- a/doc/mkdocs/docs/api/basic_json/get.md +++ b/doc/mkdocs/docs/api/basic_json/get.md @@ -73,8 +73,9 @@ constexpr const PointerType get_ptr() const noexcept; `PointerType` : pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md), - [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or [`number_unsigned`](number_unsigned.md), - [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). Other types will not compile. + [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or + [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). + Other types will not compile. ## Return value diff --git a/doc/mkdocs/docs/api/basic_json/get_ptr.md b/doc/mkdocs/docs/api/basic_json/get_ptr.md index 80c2a19f3..c5cee307a 100644 --- a/doc/mkdocs/docs/api/basic_json/get_ptr.md +++ b/doc/mkdocs/docs/api/basic_json/get_ptr.md @@ -14,8 +14,9 @@ Implicit pointer access to the internally stored JSON value. No copies are made. `PointerType` : pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md), - [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or [`number_unsigned`](number_unsigned.md), - [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). Other types will not compile. + [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or + [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). + Other types will not compile. ## Return value diff --git a/doc/mkdocs/docs/api/basic_json/get_ref.md b/doc/mkdocs/docs/api/basic_json/get_ref.md index 13b8e0f21..102aff1ef 100644 --- a/doc/mkdocs/docs/api/basic_json/get_ref.md +++ b/doc/mkdocs/docs/api/basic_json/get_ref.md @@ -15,7 +15,7 @@ Implicit reference access to the internally stored JSON value. No copies are mad `ReferenceType` : reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md), [`boolean_t`](boolean_t.md), [`number_integer_t`](number_integer_t.md), or - [`number_unsigned`](number_unsigned.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). + [`number_unsigned_t`](number_unsigned_t.md), [`number_float_t`](number_float_t.md), or [`binary_t`](binary_t.md). Enforced by static assertion. ## Return value diff --git a/doc/mkdocs/docs/api/basic_json/get_to.md b/doc/mkdocs/docs/api/basic_json/get_to.md new file mode 100644 index 000000000..4a4395bc8 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/get_to.md @@ -0,0 +1,58 @@ +# basic_json::get_to + +```cpp +template +ValueType& get_to(ValueType& v) const noexcept( + noexcept(JSONSerializer::from_json( + std::declval(), v))) +``` + +Explicit type conversion between the JSON value and a compatible value. The value is filled into the input parameter by +calling the `json_serializer` `from_json()` method. + +The function is equivalent to executing +```cpp +ValueType v; +JSONSerializer::from_json(*this, v); +``` + +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&)` + +## Template parameters + +`ValueType` +: the value type to return + +## Return value + +the input parameter, allowing chaining calls + +## 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 + `#!cpp std::vector`, (3) A JSON object can be converted to C++ associative containers such as + `#cpp std::unordered_map`. + + ```cpp + --8<-- "examples/get_to.cpp" + ``` + + Output: + + ```json + --8<-- "examples/get_to.output" + ``` + +## Version history + +- Since version 3.3.0. diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 29989f2cb..cdc7f9452 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -33,14 +33,14 @@ class basic_json; | -------------------- | ----------- | ------------ | | `ObjectType` | type for JSON objects | [`object_t`](object_t.md) | | `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) | -| `StringType` | type for JSON strings and object keys | `string_t` | -| `BooleanType` | type for JSON booleans | `boolean_t` | +| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) | +| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) | | `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) | | `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) | | `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) | | `AllocatorType` | type of the allocator to use | | -| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | | -| `BinaryType` | type for binary arrays | `binary_t` | +| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) | +| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) | ## Iterator invalidation @@ -48,9 +48,10 @@ Todo ## Member types +- [**adl_serializer**](../adl_serializer.md) - the default serializer - [**value_t**](value_t.md) - the JSON type enumeration - [**json_pointer**](../json_pointer.md) - JSON Pointer implementation -- json_serializer +- [**json_serializer**](json_serializer.md) - type of the serializer to for conversions from/to JSON - [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors - [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags - initializer_list_t @@ -136,7 +137,7 @@ Functions to inspect the type of a JSON value. Direct access to the stored value of a JSON value. - [**get**](get.md) - get a value -- get_to - get a value +- [**get_to**](get_to.md) - get a value and write it to a destination - [**get_ptr**](get_ptr.md) - get a pointer value - [**get_ref**](get_ref.md) - get a reference value - [**operator ValueType**](operator_ValueType.md) - get a value diff --git a/doc/mkdocs/docs/api/basic_json/json_serializer.md b/doc/mkdocs/docs/api/basic_json/json_serializer.md new file mode 100644 index 000000000..89379acf4 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/json_serializer.md @@ -0,0 +1,24 @@ +# basic_json::json_serializer + +```cpp +template +using json_serializer = JSONSerializer; +``` + +## Template parameters + +`T` +: type to convert; will be used in the `to_json`/`from_json` functions + +`SFINAE` +: type to add compile type checks via SFINAE; usually `#!cpp void` + +## Notes + +#### Default type + +The default values for `json_serializer` is [`adl_serializer`](../adl_serializer.md). + +## Version history + +- Since version 2.0.0. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index a1c4b1ebd..3310bd704 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -112,6 +112,7 @@ nav: - api/basic_json/get_binary.md - api/basic_json/get_ptr.md - api/basic_json/get_ref.md + - api/basic_json/get_to.md - api/basic_json/input_format_t.md - api/basic_json/insert.md - api/basic_json/invalid_iterator.md @@ -129,6 +130,7 @@ nav: - api/basic_json/is_string.md - api/basic_json/is_structured.md - api/basic_json/items.md + - api/basic_json/json_serializer.md - api/basic_json/max_size.md - api/basic_json/meta.md - api/basic_json/merge_patch.md @@ -171,6 +173,7 @@ nav: - api/basic_json/update.md - api/basic_json/value.md - api/basic_json/value_t.md + - api/adl_serializer.md - api/json.md - api/json_pointer.md - api/ordered_map.md