lib/json
1
0
Fork 0
mirror of https://github.com/nlohmann/json.git synced 2025-07-28 12:02:00 +03:00
Code Activity

Consolidate documentation (#3071)

Browse Source 
* 🔥 consolidate documentation
* ♻️ overwork std specializations
* 🚚 move images files to mkdocs
* ♻️ fix URLs
* 🔧 tweak MkDocs configuration
* 🔧 add namespaces
* 📝 document deprecations
* 📝 document documentation generation
* 🚸 improve search
* 🚸 add examples
* 🚧 start adding documentation for macros
* 📝 add note for https://github.com/nlohmann/json/issues/874#issuecomment-1001699139
* 📝 overwork example handling
* 📝 fix Markdown tables
This commit is contained in:
Niels Lohmann
2021-12-29 13:41:01 +01:00
committed by GitHub
parent 6d3115924c
commit 29cd970b94
392 changed files with 4827 additions and 12560 deletions
Download Patch File Download Diff File Expand all files Collapse all files

6
doc/mkdocs/docs/features/arbitrary_types.md
View File

@ -87,8 +87,8 @@ If you just want to serialize/deserialize some structs, the `to_json`/`from_json
There are two macros to make your life easier as long as you (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object:
- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the namespace of the class/struct to create code for.
- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)` is to be defined inside of the class/struct to create code for. This macro can also access private members.
- `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(name, member1, member2, ...)` is to be defined inside the namespace of the class/struct to create code for.
- `NLOHMANN_DEFINE_TYPE_INTRUSIVE(name, member1, member2, ...)` is to be defined inside the class/struct to create code for. This macro can also access private members.
In both macros, the first parameter is the name of the class/struct, and all remaining parameters name the members.
@ -197,7 +197,7 @@ namespace nlohmann {
return {j.get<int>()};
}
// Here's the catch! You must provide a to_json method! Otherwise you
// Here's the catch! You must provide a to_json method! Otherwise, you
// will not be able to convert move_only_type to json, since you fully
// specialized adl_serializer on that type
static void to_json(json& j, move_only_type t) {

78
doc/mkdocs/docs/features/binary_formats/bson.md
View File

@ -1,6 +1,8 @@
# BSON
BSON, short for Bin­ary JSON, is a bin­ary-en­coded seri­al­iz­a­tion of JSON-like doc­u­ments. Like JSON, BSON sup­ports the em­bed­ding of doc­u­ments and ar­rays with­in oth­er doc­u­ments and ar­rays. BSON also con­tains ex­ten­sions that al­low rep­res­ent­a­tion of data types that are not part of the JSON spec. For ex­ample, BSON has a Date type and a BinData type.
BSON, short for Binary JSON, is a binary-encoded serialization of JSON-like documents. Like JSON, BSON supports the
embedding of documents and arrays within other documents and arrays. BSON also contains extensions that allow
representation of data types that are not part of the JSON spec. For example, BSON has a Date type and a BinData type.
!!! abstract "References"
@ -12,21 +14,21 @@ BSON, short for Bin­ary JSON, is a bin­ary-en­coded seri­al­iz­a­tion of
The library uses the following mapping from JSON values types to BSON types:
JSON value type | value/range | BSON type | marker
--------------- | --------------------------------- | ----------- | ------
null | `null` | null | 0x0A
boolean | `true`, `false` | boolean | 0x08
number_integer | -9223372036854775808..-2147483649 | int64 | 0x12
number_integer | -2147483648..2147483647 | int32 | 0x10
number_integer | 2147483648..9223372036854775807 | int64 | 0x12
number_unsigned | 0..2147483647 | int32 | 0x10
number_unsigned | 2147483648..9223372036854775807 | int64 | 0x12
number_unsigned | 9223372036854775808..18446744073709551615| -- | --
number_float | *any value* | double | 0x01
string | *any value* | string | 0x02
array | *any value* | document | 0x04
object | *any value* | document | 0x03
binary | *any value* | binary | 0x05
| JSON value type | value/range | BSON type | marker |
|-----------------|-------------------------------------------|-----------|--------|
| null | `null` | null | 0x0A |
| boolean | `true`, `false` | boolean | 0x08 |
| number_integer | -9223372036854775808..-2147483649 | int64 | 0x12 |
| number_integer | -2147483648..2147483647 | int32 | 0x10 |
| number_integer | 2147483648..9223372036854775807 | int64 | 0x12 |
| number_unsigned | 0..2147483647 | int32 | 0x10 |
| number_unsigned | 2147483648..9223372036854775807 | int64 | 0x12 |
| number_unsigned | 9223372036854775808..18446744073709551615 | -- | -- |
| number_float | *any value* | double | 0x01 |
| string | *any value* | string | 0x02 |
| array | *any value* | document | 0x04 |
| object | *any value* | document | 0x03 |
| binary | *any value* | binary | 0x05 |
!!! warning "Incomplete mapping"
@ -53,28 +55,28 @@ binary | *any value* | binary | 0x05
The library maps BSON record types to JSON value types as follows:
BSON type | BSON marker byte | JSON value type
--------------- | ---------------- | ---------------------------
double | 0x01 | number_float
string | 0x02 | string
document | 0x03 | object
array | 0x04 | array
binary | 0x05 | binary
undefined | 0x06 | *unsupported*
ObjectId | 0x07 | *unsupported*
boolean | 0x08 | boolean
UTC Date-Time | 0x09 | *unsupported*
null | 0x0A | null
Regular Expr. | 0x0B | *unsupported*
DB Pointer | 0x0C | *unsupported*
JavaScript Code | 0x0D | *unsupported*
Symbol | 0x0E | *unsupported*
JavaScript Code | 0x0F | *unsupported*
int32 | 0x10 | number_integer
Timestamp | 0x11 | *unsupported*
128-bit decimal float | 0x13 | *unsupported*
Max Key | 0x7F | *unsupported*
Min Key | 0xFF | *unsupported*
| BSON type | BSON marker byte | JSON value type |
|-----------------------|------------------|-----------------|
| double | 0x01 | number_float |
| string | 0x02 | string |
| document | 0x03 | object |
| array | 0x04 | array |
| binary | 0x05 | binary |
| undefined | 0x06 | *unsupported* |
| ObjectId | 0x07 | *unsupported* |
| boolean | 0x08 | boolean |
| UTC Date-Time | 0x09 | *unsupported* |
| null | 0x0A | null |
| Regular Expr. | 0x0B | *unsupported* |
| DB Pointer | 0x0C | *unsupported* |
| JavaScript Code | 0x0D | *unsupported* |
| Symbol | 0x0E | *unsupported* |
| JavaScript Code | 0x0F | *unsupported* |
| int32 | 0x10 | number_integer |
| Timestamp | 0x11 | *unsupported* |
| 128-bit decimal float | 0x13 | *unsupported* |
| Max Key | 0x7F | *unsupported* |
| Min Key | 0xFF | *unsupported* |
!!! warning "Incomplete mapping"

169
doc/mkdocs/docs/features/binary_formats/cbor.md
View File

@ -1,6 +1,7 @@
# CBOR
The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely small code size, fairly small message size, and extensibility without the need for version negotiation.
The Concise Binary Object Representation (CBOR) is a data format whose design goals include the possibility of extremely
small code size, fairly small message size, and extensibility without the need for version negotiation.
!!! abstract "References"
@ -12,48 +13,48 @@ The Concise Binary Object Representation (CBOR) is a data format whose design go
The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 7049):
JSON value type | value/range | CBOR type | first byte
--------------- | ------------------------------------------ | ---------------------------------- | ---------------
null | `null` | Null | 0xF6
boolean | `true` | True | 0xF5
boolean | `false` | False | 0xF4
number_integer | -9223372036854775808..-2147483649 | Negative integer (8 bytes follow) | 0x3B
number_integer | -2147483648..-32769 | Negative integer (4 bytes follow) | 0x3A
number_integer | -32768..-129 | Negative integer (2 bytes follow) | 0x39
number_integer | -128..-25 | Negative integer (1 byte follow) | 0x38
number_integer | -24..-1 | Negative integer | 0x20..0x37
number_integer | 0..23 | Integer | 0x00..0x17
number_integer | 24..255 | Unsigned integer (1 byte follow) | 0x18
number_integer | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
number_integer | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
number_integer | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
number_unsigned | 0..23 | Integer | 0x00..0x17
number_unsigned | 24..255 | Unsigned integer (1 byte follow) | 0x18
number_unsigned | 256..65535 | Unsigned integer (2 bytes follow) | 0x19
number_unsigned | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A
number_unsigned | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B
number_float | *any value representable by a float* | Single-Precision Float | 0xFA
number_float | *any value NOT representable by a float* | Double-Precision Float | 0xFB
string | *length*: 0..23 | UTF-8 string | 0x60..0x77
string | *length*: 23..255 | UTF-8 string (1 byte follow) | 0x78
string | *length*: 256..65535 | UTF-8 string (2 bytes follow) | 0x79
string | *length*: 65536..4294967295 | UTF-8 string (4 bytes follow) | 0x7A
string | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow) | 0x7B
array | *size*: 0..23 | array | 0x80..0x97
array | *size*: 23..255 | array (1 byte follow) | 0x98
array | *size*: 256..65535 | array (2 bytes follow) | 0x99
array | *size*: 65536..4294967295 | array (4 bytes follow) | 0x9A
array | *size*: 4294967296..18446744073709551615 | array (8 bytes follow) | 0x9B
object | *size*: 0..23 | map | 0xA0..0xB7
object | *size*: 23..255 | map (1 byte follow) | 0xB8
object | *size*: 256..65535 | map (2 bytes follow) | 0xB9
object | *size*: 65536..4294967295 | map (4 bytes follow) | 0xBA
object | *size*: 4294967296..18446744073709551615 | map (8 bytes follow) | 0xBB
binary | *size*: 0..23 | byte string | 0x40..0x57
binary | *size*: 23..255 | byte string (1 byte follow) | 0x58
binary | *size*: 256..65535 | byte string (2 bytes follow) | 0x59
binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A
binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B
| JSON value type | value/range | CBOR type | first byte |
|-----------------|--------------------------------------------|-----------------------------------|------------|
| null | `null` | Null | 0xF6 |
| boolean | `true` | True | 0xF5 |
| boolean | `false` | False | 0xF4 |
| number_integer | -9223372036854775808..-2147483649 | Negative integer (8 bytes follow) | 0x3B |
| number_integer | -2147483648..-32769 | Negative integer (4 bytes follow) | 0x3A |
| number_integer | -32768..-129 | Negative integer (2 bytes follow) | 0x39 |
| number_integer | -128..-25 | Negative integer (1 byte follow) | 0x38 |
| number_integer | -24..-1 | Negative integer | 0x20..0x37 |
| number_integer | 0..23 | Integer | 0x00..0x17 |
| number_integer | 24..255 | Unsigned integer (1 byte follow) | 0x18 |
| number_integer | 256..65535 | Unsigned integer (2 bytes follow) | 0x19 |
| number_integer | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A |
| number_integer | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B |
| number_unsigned | 0..23 | Integer | 0x00..0x17 |
| number_unsigned | 24..255 | Unsigned integer (1 byte follow) | 0x18 |
| number_unsigned | 256..65535 | Unsigned integer (2 bytes follow) | 0x19 |
| number_unsigned | 65536..4294967295 | Unsigned integer (4 bytes follow) | 0x1A |
| number_unsigned | 4294967296..18446744073709551615 | Unsigned integer (8 bytes follow) | 0x1B |
| number_float | *any value representable by a float* | Single-Precision Float | 0xFA |
| number_float | *any value NOT representable by a float* | Double-Precision Float | 0xFB |
| string | *length*: 0..23 | UTF-8 string | 0x60..0x77 |
| string | *length*: 23..255 | UTF-8 string (1 byte follow) | 0x78 |
| string | *length*: 256..65535 | UTF-8 string (2 bytes follow) | 0x79 |
| string | *length*: 65536..4294967295 | UTF-8 string (4 bytes follow) | 0x7A |
| string | *length*: 4294967296..18446744073709551615 | UTF-8 string (8 bytes follow) | 0x7B |
| array | *size*: 0..23 | array | 0x80..0x97 |
| array | *size*: 23..255 | array (1 byte follow) | 0x98 |
| array | *size*: 256..65535 | array (2 bytes follow) | 0x99 |
| array | *size*: 65536..4294967295 | array (4 bytes follow) | 0x9A |
| array | *size*: 4294967296..18446744073709551615 | array (8 bytes follow) | 0x9B |
| object | *size*: 0..23 | map | 0xA0..0xB7 |
| object | *size*: 23..255 | map (1 byte follow) | 0xB8 |
| object | *size*: 256..65535 | map (2 bytes follow) | 0xB9 |
| object | *size*: 65536..4294967295 | map (4 bytes follow) | 0xBA |
| object | *size*: 4294967296..18446744073709551615 | map (8 bytes follow) | 0xBB |
| binary | *size*: 0..23 | byte string | 0x40..0x57 |
| binary | *size*: 23..255 | byte string (1 byte follow) | 0x58 |
| binary | *size*: 256..65535 | byte string (2 bytes follow) | 0x59 |
| binary | *size*: 65536..4294967295 | byte string (4 bytes follow) | 0x5A |
| binary | *size*: 4294967296..18446744073709551615 | byte string (8 bytes follow) | 0x5B |
Binary values with subtype are mapped to tagged values (0xD8..0xDB) depending on the subtype, followed by a byte string,
see "binary" cells in the table above.
@ -104,47 +105,47 @@ see "binary" cells in the table above.
The library maps CBOR types to JSON value types as follows:
CBOR type | JSON value type | first byte
---------------------- | --------------- | ----------
Integer | number_unsigned | 0x00..0x17
Unsigned integer | number_unsigned | 0x18
Unsigned integer | number_unsigned | 0x19
Unsigned integer | number_unsigned | 0x1A
Unsigned integer | number_unsigned | 0x1B
Negative integer | number_integer | 0x20..0x37
Negative integer | number_integer | 0x38
Negative integer | number_integer | 0x39
Negative integer | number_integer | 0x3A
Negative integer | number_integer | 0x3B
Byte string | binary | 0x40..0x57
Byte string | binary | 0x58
Byte string | binary | 0x59
Byte string | binary | 0x5A
Byte string | binary | 0x5B
UTF-8 string | string | 0x60..0x77
UTF-8 string | string | 0x78
UTF-8 string | string | 0x79
UTF-8 string | string | 0x7A
UTF-8 string | string | 0x7B
UTF-8 string | string | 0x7F
array | array | 0x80..0x97
array | array | 0x98
array | array | 0x99
array | array | 0x9A
array | array | 0x9B
array | array | 0x9F
map | object | 0xA0..0xB7
map | object | 0xB8
map | object | 0xB9
map | object | 0xBA
map | object | 0xBB
map | object | 0xBF
False | `false` | 0xF4
True | `true` | 0xF5
Null | `null` | 0xF6
Half-Precision Float | number_float | 0xF9
Single-Precision Float | number_float | 0xFA
Double-Precision Float | number_float | 0xFB
| CBOR type | JSON value type | first byte |
|------------------------|-----------------|------------|
| Integer | number_unsigned | 0x00..0x17 |
| Unsigned integer | number_unsigned | 0x18 |
| Unsigned integer | number_unsigned | 0x19 |
| Unsigned integer | number_unsigned | 0x1A |
| Unsigned integer | number_unsigned | 0x1B |
| Negative integer | number_integer | 0x20..0x37 |
| Negative integer | number_integer | 0x38 |
| Negative integer | number_integer | 0x39 |
| Negative integer | number_integer | 0x3A |
| Negative integer | number_integer | 0x3B |
| Byte string | binary | 0x40..0x57 |
| Byte string | binary | 0x58 |
| Byte string | binary | 0x59 |
| Byte string | binary | 0x5A |
| Byte string | binary | 0x5B |
| UTF-8 string | string | 0x60..0x77 |
| UTF-8 string | string | 0x78 |
| UTF-8 string | string | 0x79 |
| UTF-8 string | string | 0x7A |
| UTF-8 string | string | 0x7B |
| UTF-8 string | string | 0x7F |
| array | array | 0x80..0x97 |
| array | array | 0x98 |
| array | array | 0x99 |
| array | array | 0x9A |
| array | array | 0x9B |
| array | array | 0x9F |
| map | object | 0xA0..0xB7 |
| map | object | 0xB8 |
| map | object | 0xB9 |
| map | object | 0xBA |
| map | object | 0xBB |
| map | object | 0xBF |
| False | `false` | 0xF4 |
| True | `true` | 0xF5 |
| Null | `null` | 0xF6 |
| Half-Precision Float | number_float | 0xF9 |
| Single-Precision Float | number_float | 0xFA |
| Double-Precision Float | number_float | 0xFB |
!!! warning "Incomplete mapping"

