j3d1/json
1
0
Fork 0
Code Issues Pull requests Releases Wiki Activity

📝 add more documentation

Browse source
This commit is contained in:
Niels Lohmann 2020-07-27 14:07:13 +02:00
parent 84c0c76849
commit c006fc9bec
No known key found for this signature in database
GPG key ID: 7F3CEA63AE251B69
5 changed files with 405 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

18
doc/mkdocs/docs/api/basic_json/dump.md
View file

@ -57,16 +57,18 @@ Binary values are serialized as object containing two keys:
## Example ## Example
The following example shows the effect of different `indent`, ??? example
The following example shows the effect of different `indent`,
`indent_char`, and `ensure_ascii` parameters to the result of the `indent_char`, and `ensure_ascii` parameters to the result of the
serialization. serialization.
```cpp ```cpp
--8<-- "examples/dump.cpp" --8<-- "examples/dump.cpp"
``` ```
Output: Output:
```json ```json
--8<-- "examples/dump.output" --8<-- "examples/dump.output"
``` ```

244
doc/mkdocs/docs/api/basic_json/index.md
View file

@ -1,15 +1,253 @@
# Overview # basic_json
!!! note !!! note
This page is under construction. This page is under construction.
Defined in header `<json.hpp>`
```cpp
template<template<typename, typename, typename...> class ObjectType,
template<typename, typename...> class ArrayType,
class StringType, class BooleanType, class NumberIntegerType,
class NumberUnsignedType, class NumberFloatType,
template<typename> class AllocatorType,
template<typename, typename = void> class JSONSerializer,
class BinaryType>
class basic_json
```
## Specializations
- json
- ordered_json
## Template parameters
- ObjectType
- ArrayType
- StringType
- BooleanType
- NumberIntegerType
- NumberUnsignedType
- NumberFloatType
- AllocatorType
- JSONSerializer
- BinaryType
## Iterator invalidation
## Member types
- value_t
- json_pointer
- json_serializer
- error_handler_t
- cbor_tag_handler_t
- initializer_list_t
- input_format_t
- json_sax_t
### Exceptions
- exception
- parse_error
- invalid_iterator
- type_error
- out_of_range
- other_error
### Container types
- value_type
- reference
- const_reference
- difference_type
- size_type
- allocator_type
- pointer
- const_pointer
- iterator
- const_iterator
- reverse_iterator
- const_reverse_iterator
### JSON value data types
- object_comparator_t
- object_t
- array_t
- string_t
- boolean_t
- number_integer_t
- number_unsigned_t
- number_float_t
- binary_t
### Parser callback
- parse_event_t
- parser_callback_t
## Member functions ## Member functions
- (constructor)
- (destructor)
- binary (static) - explicitly create a binary array
- array (static) - explicitly create an array
- object (static) - explicitly create an object
- operator= - copy assignment
### Object inspection ### Object inspection
- [dump](dump.md) - serialization Functions to inspect the type of a JSON value.
- type - return the type of the JSON value
- is_primitive - return whether type is primitive
- is_structured - return whether type is structured
- is_null - return whether value is null
- is_boolean - return whether value is a boolean
- is_number - return whether value is a number
- is_number_integer - return whether value is an integer number
- is_number_unsigned - return whether value is an unsigned integer number
- is_number_float - return whether value is a floating-point number
- is_object - return whether value is an object
- is_array - return whether value is an array
- is_string - return whether value is a string
- is_binary - return whether value is a binary array
- is_discarded - return whether value is discarded
- operator value_t - return the type of the JSON value
### Value access
Direct access to the stored value of a JSON value.
- get - 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
### Element access
Access to the JSON value
- at - access specified array element with bounds checking
- at - access specified object element with bounds checking
- operator[] - access specified array element
- operator[] - access specified object element
- value - access specified object element with default value
- front - access the first element
- back - access the last element
- erase - remove elements
### Lookup
- find - find an element in a JSON object
- count - returns the number of occurrences of a key in a JSON object
- contains - check the existence of an element in a JSON object
### Iterators
- begin - returns an iterator to the first element
- cbegin - returns a const iterator to the first element
- end - returns an iterator to one past the last element
- cend - returns a const iterator to one past the last element
- rbegin - returns an iterator to the reverse-beginning
- rend - returns an iterator to the reverse-end
- crbegin - returns a const iterator to the reverse-beginning
- crend - returns a const iterator to the reverse-end
- items - wrapper to access iterator member functions in range-based for
### Capacity
- empty - checks whether the container is empty
- size - returns the number of elements
- max_size - returns the maximum possible number of elements
### Modifiers
- clear - clears the contents
- push_back - add an object to an array
- operator+= - add an object to an array
- push_back - add an object to an object
- operator+= - add an object to an object
- emplace_back - add an object to an array
- emplace - add an object to an object if key does not exist
- insert - inserts element
- update - updates a JSON object from another object, overwriting existing keys
- swap - exchanges the values
### Lexicographical comparison operators
- operator== - comparison: equal
- operator!= - comparison: not equal
- operator< - comparison: less than
- operator<= - comparison: less than or equal
- operator> - comparison: greater than
- operator>= - comparison: greater than or equal
### Serialization
- [**dump**](dump.md) - serialization
- to_string - user-defined to_string function for JSON values
### Deserialization
- [**parse**](parse.md) - deserialize from a compatible input
- accept - check if the input is valid JSON
- sax_parse - generate SAX events
### Convenience functions
- type_name - return the type as string
### JSON Pointer functions
- at - access specified object element with bounds checking via JSON Pointer
- operator[] - access specified element via JSON Pointer
- value - access specified object element with default value via JSON Pointer
- flatten - return flattened JSON value
- unflatten - unflatten a previously flattened JSON value
### JSON Patch functions
- patch - applies a JSON patch
- diff (static) - creates a diff as a JSON patch
### JSON Merge Patch functions
- merge_patch - applies a JSON Merge Patch
## 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
### Binary formats
- to_cbor - create a CBOR serialization of a given JSON value
- to_msgpack - create a MessagePack serialization of a given JSON value
- to_ubjson - create a UBJSON serialization of a given JSON value
- to_bson - create a BSON serialization of a given JSON value
- from_cbor - create a JSON value from an input in CBOR format
- from_msgpack - create a JSON value from an input in MessagePack format
- from_ubjson - create a JSON value from an input in UBJSON format
- from_bson - create a JSON value from an input in BSON format
## Non-member functions
- operator<<(std::ostream&) - serialize to stream
- operator>>(std::istream&) - deserialize from stream
## Literals
- operator""_json
- operator""_json_pointer
## Helper classes
- std::hash<nlohmann::json\>
- std::less<nlohmann::value_t\>
- std::swap<nlohmann::json\>

