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

📝 make examples collapsible

Browse source
This commit is contained in:
Niels Lohmann 2020-05-24 22:45:38 +02:00
parent ddf92606ab
commit 95a3c76643
No known key found for this signature in database
GPG key ID: 7F3CEA63AE251B69
14 changed files with 502 additions and 270 deletions
Download patch file Download diff file Expand all files Collapse all files

4
doc/mkdocs/docs/features/binary_formats/bson.md
View file

@ -36,7 +36,7 @@ binary | *any value* | binary | 0x05
and the keys may not contain U+0000, since they are serialized a
zero-terminated c-strings.
!!! example
??? example
```cpp
--8<-- "examples/to_bson.cpp"
@ -81,7 +81,7 @@ Min Key | 0xFF | *unsupported*
The mapping is **incomplete**. The unsupported mappings are indicated in the table above.
!!! example
??? example
```cpp
--8<-- "examples/from_bson.cpp"

4
doc/mkdocs/docs/features/binary_formats/cbor.md
View file

@ -84,7 +84,7 @@ binary | *size*: 4294967296..18446744073709551615 | byte string (8 by
- half-precision floats (0xF9)
- break (0xFF)
!!! example
??? example
```cpp
--8<-- "examples/to_cbor.cpp"
@ -159,7 +159,7 @@ Double-Precision Float | number_float | 0xFB
CBOR allows map keys of any type, whereas JSON only allows strings as keys in object values. Therefore, CBOR maps with keys other than UTF-8 strings are rejected.
!!! example
??? example
```cpp
--8<-- "examples/from_cbor.cpp"

6
doc/mkdocs/docs/features/binary_formats/index.md
View file

@ -5,7 +5,7 @@ Though JSON is a ubiquitous data format, it is not a very compact format suitabl
- [BSON](bson.md) (Binary JSON),
- [CBOR](cbor.md) (Concise Binary Object Representation),
- [MessagePack](messagepack.md), and
- [UBJSON](ubjson.md) (Universal Binary JSON Specification)
- [UBJSON](ubjson.md) (Universal Binary JSON)
to efficiently encode JSON values to byte vectors and to decode such vectors.
@ -29,6 +29,8 @@ to efficiently encode JSON values to byte vectors and to decode such vectors.
| MessagePack | supported | supported |
| UBJSON | not supported | not supported |
See [binary values](../binary_values.md) for more information.
### Sizes
| Format | canada.json | twitter.json | citm_catalog.json | jeopardy.json |
@ -39,3 +41,5 @@ to efficiently encode JSON values to byte vectors and to decode such vectors.
| UBJSON | 53,2 % | 91,3 % | 78,2 % | 96,6 % |
| UBJSON (size) | 58,6 % | 92,3 % | 86,8 % | 97,4 % |
| UBJSON (size+type) | 55,9 % | 92,3 % | 85,0 % | 95,0 % |
Sizes compared to minified JSON value.

4
doc/mkdocs/docs/features/binary_formats/messagepack.md
View file

@ -69,7 +69,7 @@ binary | *size*: 65536..4294967295 | bin 32 | 0xC6
If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or Infinity to `null`.
!!! example
??? example
```cpp
--8<-- "examples/to_msgpack.cpp"
@ -129,7 +129,7 @@ negative fixint | number_integer | 0xE0-0xFF
Any MessagePack output created by `to_msgpack` can be successfully parsed by `from_msgpack`.
!!! example
??? example
```cpp
--8<-- "examples/from_msgpack.cpp"

4
doc/mkdocs/docs/features/binary_formats/ubjson.md
View file

@ -81,7 +81,7 @@ object | *see notes on optimized format* | map | `{`
different JSON object.
!!! example
??? example
```cpp
--8<-- "examples/to_ubjson.cpp"
@ -120,7 +120,7 @@ object | object (optimized values are supported) | `{`
The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value.
!!! example
??? example
```cpp
--8<-- "examples/from_ubjson.cpp"

312
doc/mkdocs/docs/features/binary_values.md
View file

@ -88,29 +88,29 @@ Binary values are serialized differently according to the formats.
JSON does not have a binary type, and this library does not introduce a new type as this would break conformance. Instead, binary values are serialized as an object with two keys: `bytes` holds an array of integers, and `subtype` is an integer or `null`.
!!! example
??? example
Code:
Code:
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
// serialize to standard output
std::cout << j.dump(2) << std::endl;
```
Output:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
// serialize to standard output
std::cout << j.dump(2) << std::endl;
```
Output:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
!!! warning "No roundtrip for binary values"
@ -120,79 +120,79 @@ JSON does not have a binary type, and this library does not introduce a new type
[BSON](binary_formats/bson.md) supports binary values and subtypes. 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.
!!! example
??? example
Code:
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
Code:
// convert to BSON
auto v = json::to_bson(j);
```
`v` is a `std::vector<std::uint8t>` with the following 22 elements:
```c
0x16 0x00 0x00 0x00 // number of bytes in the document
0x05 // binary value
0x62 0x69 0x6E 0x61 0x72 0x79 0x00 // key "binary" + null byte
0x04 0x00 0x00 0x00 // number of bytes
0x2a // subtype
0xCA 0xFE 0xBA 0xBE // content
0x00 // end of the document
```
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
Note that the serialization preserves the subtype, and deserializing `v` would yield the following value:
// convert to BSON
auto v = json::to_bson(j);
```
`v` is a `std::vector<std::uint8t>` with the following 22 elements:
```c
0x16 0x00 0x00 0x00 // number of bytes in the document
0x05 // binary value
0x62 0x69 0x6E 0x61 0x72 0x79 0x00 // key "binary" + null byte
0x04 0x00 0x00 0x00 // number of bytes
0x2a // subtype
0xCA 0xFE 0xBA 0xBE // content
0x00 // end of the document
```
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
Note that the serialization preserves the subtype, and deserializing `v` would yield the following value:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
### CBOR
[CBOR](binary_formats/cbor.md) supports binary values, but no subtypes. Any binary value will be serialized as byte strings. The library will choose the smallest representation using the length of the byte array.
!!! example
??? example
Code:
```cpp
// create a binary value of subtype 42 (will be ignored by CBOR)
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
Code:
// convert to CBOR
auto v = json::to_cbor(j);
```
`v` is a `std::vector<std::uint8t>` with the following 13 elements:
```c
0xA1 // map(1)
0x66 // text(6)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x44 // bytes(4)
0xCA 0xFE 0xBA 0xBE // content
```
```cpp
// create a binary value of subtype 42 (will be ignored by CBOR)
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
Note the subtype (42) is **not** serialized, and deserializing `v` would yield the following value:
// convert to CBOR
auto v = json::to_cbor(j);
```
`v` is a `std::vector<std::uint8t>` with the following 13 elements:
```c
0xA1 // map(1)
0x66 // text(6)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x44 // bytes(4)
0xCA 0xFE 0xBA 0xBE // content
```
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": null
}
}
```
Note the subtype (42) is **not** serialized, and deserializing `v` would yield the following value:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": null
}
}
```
### MessagePack
@ -200,95 +200,95 @@ JSON does not have a binary type, and this library does not introduce a new type
If no subtype is given, the bin family (bin8, bin16, bin32) is used.
!!! example
??? example
Code:
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
Code:
// convert to MessagePack
auto v = json::to_msgpack(j);
```
`v` is a `std::vector<std::uint8t>` with the following 14 elements:
```c
0x81 // fixmap1
0xA6 // fixstr6
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0xD6 // fixext4
0x2A // subtype
0xCA 0xFE 0xBA 0xBE // content
```
```cpp
// create a binary value of subtype 42
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
Note that the serialization preserves the subtype, and deserializing `v` would yield the following value:
// convert to MessagePack
auto v = json::to_msgpack(j);
```
`v` is a `std::vector<std::uint8t>` with the following 14 elements:
```c
0x81 // fixmap1
0xA6 // fixstr6
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0xD6 // fixext4
0x2A // subtype
0xCA 0xFE 0xBA 0xBE // content
```
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
Note that the serialization preserves the subtype, and deserializing `v` would yield the following value:
```json
{
"binary": {
"bytes": [202, 254, 186, 190],
"subtype": 42
}
}
```
### UBJSON
[UBJSON](binary_formats/ubjson.md) neither supports binary values nor subtypes, and proposes to serialize binary values as array of uint8 values. This translation is implemented by the library.
!!! example
??? example
Code:
```cpp
// create a binary value of subtype 42 (will be ignored in UBJSON)
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
Code:
// convert to UBJSON
auto v = json::to_msgpack(j);
```
`v` is a `std::vector<std::uint8t>` with the following 20 elements:
```c
0x7B // '{'
0x69 0x06 // i 6 (length of the key)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x5B // '['
0x55 0xCA 0x55 0xFE 0x55 0xBA 0x55 0xBE // content (each byte prefixed with 'U')
0x5D // ']'
0x7D // '}'
```
```cpp
// create a binary value of subtype 42 (will be ignored in UBJSON)
json j;
j["binary"] = json::binary({0xCA, 0xFE, 0xBA, 0xBE}, 42);
The following code uses the type and size optimization for UBJSON:
// convert to UBJSON
auto v = json::to_msgpack(j);
```
`v` is a `std::vector<std::uint8t>` with the following 20 elements:
```c
0x7B // '{'
0x69 0x06 // i 6 (length of the key)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x5B // '['
0x55 0xCA 0x55 0xFE 0x55 0xBA 0x55 0xBE // content (each byte prefixed with 'U')
0x5D // ']'
0x7D // '}'
```
```cpp
// convert to UBJSON using the size and type optimization
auto v = json::to_ubjson(j, true, true);
```
The following code uses the type and size optimization for UBJSON:
The resulting vector has 23 elements; the optimization is not effective for examples with few values:
```cpp
// convert to UBJSON using the size and type optimization
auto v = json::to_ubjson(j, true, true);
```
```c
0x7B // '{'
0x24 // '$' type of the object elements
0x5B // '[' array
0x23 0x69 0x01 // '#' i 1 number of object elements
0x69 0x06 // i 6 (length of the key)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x24 0x55 // '$' 'U' type of the array elements: unsinged integers
0x23 0x69 0x04 // '#' i 4 number of array elements
0xCA 0xFE 0xBA 0xBE // content
```
The resulting vector has 23 elements; the optimization is not effective for examples with few values:
Note that subtype (42) is **not** serialized and that UBJSON has **no binary type**, and deserializing `v` would yield the following value:
```c
0x7B // '{'
0x24 // '$' type of the object elements
0x5B // '[' array
0x23 0x69 0x01 // '#' i 1 number of object elements
0x69 0x06 // i 6 (length of the key)
0x62 0x69 0x6E 0x61 0x72 0x79 // "binary"
0x24 0x55 // '$' 'U' type of the array elements: unsinged integers
0x23 0x69 0x04 // '#' i 4 number of array elements
0xCA 0xFE 0xBA 0xBE // content
```
```json
{
"binary": [202, 254, 186, 190]
}
```
Note that subtype (42) is **not** serialized and that UBJSON has **no binary type**, and deserializing `v` would yield the following value:
```json
{
"binary": [202, 254, 186, 190]
}
```

129
doc/mkdocs/docs/features/iterators.md Normal file
View file

@ -0,0 +1,129 @@
# Iterators
## Overview
A JSON value is a container and allows access via iterators.
![](../images/range-begin-end.svg)
![](../images/range-rbegin-rend.svg)
## Iterator getters
### `begin()`
??? example
The following code shows an example for `begin()`.
```cpp
--8<-- "examples/begin.cpp"
```
Output:
```json
--8<-- "examples/begin.output"
```
### `cbegin()`
??? example
The following code shows an example for `cbegin()`.
```cpp
--8<-- "examples/cbegin.cpp"
```
Output:
```json
--8<-- "examples/cbegin.output"
```
### `end()`
??? example
The following code shows an example for `end()`.
```cpp
--8<-- "examples/end.cpp"
```
Output:
```json
--8<-- "examples/end.output"
```
### `cend()`
??? example
The following code shows an example for `cend()`.
```cpp
--8<-- "examples/cend.cpp"
```
Output:
```json
--8<-- "examples/cend.output"
```
### `rbegin()`
??? example
The following code shows an example for `rbegin()`.
```cpp
--8<-- "examples/rbegin.cpp"
```
Output:
```json
--8<-- "examples/rbegin.output"
```
### `rend()`
??? example
The following code shows an example for `rend()`.
```cpp
--8<-- "examples/rend.cpp"
```
Output:
```json
--8<-- "examples/rend.output"
```
### `items()`
??? example
The following code shows an example for `items()`.
```cpp
--8<-- "examples/items.cpp"
```
Output:
```
--8<-- "examples/items.output"
```
## Iterator invalidation
| Operations | invalidated iterators |
| ---------- | --------------------- |
| `clear` | all |

63
doc/mkdocs/docs/features/json_patch.md
View file

@ -1,28 +1,45 @@
# JSON Patch
# JSON Patch and Diff
On top of this, **JSON Patch** ([RFC 6902](https://tools.ietf.org/html/rfc6902)) allows to describe differences between two JSON values - effectively allowing patch and diff operations known from Unix.
## Patches
```cpp
JSON Patch ([RFC 6902](https://tools.ietf.org/html/rfc6902)) defines a JSON document structure for expressing a sequence of operations to apply to a JSON) document. With the `patch` function, a JSON Patch is applied to the current JSON value by executing all operations from the patch.
// a JSON patch (RFC 6902)
json j_patch = R"([
{ "op": "replace", "path": "/baz", "value": "boo" },
{ "op": "add", "path": "/hello", "value": ["world"] },
{ "op": "remove", "path": "/foo"}
])"_json;
??? example
// apply the patch
json j_result = j_original.patch(j_patch);
// {
// "baz": "boo",
// "hello": ["world"]
// }
The following code shows how a JSON patch is applied to a value.
// calculate a JSON patch from two JSON values
json::diff(j_result, j_original);
// [
// { "op":" replace", "path": "/baz", "value": ["one", "two", "three"] },
// { "op": "remove","path": "/hello" },
// { "op": "add", "path": "/foo", "value": "bar" }
// ]
```
```cpp
--8<-- "examples/patch.cpp"
```
Output:
```json
--8<-- "examples/patch.output"
```
## Diff
The library can also calculate a JSON patch (i.e., a **diff**) given two JSON values.
!!! success "Invariant"
For two JSON values *source* and *target*, the following code yields always true:
```cüü
source.patch(diff(source, target)) == target;
```
??? example
The following code shows how a JSON patch is created as a diff for two JSON values.
```cpp
--8<-- "examples/diff.cpp"
```
Output:
```json
--8<-- "examples/diff.output"
```

41
doc/mkdocs/docs/features/merge_patch.md
View file

@ -1,31 +1,20 @@
# JSON Merge Patch
The library supports **JSON Merge Patch** ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format. Instead of using JSON Pointer (see above) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
The library supports JSON Merge Patch ([RFC 7386](https://tools.ietf.org/html/rfc7386)) as a patch format.
The merge patch format is primarily intended for use with the HTTP PATCH method as a means of describing a set of modifications to a target resource's content. This function applies a merge patch to the current JSON value.
```cpp
// a JSON value
json j_document = R"({
"a": "b",
"c": {
"d": "e",
"f": "g"
}
})"_json;
Instead of using [JSON Pointer](json_pointer.md) to specify values to be manipulated, it describes the changes using a syntax that closely mimics the document being modified.
// a patch
json j_patch = R"({
"a":"z",
"c": {
"f": null
}
})"_json;
??? example
// apply the patch
j_document.merge_patch(j_patch);
// {
// "a": "z",
// "c": {
// "d": "e"
// }
// }
```
The following code shows how a JSON Merge Patch is applied to a JSON document.
```cpp
--8<-- "examples/merge_patch.cpp"
```
Output:
```json
--8<-- "examples/merge_patch.output"
```

2
doc/mkdocs/docs/features/sax_interface.md
View file

@ -3,7 +3,7 @@
The library uses a SAX-like interface with the following functions:
```plantuml
class sax {
interface json::sax_t {
+ {abstract} bool null()
+ {abstract} bool boolean(bool val)

4
doc/mkdocs/docs/features/types.md
View file

@ -17,6 +17,8 @@ By default, JSON values are stored as follows:
Note there are three different types for numbers - when parsing JSON text, the best fitting type is chosen.
## Storage
```plantuml
enum value_t {
null
@ -44,8 +46,10 @@ class json_value << (U,orchid) >> {
}
class basic_json {
-- type and value --
value_t m_type
json_value m_value
-- derived types --
+ <u>typedef</u> object_t
+ <u>typedef</u> array_t
+ <u>typedef</u> binary_t