8
doc/mkdocs/docs/features/binary_formats/index.md
View File

@ -1,4 +1,4 @@
# Overview
# Binary Formats
Though JSON is a ubiquitous data format, it is not a very compact format suitable for data exchange, for instance over a network. Hence, the library supports
@ -14,7 +14,7 @@ to efficiently encode JSON values to byte vectors and to decode such vectors.
### Completeness
| Format | Serialization | Deserialization |
| ----------- |---------------------------------------------- | -------------------------------------------- |
|-------------|-----------------------------------------------|----------------------------------------------|
| BSON | incomplete: top-level value must be an object | incomplete, but all JSON types are supported |
| CBOR | complete | incomplete, but all JSON types are supported |
| MessagePack | complete | complete |
@ -23,7 +23,7 @@ to efficiently encode JSON values to byte vectors and to decode such vectors.
### Binary values
| Format | Binary values | Binary subtypes |
| ----------- | ------------- | --------------- |
|-------------|---------------|-----------------|
| BSON | supported | supported |
| CBOR | supported | supported |
| MessagePack | supported | supported |
@ -34,7 +34,7 @@ See [binary values](../binary_values.md) for more information.
### Sizes
| Format | canada.json | twitter.json | citm_catalog.json | jeopardy.json |
| ------------------ | ----------- | ------------ | ----------------- | ------------- |
|--------------------|-------------|--------------|-------------------|---------------|
| BSON | 85,8 % | 95,2 % | 95,8 % | 106,7 % |
| CBOR | 50,5 % | 86,3 % | 68,4 % | 88,0 % |
| MessagePack | 50,6 % | 86,0 % | 68,5 % | 87,9 % |

