From 82c79ab41d8236c50fb9d02247409adbedf6b629 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 29 Dec 2021 00:02:56 +0100 Subject: [PATCH] :memo: fix Markdown tables --- doc/mkdocs/docs/api/basic_json/basic_json.md | 18 +- doc/mkdocs/docs/api/basic_json/clear.md | 18 +- doc/mkdocs/docs/api/basic_json/empty.md | 18 +- doc/mkdocs/docs/api/basic_json/index.md | 68 ++++--- doc/mkdocs/docs/api/basic_json/max_size.md | 18 +- doc/mkdocs/docs/api/basic_json/meta.md | 16 +- .../docs/api/basic_json/operator_value_t.md | 24 +-- .../docs/api/basic_json/parser_callback_t.md | 16 +- doc/mkdocs/docs/api/basic_json/size.md | 18 +- doc/mkdocs/docs/api/basic_json/type.md | 24 +-- doc/mkdocs/docs/api/basic_json/type_name.md | 20 +-- .../docs/features/binary_formats/bson.md | 74 ++++---- .../docs/features/binary_formats/cbor.md | 166 +++++++++--------- .../docs/features/binary_formats/index.md | 6 +- .../features/binary_formats/messagepack.md | 146 +++++++-------- .../docs/features/binary_formats/ubjson.md | 80 ++++----- .../features/element_access/checked_access.md | 10 +- .../element_access/unchecked_access.md | 12 +- doc/mkdocs/docs/features/iterators.md | 2 +- .../docs/features/parsing/parser_callbacks.md | 16 +- doc/mkdocs/docs/features/types/index.md | 14 +- .../docs/features/types/number_handling.md | 40 ++--- 22 files changed, 420 insertions(+), 404 deletions(-) diff --git a/doc/mkdocs/docs/api/basic_json/basic_json.md b/doc/mkdocs/docs/api/basic_json/basic_json.md index 27d6ee821..ab3fea470 100644 --- a/doc/mkdocs/docs/api/basic_json/basic_json.md +++ b/doc/mkdocs/docs/api/basic_json/basic_json.md @@ -39,15 +39,15 @@ basic_json(basic_json&& other) noexcept; 1. Create an empty JSON value with a given type. The value will be default initialized with an empty value which depends on the type: - Value type | initial value - ----------- | ------------- - null | `#!json null` - boolean | `#!json false` - string | `#!json ""` - number | `#!json 0` - object | `#!json {}` - array | `#!json []` - binary | empty array + | Value type | initial value | + |------------|----------------| + | null | `#!json null` | + | boolean | `#!json false` | + | string | `#!json ""` | + | number | `#!json 0` | + | object | `#!json {}` | + | array | `#!json []` | + | binary | empty array | The postcondition of this constructor can be restored by calling [`clear()`](clear.md). diff --git a/doc/mkdocs/docs/api/basic_json/clear.md b/doc/mkdocs/docs/api/basic_json/clear.md index 00367c838..ff04b08e6 100644 --- a/doc/mkdocs/docs/api/basic_json/clear.md +++ b/doc/mkdocs/docs/api/basic_json/clear.md @@ -7,15 +7,15 @@ void clear() noexcept; Clears the content of a JSON value and resets it to the default value as if [`basic_json(value_t)`](basic_json.md) would have been called with the current value type from [`type()`](type.md): -Value type | initial value ------------ | ------------- -null | `null` -boolean | `false` -string | `""` -number | `0` -binary | An empty byte vector -object | `{}` -array | `[]` +| Value type | initial value | +|------------|----------------------| +| null | `null` | +| boolean | `false` | +| string | `""` | +| number | `0` | +| binary | An empty byte vector | +| object | `{}` | +| array | `[]` | Has the same effect as calling diff --git a/doc/mkdocs/docs/api/basic_json/empty.md b/doc/mkdocs/docs/api/basic_json/empty.md index e914e1689..26bf6e9aa 100644 --- a/doc/mkdocs/docs/api/basic_json/empty.md +++ b/doc/mkdocs/docs/api/basic_json/empty.md @@ -10,15 +10,15 @@ Checks if a JSON value has no elements (i.e. whether its [`size()`](size.md) is The return value depends on the different types and is defined as follows: -Value type | return value ------------ | ------------- -null | `#!cpp true` -boolean | `#!cpp false` -string | `#!cpp false` -number | `#!cpp false` -binary | `#!cpp false` -object | result of function `object_t::empty()` -array | result of function `array_t::empty()` +| Value type | return value | +|------------|----------------------------------------| +| null | `#!cpp true` | +| boolean | `#!cpp false` | +| string | `#!cpp false` | +| number | `#!cpp false` | +| binary | `#!cpp false` | +| object | result of function `object_t::empty()` | +| array | result of function `array_t::empty()` | ## Exception safety diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 9739b216f..eb90ac6ec 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -20,18 +20,18 @@ class basic_json; ## Template parameters -| Template parameter | Description | Derived type | -| -------------------- | ----------- | ------------ | -| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) | -| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) | -| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) | -| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) | -| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) | -| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) | -| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) | -| `AllocatorType` | type of the allocator to use | | -| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) | -| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) | +| Template parameter | Description | Derived type | +|----------------------|---------------------------------------------------------------------------|---------------------------------------------| +| `ObjectType` | type for JSON objects | [`object_t`](object_t.md) | +| `ArrayType` | type for JSON arrays | [`array_t`](array_t.md) | +| `StringType` | type for JSON strings and object keys | [`string_t`](string_t.md) | +| `BooleanType` | type for JSON booleans | [`boolean_t`](boolean_t.md) | +| `NumberIntegerType` | type for JSON integer numbers | [`number_integer_t`](number_integer_t.md) | +| `NumberUnsignedType` | type for JSON unsigned integer numbers | [`number_unsigned_t`](number_unsigned_t.md) | +| `NumberFloatType` | type for JSON floating-point numbers | [`number_float_t`](number_float_t.md) | +| `AllocatorType` | type of the allocator to use | | +| `JSONSerializer` | the serializer to resolve internal calls to `to_json()` and `from_json()` | [`json_serializer`](json_serializer.md) | +| `BinaryType` | type for binary arrays | [`binary_t`](binary_t.md) | ## Specializations @@ -107,21 +107,21 @@ The class satisfies the following concept requirements: ### Container types -| Type | Definition | -| ------------------------ | ---------- | -| `value_type` | `#!cpp basic_json` | -| `reference` | `#!cpp value_type&` | -| `const_reference` | `#!cpp const value_type&` | -| `difference_type` | `#!cpp std::ptrdiff_t` | -| `size_type` | `#!cpp std::size_t` | -| `allocator_type` | `#!cpp AllocatorType` | -| `pointer` | `#!cpp std::allocator_traits::pointer` | -| `const_pointer` | `#!cpp std::allocator_traits::const_pointer` | -| `iterator` | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) | +| Type | Definition | +|--------------------------|-----------------------------------------------------------------------------------------------------------| +| `value_type` | `#!cpp basic_json` | +| `reference` | `#!cpp value_type&` | +| `const_reference` | `#!cpp const value_type&` | +| `difference_type` | `#!cpp std::ptrdiff_t` | +| `size_type` | `#!cpp std::size_t` | +| `allocator_type` | `#!cpp AllocatorType` | +| `pointer` | `#!cpp std::allocator_traits::pointer` | +| `const_pointer` | `#!cpp std::allocator_traits::const_pointer` | +| `iterator` | [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) | | `const_iterator` | constant [LegacyBidirectionalIterator](https://en.cppreference.com/w/cpp/named_req/BidirectionalIterator) | -| `reverse_iterator` | reverse iterator, derived from `iterator` | -| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` | -| `iteration_proxy` | helper type for [`items`](items.md) function | +| `reverse_iterator` | reverse iterator, derived from `iterator` | +| `const_reverse_iterator` | reverse iterator, derived from `const_iterator` | +| `iteration_proxy` | helper type for [`items`](items.md) function | ### JSON value data types @@ -292,6 +292,22 @@ Access to the JSON value - [**std::hash<basic_json>**](std_hash.md) - return a hash value for a JSON object - [**std::swap<basic_json>**](std_swap.md) - exchanges the values of two JSON objects +## Example + +??? example + + The example shows how the library is used. + + ```cpp + --8<-- "examples/README.cpp" + ``` + + Output: + + ```json + --8<-- "examples/README.output" + ``` + ## See also - [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259) diff --git a/doc/mkdocs/docs/api/basic_json/max_size.md b/doc/mkdocs/docs/api/basic_json/max_size.md index b07500224..31339dbe9 100644 --- a/doc/mkdocs/docs/api/basic_json/max_size.md +++ b/doc/mkdocs/docs/api/basic_json/max_size.md @@ -11,15 +11,15 @@ i.e. `std::distance(begin(), end())` for the JSON value. The return value depends on the different types and is defined as follows: -Value type | return value ------------ | ------------- -null | `0` (same as [`size()`](size.md)) -boolean | `1` (same as [`size()`](size.md)) -string | `1` (same as [`size()`](size.md)) -number | `1` (same as [`size()`](size.md)) -binary | `1` (same as [`size()`](size.md)) -object | result of function `object_t::max_size()` -array | result of function `array_t::max_size()` +| Value type | return value | +|------------|-------------------------------------------| +| null | `0` (same as [`size()`](size.md)) | +| boolean | `1` (same as [`size()`](size.md)) | +| string | `1` (same as [`size()`](size.md)) | +| number | `1` (same as [`size()`](size.md)) | +| binary | `1` (same as [`size()`](size.md)) | +| object | result of function `object_t::max_size()` | +| array | result of function `array_t::max_size()` | ## Exception safety diff --git a/doc/mkdocs/docs/api/basic_json/meta.md b/doc/mkdocs/docs/api/basic_json/meta.md index 6372dd054..e2b312e0c 100644 --- a/doc/mkdocs/docs/api/basic_json/meta.md +++ b/doc/mkdocs/docs/api/basic_json/meta.md @@ -11,14 +11,14 @@ the platform and compiler. JSON object holding version information -key | description ------------ | --------------- -`compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version). -`copyright` | The copyright line for the library as string. -`name` | The name of the library as string. -`platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`. -`url` | The URL of the project as string. -`version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string). +| key | description | +|-------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| +| `compiler` | Information on the used compiler. It is an object with the following keys: `c++` (the used C++ standard), `family` (the compiler family; possible values are `clang`, `icc`, `gcc`, `ilecpp`, `msvc`, `pgcpp`, `sunpro`, and `unknown`), and `version` (the compiler version). | +| `copyright` | The copyright line for the library as string. | +| `name` | The name of the library as string. | +| `platform` | The used platform as string. Possible values are `win32`, `linux`, `apple`, `unix`, and `unknown`. | +| `url` | The URL of the project as string. | +| `version` | The version of the library. It is an object with the following keys: `major`, `minor`, and `patch` as defined by [Semantic Versioning](http://semver.org), and `string` (the version string). | ## Exception safety diff --git a/doc/mkdocs/docs/api/basic_json/operator_value_t.md b/doc/mkdocs/docs/api/basic_json/operator_value_t.md index 470effc92..0f08f42b0 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_value_t.md +++ b/doc/mkdocs/docs/api/basic_json/operator_value_t.md @@ -10,18 +10,18 @@ Return the type of the JSON value as a value from the [`value_t`](value_t.md) en the type of the JSON value -Value type | return value -------------------------- | ------------------------- -`#!json null` | `value_t::null` -boolean | `value_t::boolean` -string | `value_t::string` -number (integer) | `value_t::number_integer` -number (unsigned integer) | `value_t::number_unsigned` -number (floating-point) | `value_t::number_float` -object | `value_t::object` -array | `value_t::array` -binary | `value_t::binary` -discarded | `value_t::discarded` +| Value type | return value | +|---------------------------|----------------------------| +| `#!json null` | `value_t::null` | +| boolean | `value_t::boolean` | +| string | `value_t::string` | +| number (integer) | `value_t::number_integer` | +| number (unsigned integer) | `value_t::number_unsigned` | +| number (floating-point) | `value_t::number_float` | +| object | `value_t::object` | +| array | `value_t::array` | +| binary | `value_t::binary` | +| discarded | `value_t::discarded` | ## Exception safety diff --git a/doc/mkdocs/docs/api/basic_json/parser_callback_t.md b/doc/mkdocs/docs/api/basic_json/parser_callback_t.md index f5400ed22..e10402ea9 100644 --- a/doc/mkdocs/docs/api/basic_json/parser_callback_t.md +++ b/doc/mkdocs/docs/api/basic_json/parser_callback_t.md @@ -14,14 +14,14 @@ is a boolean indicating whether the element that emitted the callback shall be k 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 when certain parse events are triggered](../../images/callback_events.png) diff --git a/doc/mkdocs/docs/api/basic_json/size.md b/doc/mkdocs/docs/api/basic_json/size.md index 9d97bb6f6..4ff582db2 100644 --- a/doc/mkdocs/docs/api/basic_json/size.md +++ b/doc/mkdocs/docs/api/basic_json/size.md @@ -10,15 +10,15 @@ Returns the number of elements in a JSON value. The return value depends on the different types and is defined as follows: -Value type | return value ------------ | ------------- -null | `0` -boolean | `1` -string | `1` -number | `1` -binary | `1` -object | result of function object_t::size() -array | result of function array_t::size() +| Value type | return value | +|------------|-------------------------------------| +| null | `0` | +| boolean | `1` | +| string | `1` | +| number | `1` | +| binary | `1` | +| object | result of function object_t::size() | +| array | result of function array_t::size() | ## Exception safety diff --git a/doc/mkdocs/docs/api/basic_json/type.md b/doc/mkdocs/docs/api/basic_json/type.md index 32c3927cd..deedd6b69 100644 --- a/doc/mkdocs/docs/api/basic_json/type.md +++ b/doc/mkdocs/docs/api/basic_json/type.md @@ -10,18 +10,18 @@ Return the type of the JSON value as a value from the [`value_t`](value_t.md) en the type of the JSON value -Value type | return value -------------------------- | ------------------------- -`#!json null` | `value_t::null` -boolean | `value_t::boolean` -string | `value_t::string` -number (integer) | `value_t::number_integer` -number (unsigned integer) | `value_t::number_unsigned` -number (floating-point) | `value_t::number_float` -object | `value_t::object` -array | `value_t::array` -binary | `value_t::binary` -discarded | `value_t::discarded` +| Value type | return value | +|---------------------------|----------------------------| +| `#!json null` | `value_t::null` | +| boolean | `value_t::boolean` | +| string | `value_t::string` | +| number (integer) | `value_t::number_integer` | +| number (unsigned integer) | `value_t::number_unsigned` | +| number (floating-point) | `value_t::number_float` | +| object | `value_t::object` | +| array | `value_t::array` | +| binary | `value_t::binary` | +| discarded | `value_t::discarded` | ## Exception safety diff --git a/doc/mkdocs/docs/api/basic_json/type_name.md b/doc/mkdocs/docs/api/basic_json/type_name.md index d9e8cf012..389c2b1dd 100644 --- a/doc/mkdocs/docs/api/basic_json/type_name.md +++ b/doc/mkdocs/docs/api/basic_json/type_name.md @@ -11,16 +11,16 @@ wrong JSON type. a string representation of the type ([`value_t`](value_t.md)): -Value type | return value --------------------------------------------------- | ------------------------- -`#!json null` | `"null"` -boolean | `"boolean"` -string | `"string"` -number (integer, unsigned integer, floating-point) | `"number"` -object | `"object"` -array | `"array"` -binary | `"binary"` -discarded | `"discarded"` +| Value type | return value | +|----------------------------------------------------|---------------| +| `#!json null` | `"null"` | +| boolean | `"boolean"` | +| string | `"string"` | +| number (integer, unsigned integer, floating-point) | `"number"` | +| object | `"object"` | +| array | `"array"` | +| binary | `"binary"` | +| discarded | `"discarded"` | ## Exception safety diff --git a/doc/mkdocs/docs/features/binary_formats/bson.md b/doc/mkdocs/docs/features/binary_formats/bson.md index 4487d26e1..8c7716d9b 100644 --- a/doc/mkdocs/docs/features/binary_formats/bson.md +++ b/doc/mkdocs/docs/features/binary_formats/bson.md @@ -14,21 +14,21 @@ representation of data types that are not part of the JSON spec. For example, BS 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" @@ -55,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" diff --git a/doc/mkdocs/docs/features/binary_formats/cbor.md b/doc/mkdocs/docs/features/binary_formats/cbor.md index a1824eb97..280bf577f 100644 --- a/doc/mkdocs/docs/features/binary_formats/cbor.md +++ b/doc/mkdocs/docs/features/binary_formats/cbor.md @@ -13,48 +13,48 @@ small code size, fairly small message size, and extensibility without the need f 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. @@ -105,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" diff --git a/doc/mkdocs/docs/features/binary_formats/index.md b/doc/mkdocs/docs/features/binary_formats/index.md index e115e02ba..3a969a5dc 100644 --- a/doc/mkdocs/docs/features/binary_formats/index.md +++ b/doc/mkdocs/docs/features/binary_formats/index.md @@ -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 % | diff --git a/doc/mkdocs/docs/features/binary_formats/messagepack.md b/doc/mkdocs/docs/features/binary_formats/messagepack.md index 3e041bb70..b0139b40c 100644 --- a/doc/mkdocs/docs/features/binary_formats/messagepack.md +++ b/doc/mkdocs/docs/features/binary_formats/messagepack.md @@ -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 diff --git a/doc/mkdocs/docs/features/binary_formats/ubjson.md b/doc/mkdocs/docs/features/binary_formats/ubjson.md index 050b4ec59..509d9f577 100644 --- a/doc/mkdocs/docs/features/binary_formats/ubjson.md +++ b/doc/mkdocs/docs/features/binary_formats/ubjson.md @@ -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" diff --git a/doc/mkdocs/docs/features/element_access/checked_access.md b/doc/mkdocs/docs/features/element_access/checked_access.md index fcbfed09c..fd444bebe 100644 --- a/doc/mkdocs/docs/features/element_access/checked_access.md +++ b/doc/mkdocs/docs/features/element_access/checked_access.md @@ -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 | diff --git a/doc/mkdocs/docs/features/element_access/unchecked_access.md b/doc/mkdocs/docs/features/element_access/unchecked_access.md index 81ddabd13..bb7228777 100644 --- a/doc/mkdocs/docs/features/element_access/unchecked_access.md +++ b/doc/mkdocs/docs/features/element_access/unchecked_access.md @@ -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 | diff --git a/doc/mkdocs/docs/features/iterators.md b/doc/mkdocs/docs/features/iterators.md index 8432e7b39..46f28f189 100644 --- a/doc/mkdocs/docs/features/iterators.md +++ b/doc/mkdocs/docs/features/iterators.md @@ -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 | diff --git a/doc/mkdocs/docs/features/parsing/parser_callbacks.md b/doc/mkdocs/docs/features/parsing/parser_callbacks.md index dbf88849f..12136f57c 100644 --- a/doc/mkdocs/docs/features/parsing/parser_callbacks.md +++ b/doc/mkdocs/docs/features/parsing/parser_callbacks.md @@ -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 diff --git a/doc/mkdocs/docs/features/types/index.md b/doc/mkdocs/docs/features/types/index.md index f52d35558..d9dfcc29a 100644 --- a/doc/mkdocs/docs/features/types/index.md +++ b/doc/mkdocs/docs/features/types/index.md @@ -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` | -| array | `std::vector` | -| null | `std::nullptr_t` | -| string | `std::string` | -| boolean | `bool` | +| JSON type | C++ type | +|-----------|-----------------------------------------------| +| object | `std::map` | +| array | `std::vector` | +| 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. diff --git a/doc/mkdocs/docs/features/types/number_handling.md b/doc/mkdocs/docs/features/types/number_handling.md index 83819e2bf..dd6507353 100644 --- a/doc/mkdocs/docs/features/types/number_handling.md +++ b/doc/mkdocs/docs/features/types/number_handling.md @@ -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 `-`. @@ -286,24 +286,24 @@ the stored number: - [`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"