mirror of
https://github.com/nlohmann/json.git
synced 2024-07-07 12:23:49 +02:00
📝 add more API documentation
This commit is contained in:
parent
772f37c12d
commit
6674561d6a
|
@ -8,11 +8,13 @@ INSERT INTO searchIndex(name, type, path) VALUES ('array', 'Function', 'api/basi
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('array_t', 'Type', 'api/basic_json/array_t/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');
|
INSERT INTO searchIndex(name, type, path) VALUES ('at', 'Method', 'api/basic_json/at/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('back', 'Method', 'api/basic_json/back/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('back', 'Method', 'api/basic_json/back/index.html');
|
||||||
|
INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Class', 'api/basic_json/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Constructor', 'api/basic_json/basic_json/index.html');
|
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 ('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', 'Function', 'api/basic_json/binary/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 ('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 ('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');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('cend', 'Method', 'api/basic_json/cend/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('cend', 'Method', 'api/basic_json/cend/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('clear', 'Method', 'api/basic_json/clear/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('clear', 'Method', 'api/basic_json/clear/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('contains', 'Method', 'api/basic_json/contains/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('contains', 'Method', 'api/basic_json/contains/index.html');
|
||||||
|
@ -27,10 +29,12 @@ INSERT INTO searchIndex(name, type, path) VALUES ('empty', 'Method', 'api/basic_
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('end', 'Method', 'api/basic_json/end/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('end', 'Method', 'api/basic_json/end/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('erase', 'Method', 'api/basic_json/erase/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('erase', 'Method', 'api/basic_json/erase/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('error_handler_t', 'Enum', 'api/basic_json/error_handler_t/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('error_handler_t', 'Enum', 'api/basic_json/error_handler_t/index.html');
|
||||||
|
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 ('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 ('flatten', 'Method', 'api/basic_json/flatten/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('front', 'Method', 'api/basic_json/front/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('front', 'Method', 'api/basic_json/front/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('basic_json', 'Class', 'api/basic_json/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');
|
INSERT INTO searchIndex(name, type, path) VALUES ('insert', 'Method', 'api/basic_json/insert/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('is_array', 'Method', 'api/basic_json/is_array/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('is_array', 'Method', 'api/basic_json/is_array/index.html');
|
||||||
INSERT INTO searchIndex(name, type, path) VALUES ('is_binary', 'Method', 'api/basic_json/is_binary/index.html');
|
INSERT INTO searchIndex(name, type, path) VALUES ('is_binary', 'Method', 'api/basic_json/is_binary/index.html');
|
||||||
|
|
21
doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
Normal file
21
doc/mkdocs/docs/api/basic_json/cbor_tag_handler_t.md
Normal file
|
@ -0,0 +1,21 @@
|
||||||
|
# basic_json::cbor_tag_handler_t
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
enum class cbor_tag_handler_t
|
||||||
|
{
|
||||||
|
error,
|
||||||
|
ignore
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
This enumeration is used in the [`from_cbor`](from_cbor.md) function to choose how to treat tags:
|
||||||
|
|
||||||
|
error
|
||||||
|
: throw a `parse_error` exception in case of a tag
|
||||||
|
|
||||||
|
ignore
|
||||||
|
: ignore tags
|
||||||
|
|
||||||
|
## Version history
|
||||||
|
|
||||||
|
- Added in version 3.9.0.
|
65
doc/mkdocs/docs/api/basic_json/exception.md
Normal file
65
doc/mkdocs/docs/api/basic_json/exception.md
Normal file
|
@ -0,0 +1,65 @@
|
||||||
|
# basic_json::exception
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
class exception : public std::exception;
|
||||||
|
```
|
||||||
|
|
||||||
|
This class is an extension of [`std::exception`](https://en.cppreference.com/w/cpp/error/exception) objects with a
|
||||||
|
member `id` for exception ids. It is used as the base class for all exceptions thrown by the `basic_json` class. This
|
||||||
|
class can hence be used as "wildcard" to catch exceptions, see example below.
|
||||||
|
|
||||||
|
```plantuml
|
||||||
|
std::exception <|-- json::exception
|
||||||
|
json::exception <|-- json::parse_error
|
||||||
|
json::exception <|-- json::invalid_iterator
|
||||||
|
json::exception <|-- json::type_error
|
||||||
|
json::exception <|-- json::out_of_range
|
||||||
|
json::exception <|-- json::other_error
|
||||||
|
|
||||||
|
interface std::exception {}
|
||||||
|
|
||||||
|
class json::exception #FFFF00 {
|
||||||
|
+ const int id
|
||||||
|
+ const char* what() const
|
||||||
|
}
|
||||||
|
|
||||||
|
class json::parse_error {
|
||||||
|
+ const std::size_t byte
|
||||||
|
}
|
||||||
|
```
|
||||||
|
|
||||||
|
Subclasses:
|
||||||
|
|
||||||
|
- `parse_error` for exceptions indicating a parse error
|
||||||
|
- `invalid_iterator` for exceptions indicating errors with iterators
|
||||||
|
- `type_error` for exceptions indicating executing a member function with a wrong type
|
||||||
|
- `out_of_range` for exceptions indicating access out of the defined range
|
||||||
|
- `other_error` for exceptions indicating other library errors
|
||||||
|
|
||||||
|
## Member functions
|
||||||
|
|
||||||
|
- **what** - returns explanatory string
|
||||||
|
|
||||||
|
## Member variables
|
||||||
|
|
||||||
|
- **id** - the id of the exception
|
||||||
|
|
||||||
|
## Example
|
||||||
|
|
||||||
|
??? example
|
||||||
|
|
||||||
|
The following code shows how arbitrary library exceptions can be caught.
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
--8<-- "examples/exception.cpp"
|
||||||
|
```
|
||||||
|
|
||||||
|
Output:
|
||||||
|
|
||||||
|
```json
|
||||||
|
--8<-- "examples/exception.output"
|
||||||
|
```
|
||||||
|
|
||||||
|
## Version history
|
||||||
|
|
||||||
|
- Since version 3.0.0.
|
|
@ -53,7 +53,8 @@ Deserializes a given input to a JSON value using the CBOR (Concise Binary Object
|
||||||
: whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
|
: whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
|
||||||
|
|
||||||
`tag_handler` (in)
|
`tag_handler` (in)
|
||||||
: how to treat CBOR tags (optional, `error` by default)
|
: how to treat CBOR tags (optional, `error` by default); see [`cbor_tag_handler_t`](cbor_tag_handler_t.md) for more
|
||||||
|
information
|
||||||
|
|
||||||
## Return value
|
## Return value
|
||||||
|
|
||||||
|
|
15
doc/mkdocs/docs/api/basic_json/get_allocator.md
Normal file
15
doc/mkdocs/docs/api/basic_json/get_allocator.md
Normal file
|
@ -0,0 +1,15 @@
|
||||||
|
# basic_json::get_allocator
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
static allocator_type get_allocator();
|
||||||
|
```
|
||||||
|
|
||||||
|
Returns the allocator associated with the container.
|
||||||
|
|
||||||
|
## Return value
|
||||||
|
|
||||||
|
associated allocator
|
||||||
|
|
||||||
|
## Version history
|
||||||
|
|
||||||
|
- Unknown.
|
|
@ -52,14 +52,14 @@ Todo
|
||||||
- [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
|
- [**json_pointer**](../json_pointer.md) - JSON Pointer implementation
|
||||||
- json_serializer
|
- json_serializer
|
||||||
- [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
|
- [**error_handler_t**](error_handler_t.md) - type to choose behavior on decoding errors
|
||||||
- cbor_tag_handler_t
|
- [**cbor_tag_handler_t**](cbor_tag_handler_t.md) - type to choose how to handle CBOR tags
|
||||||
- initializer_list_t
|
- initializer_list_t
|
||||||
- input_format_t
|
- [**input_format_t**](input_format_t.md) - type to choose the format to parse
|
||||||
- json_sax_t
|
- json_sax_t
|
||||||
|
|
||||||
### Exceptions
|
### Exceptions
|
||||||
|
|
||||||
- exception
|
- [**exception**](exception.md) - general exception of the `basic_json` class
|
||||||
- parse_error
|
- parse_error
|
||||||
- invalid_iterator
|
- invalid_iterator
|
||||||
- type_error
|
- type_error
|
||||||
|
@ -225,7 +225,7 @@ Access to the JSON value
|
||||||
## Static functions
|
## Static functions
|
||||||
|
|
||||||
- [**meta**](meta.md) - returns version information on the library
|
- [**meta**](meta.md) - returns version information on the library
|
||||||
- get_allocator - returns the allocator associated with the container
|
- [**get_allocator**](get_allocator.md) - returns the allocator associated with the container
|
||||||
|
|
||||||
### Binary formats
|
### Binary formats
|
||||||
|
|
||||||
|
|
32
doc/mkdocs/docs/api/basic_json/input_format_t.md
Normal file
32
doc/mkdocs/docs/api/basic_json/input_format_t.md
Normal file
|
@ -0,0 +1,32 @@
|
||||||
|
# basic_json::input_format_t
|
||||||
|
|
||||||
|
```cpp
|
||||||
|
enum class input_format_t {
|
||||||
|
json,
|
||||||
|
cbor,
|
||||||
|
msgpack,
|
||||||
|
ubjson,
|
||||||
|
bson
|
||||||
|
};
|
||||||
|
```
|
||||||
|
|
||||||
|
This enumeration is used in the [`sax_parse`](sax_parse.md) function to choose the input format to parse:
|
||||||
|
|
||||||
|
json
|
||||||
|
: JSON (JavaScript Object Notation)
|
||||||
|
|
||||||
|
cbor
|
||||||
|
: CBOR (Concise Binary Object Representation)
|
||||||
|
|
||||||
|
msgpack
|
||||||
|
: MessagePack
|
||||||
|
|
||||||
|
ubjson
|
||||||
|
: UBJSON (Universal Binary JSON)
|
||||||
|
|
||||||
|
bson
|
||||||
|
: BSON (Binary JSON)
|
||||||
|
|
||||||
|
## Version history
|
||||||
|
|
||||||
|
- Added in version 3.2.0.
|
|
@ -55,7 +55,8 @@ The SAX event lister must follow the interface of `json_sax`.
|
||||||
: SAX event listener
|
: SAX event listener
|
||||||
|
|
||||||
`format` (in)
|
`format` (in)
|
||||||
: the format to parse (JSON, CBOR, MessagePack, or UBJSON) (optional, `input_format_t::json` by default)
|
: the format to parse (JSON, CBOR, MessagePack, or UBJSON) (optional, `input_format_t::json` by default), see
|
||||||
|
[`input_format_t`](input_format_t.md) for more information
|
||||||
|
|
||||||
`strict` (in)
|
`strict` (in)
|
||||||
: whether the input has to be consumed completely (optional, `#!cpp true` by default)
|
: whether the input has to be consumed completely (optional, `#!cpp true` by default)
|
||||||
|
|
|
@ -454,7 +454,6 @@ Cannot get value for iterator: Either the iterator belongs to a null value or it
|
||||||
[json.exception.invalid_iterator.214] cannot get value
|
[json.exception.invalid_iterator.214] cannot get value
|
||||||
```
|
```
|
||||||
|
|
||||||
|
|
||||||
## Type errors
|
## Type errors
|
||||||
|
|
||||||
This exception is thrown in case of a type error; that is, a library function is executed on a JSON value whose type does not match the expected semantics.
|
This exception is thrown in case of a type error; that is, a library function is executed on a JSON value whose type does not match the expected semantics.
|
||||||
|
@ -684,7 +683,6 @@ The dynamic type of the object cannot be represented in the requested serializat
|
||||||
|
|
||||||
Encapsulate the JSON value in an object. That is, instead of serializing `#!json true`, serialize `#!json {"value": true}`
|
Encapsulate the JSON value in an object. That is, instead of serializing `#!json true`, serialize `#!json {"value": true}`
|
||||||
|
|
||||||
|
|
||||||
## Out of range
|
## Out of range
|
||||||
|
|
||||||
This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for instance in case of array indices or nonexisting object keys.
|
This exception is thrown in case a library function is called on an input parameter that exceeds the expected range, for instance in case of array indices or nonexisting object keys.
|
||||||
|
|
|
@ -83,6 +83,7 @@ nav:
|
||||||
- api/basic_json/binary.md
|
- api/basic_json/binary.md
|
||||||
- api/basic_json/boolean_t.md
|
- api/basic_json/boolean_t.md
|
||||||
- api/basic_json/cbegin.md
|
- api/basic_json/cbegin.md
|
||||||
|
- api/basic_json/cbor_tag_handler_t.md
|
||||||
- api/basic_json/cend.md
|
- api/basic_json/cend.md
|
||||||
- api/basic_json/clear.md
|
- api/basic_json/clear.md
|
||||||
- api/basic_json/contains.md
|
- api/basic_json/contains.md
|
||||||
|
@ -97,6 +98,7 @@ nav:
|
||||||
- api/basic_json/end.md
|
- api/basic_json/end.md
|
||||||
- api/basic_json/erase.md
|
- api/basic_json/erase.md
|
||||||
- api/basic_json/error_handler_t.md
|
- api/basic_json/error_handler_t.md
|
||||||
|
- api/basic_json/exception.md
|
||||||
- api/basic_json/find.md
|
- api/basic_json/find.md
|
||||||
- api/basic_json/flatten.md
|
- api/basic_json/flatten.md
|
||||||
- api/basic_json/from_bson.md
|
- api/basic_json/from_bson.md
|
||||||
|
@ -104,6 +106,8 @@ nav:
|
||||||
- api/basic_json/from_msgpack.md
|
- api/basic_json/from_msgpack.md
|
||||||
- api/basic_json/from_ubjson.md
|
- api/basic_json/from_ubjson.md
|
||||||
- api/basic_json/front.md
|
- api/basic_json/front.md
|
||||||
|
- api/basic_json/get_allocator.md
|
||||||
|
- api/basic_json/input_format_t.md
|
||||||
- api/basic_json/insert.md
|
- api/basic_json/insert.md
|
||||||
- api/basic_json/is_array.md
|
- api/basic_json/is_array.md
|
||||||
- api/basic_json/is_binary.md
|
- api/basic_json/is_binary.md
|
||||||
|
|
Loading…
Reference in a new issue