146
doc/mkdocs/docs/features/binary_formats/messagepack.md
View File

@ -11,41 +11,41 @@ MessagePack is an efficient binary serialization format. It lets you exchange da
The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification:
JSON value type | value/range | MessagePack type | first byte
--------------- | --------------------------------- | ---------------- | ----------
null | `null` | nil | 0xC0
boolean | `true` | true | 0xC3
boolean | `false` | false | 0xC2
number_integer | -9223372036854775808..-2147483649 | int64 | 0xD3
number_integer | -2147483648..-32769 | int32 | 0xD2
number_integer | -32768..-129 | int16 | 0xD1
number_integer | -128..-33 | int8 | 0xD0
number_integer | -32..-1 | negative fixint | 0xE0..0xFF
number_integer | 0..127 | positive fixint | 0x00..0x7F
number_integer | 128..255 | uint 8 | 0xCC
number_integer | 256..65535 | uint 16 | 0xCD
number_integer | 65536..4294967295 | uint 32 | 0xCE
number_integer | 4294967296..18446744073709551615 | uint 64 | 0xCF
number_unsigned | 0..127 | positive fixint | 0x00..0x7F
number_unsigned | 128..255 | uint 8 | 0xCC
number_unsigned | 256..65535 | uint 16 | 0xCD
number_unsigned | 65536..4294967295 | uint 32 | 0xCE
number_unsigned | 4294967296..18446744073709551615 | uint 64 | 0xCF
number_float | *any value representable by a float* | float 32 | 0xCA
number_float | *any value NOT representable by a float* | float 64 | 0xCB
string | *length*: 0..31 | fixstr | 0xA0..0xBF
string | *length*: 32..255 | str 8 | 0xD9
string | *length*: 256..65535 | str 16 | 0xDA
string | *length*: 65536..4294967295 | str 32 | 0xDB
array | *size*: 0..15 | fixarray | 0x90..0x9F
array | *size*: 16..65535 | array 16 | 0xDC
array | *size*: 65536..4294967295 | array 32 | 0xDD
object | *size*: 0..15 | fix map | 0x80..0x8F
object | *size*: 16..65535 | map 16 | 0xDE
object | *size*: 65536..4294967295 | map 32 | 0xDF
binary | *size*: 0..255 | bin 8 | 0xC4
binary | *size*: 256..65535 | bin 16 | 0xC5
binary | *size*: 65536..4294967295 | bin 32 | 0xC6
| JSON value type | value/range | MessagePack type | first byte |
|-----------------|------------------------------------------|------------------|------------|
| null | `null` | nil | 0xC0 |
| boolean | `true` | true | 0xC3 |
| boolean | `false` | false | 0xC2 |
| number_integer | -9223372036854775808..-2147483649 | int64 | 0xD3 |
| number_integer | -2147483648..-32769 | int32 | 0xD2 |
| number_integer | -32768..-129 | int16 | 0xD1 |
| number_integer | -128..-33 | int8 | 0xD0 |
| number_integer | -32..-1 | negative fixint | 0xE0..0xFF |
| number_integer | 0..127 | positive fixint | 0x00..0x7F |
| number_integer | 128..255 | uint 8 | 0xCC |
| number_integer | 256..65535 | uint 16 | 0xCD |
| number_integer | 65536..4294967295 | uint 32 | 0xCE |
| number_integer | 4294967296..18446744073709551615 | uint 64 | 0xCF |
| number_unsigned | 0..127 | positive fixint | 0x00..0x7F |
| number_unsigned | 128..255 | uint 8 | 0xCC |
| number_unsigned | 256..65535 | uint 16 | 0xCD |
| number_unsigned | 65536..4294967295 | uint 32 | 0xCE |
| number_unsigned | 4294967296..18446744073709551615 | uint 64 | 0xCF |
| number_float | *any value representable by a float* | float 32 | 0xCA |
| number_float | *any value NOT representable by a float* | float 64 | 0xCB |
| string | *length*: 0..31 | fixstr | 0xA0..0xBF |
| string | *length*: 32..255 | str 8 | 0xD9 |
| string | *length*: 256..65535 | str 16 | 0xDA |
| string | *length*: 65536..4294967295 | str 32 | 0xDB |
| array | *size*: 0..15 | fixarray | 0x90..0x9F |
| array | *size*: 16..65535 | array 16 | 0xDC |
| array | *size*: 65536..4294967295 | array 32 | 0xDD |
| object | *size*: 0..15 | fix map | 0x80..0x8F |
| object | *size*: 16..65535 | map 16 | 0xDE |
| object | *size*: 65536..4294967295 | map 32 | 0xDF |
| binary | *size*: 0..255 | bin 8 | 0xC4 |
| binary | *size*: 256..65535 | bin 16 | 0xC5 |
| binary | *size*: 65536..4294967295 | bin 32 | 0xC6 |
!!! success "Complete mapping"
@ -82,44 +82,44 @@ binary | *size*: 65536..4294967295 | bin 32 | 0xC6
The library maps MessagePack types to JSON value types as follows:
MessagePack type | JSON value type | first byte
---------------- | --------------- | ----------
positive fixint | number_unsigned | 0x00..0x7F
fixmap | object | 0x80..0x8F
fixarray | array | 0x90..0x9F
fixstr | string | 0xA0..0xBF
nil | `null` | 0xC0
false | `false` | 0xC2
true | `true` | 0xC3
float 32 | number_float | 0xCA
float 64 | number_float | 0xCB
uint 8 | number_unsigned | 0xCC
uint 16 | number_unsigned | 0xCD
uint 32 | number_unsigned | 0xCE
uint 64 | number_unsigned | 0xCF
int 8 | number_integer | 0xD0
int 16 | number_integer | 0xD1
int 32 | number_integer | 0xD2
int 64 | number_integer | 0xD3
str 8 | string | 0xD9
str 16 | string | 0xDA
str 32 | string | 0xDB
array 16 | array | 0xDC
array 32 | array | 0xDD
map 16 | object | 0xDE
map 32 | object | 0xDF
bin 8 | binary | 0xC4
bin 16 | binary | 0xC5
bin 32 | binary | 0xC6
ext 8 | binary | 0xC7
ext 16 | binary | 0xC8
ext 32 | binary | 0xC9
fixext 1 | binary | 0xD4
fixext 2 | binary | 0xD5
fixext 4 | binary | 0xD6
fixext 8 | binary | 0xD7
fixext 16 | binary | 0xD8
negative fixint | number_integer | 0xE0-0xFF
| MessagePack type | JSON value type | first byte |
|------------------|-----------------|------------|
| positive fixint | number_unsigned | 0x00..0x7F |
| fixmap | object | 0x80..0x8F |
| fixarray | array | 0x90..0x9F |
| fixstr | string | 0xA0..0xBF |
| nil | `null` | 0xC0 |
| false | `false` | 0xC2 |
| true | `true` | 0xC3 |
| float 32 | number_float | 0xCA |
| float 64 | number_float | 0xCB |
| uint 8 | number_unsigned | 0xCC |
| uint 16 | number_unsigned | 0xCD |
| uint 32 | number_unsigned | 0xCE |
| uint 64 | number_unsigned | 0xCF |
| int 8 | number_integer | 0xD0 |
| int 16 | number_integer | 0xD1 |
| int 32 | number_integer | 0xD2 |
| int 64 | number_integer | 0xD3 |
| str 8 | string | 0xD9 |
| str 16 | string | 0xDA |
| str 32 | string | 0xDB |
| array 16 | array | 0xDC |
| array 32 | array | 0xDD |
| map 16 | object | 0xDE |
| map 32 | object | 0xDF |
| bin 8 | binary | 0xC4 |
| bin 16 | binary | 0xC5 |
| bin 32 | binary | 0xC6 |
| ext 8 | binary | 0xC7 |
| ext 16 | binary | 0xC8 |
| ext 32 | binary | 0xC9 |
| fixext 1 | binary | 0xD4 |
| fixext 2 | binary | 0xD5 |
| fixext 4 | binary | 0xD6 |
| fixext 8 | binary | 0xD7 |
| fixext 16 | binary | 0xD8 |
| negative fixint | number_integer | 0xE0-0xFF |
!!! info

80
doc/mkdocs/docs/features/binary_formats/ubjson.md
View File

@ -10,29 +10,29 @@ Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but req
The library uses the following mapping from JSON values types to UBJSON types according to the UBJSON specification:
JSON value type | value/range | UBJSON type | marker
--------------- | --------------------------------- | ----------- | ------
null | `null` | null | `Z`
boolean | `true` | true | `T`
boolean | `false` | false | `F`
number_integer | -9223372036854775808..-2147483649 | int64 | `L`
number_integer | -2147483648..-32769 | int32 | `l`
number_integer | -32768..-129 | int16 | `I`
number_integer | -128..127 | int8 | `i`
number_integer | 128..255 | uint8 | `U`
number_integer | 256..32767 | int16 | `I`
number_integer | 32768..2147483647 | int32 | `l`
number_integer | 2147483648..9223372036854775807 | int64 | `L`
number_unsigned | 0..127 | int8 | `i`
number_unsigned | 128..255 | uint8 | `U`
number_unsigned | 256..32767 | int16 | `I`
number_unsigned | 32768..2147483647 | int32 | `l`
number_unsigned | 2147483648..9223372036854775807 | int64 | `L`
number_unsigned | 2147483649..18446744073709551615 | high-precision | `H`
number_float | *any value* | float64 | `D`
string | *with shortest length indicator* | string | `S`
array | *see notes on optimized format* | array | `[`
object | *see notes on optimized format* | map | `{`
| JSON value type | value/range | UBJSON type | marker |
|-----------------|-----------------------------------|----------------|--------|
| null | `null` | null | `Z` |
| boolean | `true` | true | `T` |
| boolean | `false` | false | `F` |
| number_integer | -9223372036854775808..-2147483649 | int64 | `L` |
| number_integer | -2147483648..-32769 | int32 | `l` |
| number_integer | -32768..-129 | int16 | `I` |
| number_integer | -128..127 | int8 | `i` |
| number_integer | 128..255 | uint8 | `U` |
| number_integer | 256..32767 | int16 | `I` |
| number_integer | 32768..2147483647 | int32 | `l` |
| number_integer | 2147483648..9223372036854775807 | int64 | `L` |
| number_unsigned | 0..127 | int8 | `i` |
| number_unsigned | 128..255 | uint8 | `U` |
| number_unsigned | 256..32767 | int16 | `I` |
| number_unsigned | 32768..2147483647 | int32 | `l` |
| number_unsigned | 2147483648..9223372036854775807 | int64 | `L` |
| number_unsigned | 2147483649..18446744073709551615 | high-precision | `H` |
| number_float | *any value* | float64 | `D` |
| string | *with shortest length indicator* | string | `S` |
| array | *see notes on optimized format* | array | `[` |
| object | *see notes on optimized format* | map | `{` |
!!! success "Complete mapping"
@ -97,23 +97,23 @@ object | *see notes on optimized format* | map | `{`
The library maps UBJSON types to JSON value types as follows:
UBJSON type | JSON value type | marker
----------- | --------------------------------------- | ------
no-op | *no value, next value is read* | `N`
null | `null` | `Z`
false | `false` | `F`
true | `true` | `T`
float32 | number_float | `d`
float64 | number_float | `D`
uint8 | number_unsigned | `U`
int8 | number_integer | `i`
int16 | number_integer | `I`
int32 | number_integer | `l`
int64 | number_integer | `L`
string | string | `S`
char | string | `C`
array | array (optimized values are supported) | `[`
object | object (optimized values are supported) | `{`
| UBJSON type | JSON value type | marker |
|-------------|-----------------------------------------|--------|
| no-op | *no value, next value is read* | `N` |
| null | `null` | `Z` |
| false | `false` | `F` |
| true | `true` | `T` |
| float32 | number_float | `d` |
| float64 | number_float | `D` |
| uint8 | number_unsigned | `U` |
| int8 | number_integer | `i` |
| int16 | number_integer | `I` |
| int32 | number_integer | `l` |
| int64 | number_integer | `L` |
| string | string | `S` |
| char | string | `C` |
| array | array (optimized values are supported) | `[` |
| object | object (optimized values are supported) | `{` |
!!! success "Complete mapping"

12
doc/mkdocs/docs/features/element_access/checked_access.md
View File

@ -27,7 +27,7 @@ The `#!cpp at()` member function performs checked access; that is, it returns a
| `#!cpp j.at("hobbies").at(0)` | `#!json "hiking"` |
| `#!cpp j.at("hobbies").at(1)` | `#!json "reading"` |
The return value is a reference, so it can be modify the original value.
The return value is a reference, so it can be modified by the original value.
??? example
@ -69,9 +69,9 @@ When accessing an invalid index (i.e., an index greater than or equal to the arr
## Summary
| scenario | non-const value | const value |
| -------- | ------------- | ----------- |
| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
| scenario | non-const value | const value |
|-----------------------------------|------------------------------------------------|------------------------------------------------|
| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
| access to non-existing object key | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
| access to invalid array index | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |
| access to invalid array index | `basic_json::out_of_range` exception is thrown | `basic_json::out_of_range` exception is thrown |

2
doc/mkdocs/docs/features/element_access/index.md
View File

@ -1,4 +1,4 @@
# Overview
# Element Access
There are many ways elements in a JSON value can be accessed:

14
doc/mkdocs/docs/features/element_access/unchecked_access.md
View File

@ -27,7 +27,7 @@ Elements in a JSON object and a JSON array can be accessed via `#!cpp operator[]
| `#!cpp j["hobbies"][0]` | `#!json "hiking"` |
| `#!cpp j["hobbies"][1]` | `#!json "reading"` |
The return value is a reference, so it can be modify the original value. In case the passed object key is non-existing, a `#!json null` value is inserted which can be immediately be overwritten.
The return value is a reference, so it can modify the original value. In case the passed object key is non-existing, a `#!json null` value is inserted which can be immediately be overwritten.
??? example
@ -94,9 +94,9 @@ When accessing an invalid index (i.e., an index greater than or equal to the arr
## Summary
| scenario | non-const value | const value |
| -------- | ------------- | ----------- |
| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
| access to non-existing object key | reference to newly inserted `#!json null` value is returned | **undefined behavior**; assertion in debug mode |
| access to invalid array index | reference to newly inserted `#!json null` value is returned; any index between previous maximal index and passed index are filled with `#!json null` | **undefined behavior**; assertion in debug mode |
| scenario | non-const value | const value |
|-----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| access to existing object key | reference to existing value is returned | const reference to existing value is returned |
| access to valid array index | reference to existing value is returned | const reference to existing value is returned |
| access to non-existing object key | reference to newly inserted `#!json null` value is returned | **undefined behavior**; assertion in debug mode |
| access to invalid array index | reference to newly inserted `#!json null` value is returned; any index between previous maximal index and passed index are filled with `#!json null` | **undefined behavior**; assertion in debug mode |

16
doc/mkdocs/docs/features/enum_conversion.md
View File

@ -1,6 +1,8 @@
# Specializing enum conversion
By default, enum values are serialized to JSON as integers. In some cases this could result in undesired behavior. If an enum is modified or re-ordered after data has been serialized to JSON, the later de-serialized JSON data may be undefined or a different enum value than was originally intended.
By default, enum values are serialized to JSON as integers. In some cases this could result in undesired behavior. If an
enum is modified or re-ordered after data has been serialized to JSON, the later de-serialized JSON data may be
undefined or a different enum value than was originally intended.
It is possible to more precisely specify how a given enum is mapped to and from JSON as shown below:
@ -22,7 +24,8 @@ NLOHMANN_JSON_SERIALIZE_ENUM( TaskState, {
})
```
The `NLOHMANN_JSON_SERIALIZE_ENUM()` macro declares a set of `to_json()` / `from_json()` functions for type `TaskState` while avoiding repetition and boilerplate serialization code.
The `NLOHMANN_JSON_SERIALIZE_ENUM()` macro declares a set of `to_json()` / `from_json()` functions for type `TaskState`
while avoiding repetition and boilerplate serialization code.
## Usage
@ -44,10 +47,13 @@ assert(jPi.get<TaskState>() == TS_INVALID );
Just as in [Arbitrary Type Conversions](#arbitrary-types-conversions) above,
- `NLOHMANN_JSON_SERIALIZE_ENUM()` MUST be declared in your enum type's namespace (which can be the global namespace), or the library will not be able to locate it and it will default to integer serialization.
- `NLOHMANN_JSON_SERIALIZE_ENUM()` MUST be declared in your enum type's namespace (which can be the global namespace),
or the library will not be able to locate it, and it will default to integer serialization.
- It MUST be available (e.g., proper headers must be included) everywhere you use the conversions.
Other Important points:
- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this default pair carefully.
- If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the map will be returned when converting to or from JSON.
- When using `get<ENUM_TYPE>()`, undefined JSON values will default to the first pair specified in your map. Select this
default pair carefully.
- If an enum or JSON value is specified more than once in your map, the first matching occurrence from the top of the
map will be returned when converting to or from JSON.

8
doc/mkdocs/docs/features/iterators.md
View File

@ -66,7 +66,7 @@ The JSON iterators have two member functions, `key()` and `value()` to access th
### Range-based for loops
C++11 allows to use range-based for loops to iterate over a container.
C++11 allows using range-based for loops to iterate over a container.
```cpp
for (auto it : j_object)
@ -76,7 +76,7 @@ for (auto it : j_object)
}
```
For this reason, the `items()` function allows to access `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a reference to the JSON values is returned, so there is no access to the underlying iterator.
For this reason, the `items()` function allows accessing `iterator::key()` and `iterator::value()` during range-based for loops. In these loops, a reference to the JSON values is returned, so there is no access to the underlying iterator.
```cpp
for (auto& el : j_object.items())
@ -85,7 +85,7 @@ for (auto& el : j_object.items())
}
```
The items() function also allows to use structured bindings (C++17):
The items() function also allows using structured bindings (C++17):
```cpp
for (auto& [key, val] : j_object.items())
@ -151,5 +151,5 @@ Note that "value" means a JSON value in this setting, not values stored in the u
## Iterator invalidation
| Operations | invalidated iterators |
| ---------- | --------------------- |
|------------|-----------------------|
| `clear` | all |

4
doc/mkdocs/docs/features/json_patch.md
View File

@ -2,7 +2,9 @@
## Patches
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.
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.
??? example

4
doc/mkdocs/docs/features/json_pointer.md
View File

@ -13,3 +13,7 @@ json j_original = R"({
j_original["/baz/1"_json_pointer];
// "two"
```
## See also
- Class [`json_pointer`](../api/json_pointer/index.md)

68
doc/mkdocs/docs/features/macros.md
View File

@ -8,21 +8,31 @@ The default value is `#!cpp assert(x)`.
## `JSON_CATCH_USER(exception)`
This macro overrides `#!cpp catch` calls inside the library. The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range` exceptions internally to rethrow them as [`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The macro is always followed by a scope.
This macro overrides `#!cpp catch` calls inside the library. The argument is the type of the exception to catch. As of
version 3.8.0, the library only catches `std::out_of_range` exceptions internally to rethrow them as
[`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The macro is always followed by a scope.
See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
## `JSON_DIAGNOSTICS`
This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable (default).
This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable
(default).
When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. Note that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead.
When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the
exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. Note
that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead.
The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets `JSON_DIAGNOSTICS` accordingly.
The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets
`JSON_DIAGNOSTICS` accordingly.
## `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20`
The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view` support for C++17). For these new features, the library implements some preprocessor checks to determine the C++ standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be detected incorrectly.
The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view`
support for C++17). For these new features, the library implements some preprocessor checks to determine the C++
standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is
unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be
detected incorrectly.
## `JSON_HAS_FILESYSTEM`, `JSON_HAS_EXPERIMENTAL_FILESYSTEM`
@ -33,25 +43,31 @@ To override the built-in check, define `JSON_HAS_FILESYSTEM` or `JSON_HAS_EXPERI
## `JSON_NOEXCEPTION`
Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`.
When defining `JSON_NOEXCEPTION`, `#!cpp try` is replaced by `#!cpp if (true)`,
`#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by `#!cpp std::abort()`.
Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try`
is replaced by `#!cpp if (true)`, `#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by
`#!cpp std::abort()`.
The same effect is achieved by setting the compiler flag `-fno-exceptions`.
Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not
available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824).
## `JSON_NO_IO`
When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for security reasons (e.g., Intel Software Guard Extensions (SGX)).
When defined, headers `<cstdio>`, `<ios>`, `<iosfwd>`, `<istream>`, and `<ostream>` are not included and parse functions
relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for
security reasons (e.g., Intel Software Guard Extensions (SGX)).
## `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK`
When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.
When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to
use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used.
## `JSON_THROW_USER(exception)`
This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior.
This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that
`JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield
undefined behavior.
See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example.
@ -74,33 +90,45 @@ When defined to `0`, implicit conversions are switched off. By default, implicit
std::string s = j;
```
When `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`, the code above does no longer compile. Instead, it must be written like this:
When `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`, the code above does no longer compile. Instead, it must be
written like this:
```cpp
json j = "Hello, world!";
auto s = j.get<std::string>();
```
Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which
sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly.
## `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)`
This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object.
This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as
serialization and (2) want to use the member variable names as object keys in that object.
The macro is to be defined inside of the class/struct to create code for. Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](#nlohmann_define_type_non_intrusivetype-member), it can access private members.
The macro is to be defined inside the class/struct to create code for. Unlike
[`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](#nlohmann_define_type_non_intrusivetype-member), it can access private members.
The first parameter is the name of the class/struct, and all remaining parameters name the members.
See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example.
## `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)`
This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object.
This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as
serialization and (2) want to use the member variable names as object keys in that object.
The macro is to be defined inside of the namespace of the class/struct to create code for. Private members cannot be accessed. Use [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](#nlohmann_define_type_intrusivetype-member) in these scenarios.
The first parameter is the name of the class/struct, and all remaining parameters name the members.
The macro is to be defined inside the namespace of the class/struct to create code for. Private members cannot be
accessed. Use [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](#nlohmann_define_type_intrusivetype-member) in these scenarios. The
first parameter is the name of the class/struct, and all remaining parameters name the members.
See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example.
## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)`
This macro simplifies the serialization/deserialization of enum types. See [Specializing enum conversion](enum_conversion.md) for more information.
This macro simplifies the serialization/deserialization of enum types. See
[Specializing enum conversion](enum_conversion.md) for more information.
## `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, `NLOHMANN_JSON_VERSION_PATCH`
These macros are defined by the library and contain the version numbers according to
[Semantic Versioning 2.0.0](https://semver.org).

2
doc/mkdocs/docs/features/parsing/index.md
View File

@ -1,4 +1,4 @@
# Overview
# Parsing
!!! note

16
doc/mkdocs/docs/features/parsing/parser_callbacks.md
View File

@ -20,14 +20,14 @@ using parser_callback_t =
We distinguish six scenarios (determined by the event type) in which the callback function can be called. The following table describes the values
of the parameters `depth`, `event`, and `parsed`.
parameter `event` | description | parameter `depth` | parameter `parsed`
------------------ | ----------- | ------------------ | -------------------
`parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded
`parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key
`parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object
`parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded
`parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array
`parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value
| parameter `event` | description | parameter `depth` | parameter `parsed` |
|-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------|
| `parse_event_t::object_start` | the parser read `{` and started to process a JSON object | depth of the parent of the JSON object | a JSON value with type discarded |
| `parse_event_t::key` | the parser read a key of a value in an object | depth of the currently parsed JSON object | a JSON string containing the key |
| `parse_event_t::object_end` | the parser read `}` and finished processing a JSON object | depth of the parent of the JSON object | the parsed JSON object |
| `parse_event_t::array_start` | the parser read `[` and started to process a JSON array | depth of the parent of the JSON array | a JSON value with type discarded |
| `parse_event_t::array_end` | the parser read `]` and finished processing a JSON array | depth of the parent of the JSON array | the parsed JSON array |
| `parse_event_t::value` | the parser finished reading a JSON value | depth of the value | the parsed JSON value |
??? example

5
doc/mkdocs/docs/features/parsing/sax_interface.md
View File

@ -66,3 +66,8 @@ To implement your own SAX handler, proceed as follows:
3. Call `#!cpp bool json::sax_parse(input, &my_sax);` where the first parameter can be any input like a string or an input stream and the second parameter is a pointer to your SAX interface.
Note the `sax_parse` function only returns a `#!cpp bool` indicating the result of the last executed SAX event. It does not return `json` value - it is up to you to decide what to do with the SAX events. Furthermore, no exceptions are thrown in case of a parse error - it is up to you what to do with the exception object passed to your `parse_error` implementation. Internally, the SAX interface is used for the DOM parser (class `json_sax_dom_parser`) as well as the acceptor (`json_sax_acceptor`), see file `json_sax.hpp`.
## See also
- [json_sax](../../api/json_sax/index.md) - documentation of the SAX interface
- [sax_parse](../../api/basic_json/sax_parse.md) - SAX parser

16
doc/mkdocs/docs/features/types/index.md
View File

@ -1,4 +1,4 @@
# Overview
# Types
This page gives an overview how JSON values are stored and how this can be configured.
@ -6,13 +6,13 @@ This page gives an overview how JSON values are stored and how this can be confi
By default, JSON values are stored as follows:
| JSON type | C++ type |
| --------- | -------- |
| object | `std::map<std::string, basic_json>` |
| array | `std::vector<basic_json>` |
| null | `std::nullptr_t` |
| string | `std::string` |
| boolean | `bool` |
| JSON type | C++ type |
|-----------|-----------------------------------------------|
| object | `std::map<std::string, basic_json>` |
| array | `std::vector<basic_json>` |
| null | `std::nullptr_t` |
| string | `std::string` |
| boolean | `bool` |
| number | `std::int64_t`, `std::uint64_t`, and `double` |
Note there are three different types for numbers - when parsing JSON text, the best fitting type is chosen.

46
doc/mkdocs/docs/features/types/number_handling.md
View File

@ -80,7 +80,7 @@ number without loss of precision. If this is impossible (e.g., if the number is
### Number limits
- Any 64 bit signed or unsigned integer can be stored without loss of precision.
- Any 64-bit signed or unsigned integer can be stored without loss of precision.
- Numbers exceeding the limits of `#!c double` (i.e., numbers that after conversion via
[`std::strtod`](https://en.cppreference.com/w/cpp/string/byte/strtof) are not satisfying
[`std::isfinite`](https://en.cppreference.com/w/cpp/numeric/math/isfinite) such as `#!c 1E400`) will throw exception
@ -100,14 +100,14 @@ This is the same behavior as the code `#!c double x = 3.141592653589793238462643
The JSON number grammar allows for different ways to express zero, and this library will store zeros differently:
| Literal | Stored value and type | Serialization |
| ------- | --------------------- | ------------- |
| `0` | `#!c std::uint64_t(0)` | `0` |
| `-0` | `#!c std::int64_t(0)` | `0` |
| `0.0` | `#!c double(0.0)` | `0.0` |
| `-0.0` | `#!c double(-0.0)` | `-0.0` |
| `0E0` | `#!c double(0.0)` | `0.0` |
| `-0E0` | `#!c double(-0.0)` | `-0.0` |
| Literal | Stored value and type | Serialization |
|---------|------------------------|---------------|
| `0` | `#!c std::uint64_t(0)` | `0` |
| `-0` | `#!c std::int64_t(0)` | `0` |
| `0.0` | `#!c double(0.0)` | `0.0` |
| `-0.0` | `#!c double(-0.0)` | `-0.0` |
| `0E0` | `#!c double(0.0)` | `0.0` |
| `-0E0` | `#!c double(-0.0)` | `-0.0` |
That is, `-0` is stored as a signed integer, but the serialization does not reproduce the `-`.
@ -116,7 +116,7 @@ That is, `-0` is stored as a signed integer, but the serialization does not repr
- Integer numbers are serialized as is; that is, no scientific notation is used.
- Floating-point numbers are serialized as specified by the `#!c %g` printf modifier with
[`std::numeric_limits<double>::max_digits10`](https://en.cppreference.com/w/cpp/types/numeric_limits/max_digits10)
significant digits). The rationale is to use the shortest representation while still allow round-tripping.
significant digits. The rationale is to use the shortest representation while still allow round-tripping.
!!! hint "Notes regarding precision of floating-point numbers"
@ -283,27 +283,27 @@ the stored number:
- [`is_number_unsigned()`](../../api/basic_json/is_number_unsigned.md) returns `#!c true` for unsigned integers only
- [`is_number_float()`](../../api/basic_json/is_number_float.md) returns `#!c true` for floating-point numbers
- [`type_name()`](../../api/basic_json/type_name.md) returns `#!c "number"` for any number type
- [`type()`](../../api/basic_json/type.md) returns an different enumerator of
- [`type()`](../../api/basic_json/type.md) returns a different enumerator of
[`value_t`](../../api/basic_json/value_t.md) for all number types
| function | unsigned integer | signed integer | floating-point | string |
| -------- | ---------------- | -------------- | -------------- | ------ |
| [`is_number()`](../../api/basic_json/is_number.md) | `#!c true` | `#!c true` | `#!c true` | `#!c false` |
| [`is_number_integer()`](../../api/basic_json/is_number_integer.md) | `#!c true` | `#!c true` | `#!c false` | `#!c false` |
| [`is_number_unsigned()`](../../api/basic_json/is_number_unsigned.md) | `#!c true` | `#!c false` | `#!c false` | `#!c false` |
| [`is_number_float()`](../../api/basic_json/is_number_float.md) | `#!c false` | `#!c false` | `#!c true` | `#!c false` |
| [`type_name()`](../../api/basic_json/type_name.md) | `#!c "number"` | `#!c "number"` | `#!c "number"` | `#!c "string"` |
| [`type()`](../../api/basic_json/type.md) | `number_unsigned` | `number_integer` | `number_float` | `string` |
| function | unsigned integer | signed integer | floating-point | string |
|----------------------------------------------------------------------|-------------------|------------------|----------------|----------------|
| [`is_number()`](../../api/basic_json/is_number.md) | `#!c true` | `#!c true` | `#!c true` | `#!c false` |
| [`is_number_integer()`](../../api/basic_json/is_number_integer.md) | `#!c true` | `#!c true` | `#!c false` | `#!c false` |
| [`is_number_unsigned()`](../../api/basic_json/is_number_unsigned.md) | `#!c true` | `#!c false` | `#!c false` | `#!c false` |
| [`is_number_float()`](../../api/basic_json/is_number_float.md) | `#!c false` | `#!c false` | `#!c true` | `#!c false` |
| [`type_name()`](../../api/basic_json/type_name.md) | `#!c "number"` | `#!c "number"` | `#!c "number"` | `#!c "string"` |
| [`type()`](../../api/basic_json/type.md) | `number_unsigned` | `number_integer` | `number_float` | `string` |
### Template number types
The number types can be changed with template parameters.
| position | number type | default type | possible values |
| -------- | ----------- | ------------ | --------------- |
| 5 | signed integers | `#!c std::int64_t` | `#!c std::int32_t`, `#!c std::int16_t`, etc. |
| position | number type | default type | possible values |
|----------|-------------------|---------------------|------------------------------------------------|
| 5 | signed integers | `#!c std::int64_t` | `#!c std::int32_t`, `#!c std::int16_t`, etc. |
| 6 | unsigned integers | `#!c std::uint64_t` | `#!c std::uint32_t`, `#!c std::uint16_t`, etc. |
| 7 | floating-point | `#!c double` | `#!c float`, `#!c long double` |
| 7 | floating-point | `#!c double` | `#!c float`, `#!c long double` |
!!! info "Constraints on number types"