Skip to content
Projects
Groups
Snippets
Help
Loading...
Help
Support
Keyboard shortcuts
?
Submit feedback
Contribute to GitLab
Sign in / Register
Toggle navigation
J
json
Project overview
Project overview
Details
Activity
Releases
Repository
Repository
Files
Commits
Branches
Tags
Contributors
Graph
Compare
Issues
0
Issues
0
List
Boards
Labels
Milestones
Merge Requests
0
Merge Requests
0
CI / CD
CI / CD
Pipelines
Jobs
Schedules
Analytics
Analytics
CI / CD
Repository
Value Stream
Wiki
Wiki
Snippets
Snippets
Members
Members
Collapse sidebar
Close sidebar
Activity
Graph
Create a new issue
Jobs
Commits
Issue Boards
Open sidebar
Libraries
json
Commits
c006fc9b
Unverified
Commit
c006fc9b
authored
Jul 27, 2020
by
Niels Lohmann
Browse files
Options
Browse Files
Download
Email Patches
Plain Diff
📝
add more documentation
parent
84c0c768
Changes
5
Show whitespace changes
Inline
Side-by-side
Showing
5 changed files
with
405 additions
and
15 deletions
+405
-15
doc/mkdocs/docs/api/basic_json/dump.md
doc/mkdocs/docs/api/basic_json/dump.md
+12
-10
doc/mkdocs/docs/api/basic_json/index.md
doc/mkdocs/docs/api/basic_json/index.md
+241
-3
doc/mkdocs/docs/api/basic_json/parse.md
doc/mkdocs/docs/api/basic_json/parse.md
+146
-0
doc/mkdocs/docs/hooks.py
doc/mkdocs/docs/hooks.py
+5
-2
doc/mkdocs/mkdocs.yml
doc/mkdocs/mkdocs.yml
+1
-0
No files found.
doc/mkdocs/docs/api/basic_json/dump.md
View file @
c006fc9b
...
@@ -57,16 +57,18 @@ Binary values are serialized as object containing two keys:
...
@@ -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"
```
```
doc/mkdocs/docs/api/basic_json/index.md
View file @
c006fc9b
#
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
\>
doc/mkdocs/docs/api/basic_json/parse.md
0 → 100644
View file @
c006fc9b
# 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.
doc/mkdocs/docs/hooks.py
View file @
c006fc9b
...
@@ -3,5 +3,8 @@ import os.path
...
@@ -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'
)
doc/mkdocs/mkdocs.yml
View file @
c006fc9b
...
@@ -74,6 +74,7 @@ nav:
...
@@ -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
:
...
...
Write
Preview
Markdown
is supported
0%
Try again
or
attach a new file
Attach a file
Cancel
You are about to add
0
people
to the discussion. Proceed with caution.
Finish editing this message first!
Cancel
Please
register
or
sign in
to comment