146
doc/mkdocs/docs/api/basic_json/parse.md Normal file
View file

@ -0,0 +1,146 @@
# basic_json::parse
```cpp
// (1)
template<typename InputType>
static basic_json parse(InputType&& i,
const parser_callback_t cb = nullptr,
const bool allow_exceptions = true,
const bool ignore_comments = false)
// (2)
template<typename IteratorType>
static basic_json parse(IteratorType first,
IteratorType last,
const parser_callback_t cb = nullptr,
const bool allow_exceptions = true,
const bool ignore_comments = false)
```
1. Deserialize from a compatible input.
2. Deserialize from a pair of character iterators
The value_type of the iterator must be a integral type with size of 1, 2 or
4 bytes, which will be interpreted respectively as UTF-8, UTF-16 and UTF-32.
## Template parameters
`InputType`
: A compatible input, for instance:
- an `std::istream` object
- a `FILE` pointer
- a C-style array of characters
- a pointer to a null-terminated string of single byte characters
- an object `obj` for which `begin(obj)` and `end(obj)` produces a valid pair of
iterators.
`IteratorType`
: Description
## Parameters
`i` (in)
: Input to parse from.
`cb` (in)
: a parser callback function of type `parser_callback_t`
which is used to control the deserialization by filtering unwanted values
(optional)
`allow_exceptions` (in)
: whether to throw exceptions in case of a parse error (optional, `#!cpp true` by default)
`ignore_comments` (in)
: whether comments should be ignored and treated
like whitespace (`#!cpp true`) or yield a parse error (`#!cpp false`); (optional, `#!cpp false` by
default)
`first` (in)
: iterator to start of character range
`last` (in)
: iterator to end of character range
## Return value
Deserialized JSON value; in case of a parse error and `allow_exceptions`
set to `#!cpp false`, the return value will be `value_t::discarded`.
## Exception safety
## Complexity
Linear in the length of the input. The parser is a predictive
LL(1) parser. The complexity can be higher if the parser callback function
`cb` or reading from (1) the input `i` or (2) the iterator range [`first`, `last`] has a super-linear complexity.
## Notes
(1) A UTF-8 byte order mark is silently ignored.
## Examples
??? example
The example below demonstrates the `parse()` function reading
from an array.
```cpp
--8<-- "examples/parse__array__parser_callback_t.cpp"
```
Output:
```json
--8<-- "examples/parse__array__parser_callback_t.output"
```
??? example
The example below demonstrates the `parse()` function with
and without callback function.
```cpp
--8<-- "examples/parse__string__parser_callback_t.cpp"
```
Output:
```json
--8<-- "examples/parse__string__parser_callback_t.output"
```
??? example
The example below demonstrates the `parse()` function with
and without callback function.
```cpp
--8<-- "examples/parse__istream__parser_callback_t.cpp"
```
Output:
```json
--8<-- "examples/parse__istream__parser_callback_t.output"
```
??? example
The example below demonstrates the `parse()` function reading
from a contiguous container.
```cpp
--8<-- "examples/parse__contiguouscontainer__parser_callback_t.cpp"
```
Output:
```json
--8<-- "examples/parse__contiguouscontainer__parser_callback_t.output"
```
## History
(1) version 2.0.3 (contiguous containers); version 3.9.0 allowed to ignore comments.

5
doc/mkdocs/docs/hooks.py
View file

@ -3,5 +3,8 @@ import os.path
def copy_doxygen(*args, **kwargs): def copy_doxygen(*args, **kwargs):
shutil.copytree('../html', os.path.join(kwargs['config']['site_dir'], 'doxygen')) doxygen_dir = os.path.join(kwargs['config']['site_dir'], 'doxygen')
if not os.path.isdir(doxygen_dir) or not os.listdir(doxygen_dir):
print('Copy Doxygen files...')
shutil.copytree('../html', doxygen_dir)
print('Copy Doxygen complete') print('Copy Doxygen complete')

1
doc/mkdocs/mkdocs.yml
View file

@ -74,6 +74,7 @@ nav:
- api/basic_json/index.md - api/basic_json/index.md
- api/basic_json/dump.md - api/basic_json/dump.md
- api/basic_json/meta.md - api/basic_json/meta.md
- api/basic_json/parse.md
# Extras # Extras
extra: extra: