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-15 15:18:07 +02:00
parent 1ce0ed5a52
commit d8ed98a7af
No known key found for this signature in database
GPG Key ID: 7F3CEA63AE251B69
12 changed files with 396 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
doc/docset/docSet.sql
View File

@ -12,6 +12,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Class', 'api/ba
INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Constructor', 'api/basic_json/basic_json/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('begin', 'Method', 'api/basic_json/begin/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('binary', 'Function', 'api/basic_json/binary/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('binary_t', 'Type', 'api/basic_json/binary_t/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('boolean_t', 'Type', 'api/basic_json/boolean_t/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('cbegin', 'Method', 'api/basic_json/cbegin/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('cbor_tag_handler_t', 'Enum', 'api/basic_json/cbor_tag_handler_t/index.html');
@ -39,6 +40,9 @@ INSERT INTO searchIndex(name, type, path) VALUES ('from_ubjson', 'Function', 'ap
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 ('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 ('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');
@ -65,6 +69,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('number_float_t', 'Type', 'api
INSERT INTO searchIndex(name, type, path) VALUES ('number_integer_t', 'Type', 'api/basic_json/number_integer_t/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('number_unsigned_t', 'Type', 'api/basic_json/number_unsigned_t/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('object', 'Function', 'api/basic_json/object/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('object_comparator_t', 'Type', 'api/basic_json/object_comparator_t/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('object_t', 'Type', 'api/basic_json/object_t/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('operator!=', 'Operator', 'api/basic_json/operator!=/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('operator+=', 'Operator', 'api/basic_json/operator+=/index.html');
@ -73,6 +78,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('operator==', 'Operator', 'api
INSERT INTO searchIndex(name, type, path) VALUES ('operator[]', 'Operator', 'api/basic_json/operator[]/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json', 'Literal', 'api/basic_json/operator_literal_json/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('operator""_json_pointer', 'Literal', 'api/basic_json/operator_literal_json_pointer/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('operator ValueType', 'Operator', 'api/basic_json/operator_ValueType/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('operator value_t', 'Operator', 'api/basic_json/operator_value_t/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('ordered_json', 'Class', 'api/ordered_json/index.html');
INSERT INTO searchIndex(name, type, path) VALUES ('ordered_map', 'Class', 'api/ordered_map/index.html');

67
doc/mkdocs/docs/api/basic_json/binary_t.md Normal file
View File

@ -0,0 +1,67 @@
# basic_json::binary_t
```cpp
using binary_t = byte_container_with_subtype<BinaryType>;
```
This type is a type designed to carry binary data that appears in various serialized formats, such as CBOR's Major Type
2, MessagePack's bin, and BSON's generic binary subtype. This type is NOT a part of standard JSON and exists solely for
compatibility with these binary types. As such, it is simply defined as an ordered sequence of zero or more byte values.
Additionally, as an implementation detail, the subtype of the binary data is carried around as a `std::uint8_t`, which
is compatible with both of the binary data formats that use binary subtyping, (though the specific numbering is
incompatible with each other, and it is up to the user to translate between them).
[CBOR's RFC 7049](https://tools.ietf.org/html/rfc7049) describes this type as:
> Major type 2: a byte string. The string's length in bytes is represented following the rules for positive integers
> (major type 0).
[MessagePack's documentation on the bin type
family](https://github.com/msgpack/msgpack/blob/master/spec.md#bin-format-family) describes this type as:
> Bin format family stores an byte array in 2, 3, or 5 bytes of extra bytes in addition to the size of the byte array.
[BSON's specifications](http://bsonspec.org/spec.html) describe several binary types; however, this type is intended to
represent the generic binary type which has the description:
> Generic binary subtype - This is the most commonly used binary subtype and should be the 'default' for drivers and
> tools.
None of these impose any limitations on the internal representation other than the basic unit of storage be some type of
array whose parts are decomposable into bytes.
The default representation of this binary format is a `#!cpp std::vector<std::uint8_t>`, which is a very common way to
represent a byte array in modern C++.
## Template parameters
`BinaryType`
: container type to store arrays
## Notes
#### Default type
The default values for `BinaryType` is `#!cpp std::vector<std::uint8_t>`.
#### Storage
Binary Arrays are stored as pointers in a `basic_json` type. That is, for any access to array values, a pointer of the
type `#!cpp binary_t*` must be dereferenced.
#### Notes on subtypes
- CBOR
- Binary values are represented as byte strings. Subtypes are written as tags.
- MessagePack
- If a subtype is given and the binary array contains exactly 1, 2, 4, 8, or 16 elements, the fixext family (fixext1,
fixext2, fixext4, fixext8) is used. For other sizes, the ext family (ext8, ext16, ext32) is used. The subtype is
then added as singed 8-bit integer.
- If no subtype is given, the bin family (bin8, bin16, bin32) is used.
- BSON
- If a subtype is given, it is used and added as unsigned 8-bit integer.
- If no subtype is given, the generic binary subtype 0x00 is used.
## Version history
- Added in version 3.8.0.

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

@ -10,6 +10,13 @@ ValueType get() const noexcept(
// (2)
template<typename BasicJsonType>
BasicJsonType get() const;
// (3)
template<typename PointerType>
PointerType get_ptr();
template<typename PointerType>
constexpr const PointerType get_ptr() const noexcept;
```
1. Explicit type conversion between the JSON value and a compatible value which is
@ -52,7 +59,9 @@ BasicJsonType get() const;
2. Overload for `basic_json` specializations. The function is equivalent to executing
```cpp
return *this;
```
```
3. Explicit pointer access to the internally stored JSON value. No copies are made.
## Template parameters
@ -62,15 +71,28 @@ BasicJsonType get() const;
`BasicJsonType`
: a specialization of `basic_json`
`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.
## Return value
1. copy of the JSON value, converted to `ValueType`
2. a copy of `#!cpp *this`, converted into `BasicJsonType`
3. pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `#!cpp nullptr`
otherwise
## Exceptions
Depends on what `json_serializer<ValueType>` `from_json()` method throws
## Notes
!!! warning
Writing data to the pointee (overload 3) of the result yields an undefined state.
## Example
??? example
@ -91,7 +113,23 @@ Depends on what `json_serializer<ValueType>` `from_json()` method throws
--8<-- "examples/get__ValueType_const.output"
```
??? example
The example below shows how pointers to internal values of a JSON value can be requested. Note that no type
conversions are made and a `#cpp nullptr` is returned if the value and the requested pointer type does not match.
```cpp
--8<-- "examples/get__PointerType.cpp"
```
Output:
```json
--8<-- "examples/get__PointerType.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.
3. Since version 1.0.0.

29
doc/mkdocs/docs/api/basic_json/get_binary.md Normal file
View File

@ -0,0 +1,29 @@
# basic_json::get_binary
```cpp
binary_t& get_binary();
const binary_t& get_binary() const;
```
Returns a reference to the stored binary value.
## Return value
Reference to binary value.
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if the value is not binary
## Complexity
Constant.
## Version history
- Added in version 3.8.0.

59
doc/mkdocs/docs/api/basic_json/get_ptr.md Normal file
View File

@ -0,0 +1,59 @@
# basic_json::get_ptr
```cpp
template<typename PointerType>
PointerType get_ptr();
template<typename PointerType>
constexpr const PointerType get_ptr() const noexcept;
```
Implicit pointer access to the internally stored JSON value. No copies are made.
## Template arguments
`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.
## Return value
pointer to the internally stored JSON value if the requested pointer type fits to the JSON value; `#!cpp nullptr`
otherwise
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Complexity
Constant.
## Notes
!!! warning
Writing data to the pointee of the result yields an undefined state.
## Example
??? example
The example below shows how pointers to internal values of a JSON value can be requested. Note that no type
conversions are made and a `#!cpp nullptr` is returned if the value and the requested pointer type does not match.
```cpp
--8<-- "examples/get_ptr.cpp"
```
Output:
```json
--8<-- "examples/get_ptr.output"
```
## Version history
- Added in version 1.0.0.
- Extended to binary types in version 3.8.0.

64
doc/mkdocs/docs/api/basic_json/get_ref.md Normal file
View File

@ -0,0 +1,64 @@
# basic_json::get_ref
```cpp
template<typename ReferenceType>
ReferenceType get_ref();
template<typename ReferenceType>
const ReferenceType get_ref() const;
```
Implicit reference access to the internally stored JSON value. No copies are made.
## Template arguments
`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).
Enforced by static assertion.
## Return value
reference to the internally stored JSON value if the requested reference type fits to the JSON value; throws
[`type_error.303`](../../home/exceptions.md#jsonexceptiontype_error303) otherwise
## Exception safety
Strong exception safety: if an exception occurs, the original value stays intact.
## Exceptions
Throws [`type_error.303`](../../home/exceptions.md#jsonexceptiontype_error303) if the requested reference type does not
match the stored JSON value type; example: `"incompatible ReferenceType for get_ref, actual type is binary"`.
## Complexity
Constant.
## Notes
!!! warning
Writing data to the referee of the result yields an undefined state.
## Example
??? example
The example shows several calls to `get_ref()`.
```cpp
--8<-- "examples/get_ref.cpp"
```
Output:
```json
--8<-- "examples/get_ref.output"
```
## Version history
- Added in version 1.1.0.
- Extended to binary types in version 3.8.0.

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

@ -68,33 +68,33 @@ Todo
### Container types
| Type | Definition |
| ---------------------- | ---------- |
| value_type | `#!cpp basic_json` |
| reference | `#!cpp value_type&` |
| const_reference | `#!cpp const value_type&` |
| difference_type | `#!cpp std::ptrdiff_t` |
| size_type | `#!cpp std::size_t` |
| allocator_type | `#!cpp AllocatorType<basic_json>` |
| pointer | `#!cpp std::allocator_traits<allocator_type>::pointer` |
| const_pointer | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
| iterator | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
| const_iterator | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
| reverse_iterator | |
| const_reverse_iterator | |
| iteration_proxy | |
| Type | Definition |
| ------------------------ | ---------- |
| `value_type` | `#!cpp basic_json` |
| `reference` | `#!cpp value_type&` |
| `const_reference` | `#!cpp const value_type&` |
| `difference_type` | `#!cpp std::ptrdiff_t` |
| `size_type` | `#!cpp std::size_t` |
| `allocator_type` | `#!cpp AllocatorType<basic_json>` |
| `pointer` | `#!cpp std::allocator_traits<allocator_type>::pointer` |
| `const_pointer` | `#!cpp std::allocator_traits<allocator_type>::const_pointer` |
| `iterator` | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
| `const_iterator` | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) |
| `reverse_iterator` | |
| `const_reverse_iterator` | |
| `iteration_proxy` | |
### JSON value data types
- object_comparator_t
- [**object_t**](object_t.md) - type for objects
- [**array_t**](array_t.md) - type for arrays
- [**string_t**](string_t.md) - type for strings
- [**binary_t**](binary_t.md) - type for binary arrays
- [**boolean_t**](boolean_t.md) - type for booleans
- [**number_float_t**](number_float_t.md) - type for numbers (floating-point)
- [**number_integer_t**](number_integer_t.md) - type for numbers (integer)
- [**number_unsigned_t**](number_unsigned_t.md) - type for numbers (unsigned)
- [**number_float_t**](number_float_t.md) - type for numbers (floating-point)
- binary_t
- [**object_comparator_t**](object_comparator_t.md) - comparator for objects
- [**object_t**](object_t.md) - type for objects
- [**string_t**](string_t.md) - type for strings
### Parser callback
@ -137,10 +137,10 @@ Direct access to the stored value of a JSON value.
- [**get**](get.md) - get a value
- get_to - get a value
- get_ptr - get a pointer value
- get_ref - get a reference value
- operator ValueType - get a value
- get_binary - get a binary value
- [**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
- [**get_binary**](get_binary.md) - get a binary value
### Element access

18
doc/mkdocs/docs/api/basic_json/object_comparator_t.md Normal file
View File

@ -0,0 +1,18 @@
# basic_json::object_comparator_t
```cpp
// until C++14
using object_comparator_t = std::less<StringType>;
// since C++14
using object_comparator_t = std::less<>;
```
The comparator used in [`object_t`](object_t.md).
When C++14 is detected, a transparent com parator is used which, when combined with perfect forwarding on find() and
count() calls, prevents unnecessary string construction.
## Version history
- Unknown.

11
doc/mkdocs/docs/api/basic_json/object_t.md
View File

@ -35,14 +35,25 @@ With the default values for `ObjectType` (`std::map`), `StringType` (`std::strin
(`std::allocator`), the default value for `object_t` is:
```cpp
// until C++14
std::map<
std::string, // key_type
basic_json, // value_type
std::less<std::string>, // key_compare
std::allocator<std::pair<const std::string, basic_json>> // allocator_type
>
// since C++14
std::map<
std::string, // key_type
basic_json, // value_type
std::less<>, // key_compare
std::allocator<std::pair<const std::string, basic_json>> // allocator_type
>
```
See [`object_comparator_t`](object_comparator_t.md) for more information.
#### Behavior
The choice of `object_t` influences the behavior of the JSON class. With the default type, objects have the following

72
doc/mkdocs/docs/api/basic_json/operator_ValueType.md Normal file
View File

@ -0,0 +1,72 @@
# basic_json::operator ValueType
```cpp
template<typename ValueType>
JSON_EXPLICIT operator ValueType() const;
```
Implicit type conversion between the JSON value and a compatible value. The call is realized by calling
[`get()`](get.md). See [Notes](#notes) for the meaning of `JSON_EXPLICIT`.
## Template parameters
`ValueType`
: the value type to return
## Return value
copy of the JSON value, converted to `ValueType`
## Exceptions
Depends on what `json_serializer<ValueType>` `from_json()` method throws
## Complexity
Linear in the size of the JSON value.
## Notes
By default `JSON_EXPLICIT` defined to the empty string, so the signature is:
```cpp
template<typename ValueType>
operator ValueType() const;
```
If [`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) is set to `0`,
`JSON_EXPLICIT` is defined to `#!cpp explicit`:
```cpp
template<typename ValueType>
explicit operator ValueType() const;
```
That is, implicit conversions can be switched off by defining
[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`.
## 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<short>`, (3) A JSON object can be converted to C++
associative containers such as `std::unordered_map<std::string, json>`.
```cpp
--8<-- "examples/operator__ValueType.cpp"
```
Output:
```json
--8<-- "examples/operator__ValueType.output"
```
## Version history
- Since version 1.0.0.
- Macros `JSON_EXPLICIT`/[`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) added
in version 3.9.0.

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

@ -27,7 +27,7 @@ function.
## Exceptions
1. The function can throw thw following exceptions:
1. The function can throw the following exceptions:
- Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than
objects; example: `"cannot use update() with string"`
2. The function can throw thw following exceptions:

6
doc/mkdocs/mkdocs.yml
View File

@ -81,6 +81,7 @@ nav:
- api/basic_json/~basic_json.md
- api/basic_json/begin.md
- api/basic_json/binary.md
- api/basic_json/binary_t.md
- api/basic_json/boolean_t.md
- api/basic_json/cbegin.md
- api/basic_json/cbor_tag_handler_t.md
@ -108,6 +109,9 @@ nav:
- api/basic_json/front.md
- api/basic_json/get.md
- api/basic_json/get_allocator.md
- api/basic_json/get_binary.md
- api/basic_json/get_ptr.md
- api/basic_json/get_ref.md
- api/basic_json/input_format_t.md
- api/basic_json/insert.md
- api/basic_json/invalid_iterator.md
@ -132,7 +136,9 @@ nav:
- api/basic_json/number_integer_t.md
- api/basic_json/number_unsigned_t.md
- api/basic_json/object.md
- api/basic_json/object_comparator_t.md
- api/basic_json/object_t.md
- api/basic_json/operator_ValueType.md
- api/basic_json/operator_value_t.md
- api/basic_json/operator[].md
- api/basic_json/operator=.md