mirror/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2024-11-28 00:59:02 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

📝 add more API documentation

Browse Source
This commit is contained in:
Niels Lohmann 2020-08-16 14:27:26 +02:00
parent d8ed98a7af
commit fb5c20134f
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
9 changed files with 133 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

3
doc/docset/docSet.sql
View File

@ -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');

31
doc/mkdocs/docs/api/adl_serializer.md Normal file
View File

@ -0,0 +1,31 @@
# adl_serializer
```cpp
template<typename, typename>
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<typename ValueType>
struct adl_serializer {
template<typename BasicJsonType>
static void to_json(BasicJsonType& j, const T& value) {
// calls the "to_json" method in T's namespace
}
template<typename BasicJsonType>
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

5
doc/mkdocs/docs/api/basic_json/get.md
View File

@ -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

5
doc/mkdocs/docs/api/basic_json/get_ptr.md
View File

@ -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

2
doc/mkdocs/docs/api/basic_json/get_ref.md
View File

@ -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

58
doc/mkdocs/docs/api/basic_json/get_to.md Normal file
View File

@ -0,0 +1,58 @@
# basic_json::get_to
```cpp
template<typename ValueType>
ValueType& get_to(ValueType& v) const noexcept(
noexcept(JSONSerializer<ValueType>::from_json(
std::declval<const basic_json_t&>(), 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<ValueType>` `from_json()` method.
The function is equivalent to executing
```cpp
ValueType v;
JSONSerializer<ValueType>::from_json(*this, v);
```
This overloads is chosen if:
- `ValueType` is not `basic_json`,
- `json_serializer<ValueType>` 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<ValueType>` `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<short>`, (3) A JSON object can be converted to C++ associative containers such as
`#cpp std::unordered_map<std::string, json>`.
```cpp
--8<-- "examples/get_to.cpp"
```
Output:
```json
--8<-- "examples/get_to.output"
```
## Version history
- Since version 3.3.0.

13
doc/mkdocs/docs/api/basic_json/index.md
View File

@ -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

24
doc/mkdocs/docs/api/basic_json/json_serializer.md Normal file
View File

@ -0,0 +1,24 @@
# basic_json::json_serializer
```cpp
template<typename T, typename SFINAE>
using json_serializer = JSONSerializer<T, SFINAE>;
```
## 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.

3
doc/mkdocs/mkdocs.yml
View File

@ -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