From 823877e426f27481c5e79122587392caf58b0d7d Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Fri, 5 Aug 2022 00:13:51 +0200 Subject: [PATCH] :lipstick: adjust line length --- docs/mkdocs/docs/api/basic_json/boolean_t.md | 4 +- .../api/basic_json/object_comparator_t.md | 3 +- docs/mkdocs/docs/api/basic_json/object_t.md | 3 +- docs/mkdocs/docs/api/basic_json/operator[].md | 6 +- .../mkdocs/docs/api/basic_json/operator_eq.md | 4 +- .../mkdocs/docs/api/basic_json/operator_ge.md | 13 ++- .../mkdocs/docs/api/basic_json/operator_ne.md | 11 +- .../docs/api/basic_json/operator_spaceship.md | 12 +-- docs/mkdocs/docs/api/basic_json/to_bjdata.md | 4 +- docs/mkdocs/docs/api/basic_json/value_t.md | 6 +- .../docs/api/macros/json_use_global_udls.md | 7 +- ...n_use_legacy_discarded_value_comparison.md | 17 ++- .../macros/nlohmann_define_type_intrusive.md | 10 +- .../nlohmann_define_type_non_intrusive.md | 9 +- docs/mkdocs/docs/api/operator_literal_json.md | 5 +- .../docs/api/operator_literal_json_pointer.md | 4 +- docs/mkdocs/docs/api/operator_ltlt.md | 3 +- .../docs/features/binary_formats/bjdata.md | 102 ++++++++---------- .../docs/features/binary_formats/cbor.md | 3 +- .../features/binary_formats/messagepack.md | 10 +- .../docs/features/binary_formats/ubjson.md | 33 +++--- .../element_access/unchecked_access.md | 3 +- .../docs/features/parsing/parse_exceptions.md | 13 ++- .../docs/features/parsing/parser_callbacks.md | 20 ++-- 24 files changed, 148 insertions(+), 157 deletions(-) diff --git a/docs/mkdocs/docs/api/basic_json/boolean_t.md b/docs/mkdocs/docs/api/basic_json/boolean_t.md index 3ca613148..7dee36bb3 100644 --- a/docs/mkdocs/docs/api/basic_json/boolean_t.md +++ b/docs/mkdocs/docs/api/basic_json/boolean_t.md @@ -6,8 +6,8 @@ using boolean_t = BooleanType; The type used to store JSON booleans. -[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two literals -`#!json true` and `#!json false`. +[RFC 8259](https://tools.ietf.org/html/rfc8259) implicitly describes a boolean as a type which differentiates the two +literals`#!json true` and `#!json false`. To store objects in C++, a type is defined by the template parameter `BooleanType` which chooses the type to use. diff --git a/docs/mkdocs/docs/api/basic_json/object_comparator_t.md b/docs/mkdocs/docs/api/basic_json/object_comparator_t.md index 496a56267..d41b98229 100644 --- a/docs/mkdocs/docs/api/basic_json/object_comparator_t.md +++ b/docs/mkdocs/docs/api/basic_json/object_comparator_t.md @@ -28,4 +28,5 @@ and [`default_object_comparator_t`](default_object_comparator_t.md) otherwise. ## Version history - Added in version 3.0.0. -- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in version 3.11.0. +- Changed to be conditionally defined as `#!cpp typename object_t::key_compare` or `default_object_comparator_t` in + version 3.11.0. diff --git a/docs/mkdocs/docs/api/basic_json/object_t.md b/docs/mkdocs/docs/api/basic_json/object_t.md index 67b3bb78c..39f68b089 100644 --- a/docs/mkdocs/docs/api/basic_json/object_t.md +++ b/docs/mkdocs/docs/api/basic_json/object_t.md @@ -90,7 +90,8 @@ Objects are stored as pointers in a `basic_json` type. That is, for any access t The order name/value pairs are added to the object is *not* preserved by the library. Therefore, iterating an object may return name/value pairs in a different order than they were originally stored. In fact, keys will be traversed in alphabetical order as `std::map` with `std::less` is used by default. Please note this behavior conforms to -[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON objects. +[RFC 8259](https://tools.ietf.org/html/rfc8259), because any order implements the specified "unordered" nature of JSON +objects. ## Examples diff --git a/docs/mkdocs/docs/api/basic_json/operator[].md b/docs/mkdocs/docs/api/basic_json/operator[].md index ebc737e4b..51dd8588c 100644 --- a/docs/mkdocs/docs/api/basic_json/operator[].md +++ b/docs/mkdocs/docs/api/basic_json/operator[].md @@ -21,7 +21,8 @@ const_reference operator[](const json_pointer& ptr) const; ``` 1. Returns a reference to the array element at specified location `idx`. -2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by value. +2. Returns a reference to the object element with specified key `key`. The non-const qualified overload takes the key by + value. 3. See 2. This overload is only available if `KeyType` is comparable with `#!cpp typename object_t::key_type` and `#!cpp typename object_comparator_t::is_transparent` denotes a type. 4. Returns a reference to the element with specified JSON pointer `ptr`. @@ -234,6 +235,7 @@ Strong exception safety: if an exception occurs, the original value stays intact ## Version history 1. Added in version 1.0.0. -2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) in version 3.11.0. +2. Added in version 1.0.0. Added overloads for `T* key` in version 1.1.0. Removed overloads for `T* key` (replaced by 3) + in version 3.11.0. 3. Added in version 3.11.0. 4. Added in version 2.0.0. diff --git a/docs/mkdocs/docs/api/basic_json/operator_eq.md b/docs/mkdocs/docs/api/basic_json/operator_eq.md index b4d61b637..a2ce6155c 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_eq.md +++ b/docs/mkdocs/docs/api/basic_json/operator_eq.md @@ -20,8 +20,8 @@ class basic_json { ``` 1. Compares two JSON values for equality according to the following rules: - - Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same - type and their stored values are the same according to their respective `operator==`. + - Two JSON values are equal if (1) neither value is discarded, or (2) they are of the same type and their stored + values are the same according to their respective `operator==`. - Integer and floating-point numbers are automatically converted before comparison. 2. Compares a JSON value and a scalar or a scalar and a JSON value for equality by converting the diff --git a/docs/mkdocs/docs/api/basic_json/operator_ge.md b/docs/mkdocs/docs/api/basic_json/operator_ge.md index 847f6ca65..d4e2fb4a5 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_ge.md +++ b/docs/mkdocs/docs/api/basic_json/operator_ge.md @@ -11,15 +11,14 @@ template bool operator>=(ScalarType lhs, const const_reference rhs) noexcept; // (2) ``` -1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs` - according to the following rules: - - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either - operand is `NaN` and the other operand is either `NaN` or any other number. +1. Compares whether one JSON value `lhs` is greater than or equal to another JSON value `rhs` according to the following + rules: + - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either operand is `NaN` and + the other operand is either `NaN` or any other number. - Otherwise, returns the result of `#!cpp !(lhs < rhs)` (see [**operator<**](operator_lt.md)). -2. Compares wether a JSON value is greater than or equal to a scalar or a scalar is greater than or - equal to a JSON value by converting the scalar to a JSON value and comparing both JSON values - according to 1. +2. Compares whether a JSON value is greater than or equal to a scalar or a scalar is greater than or equal to a JSON + value by converting the scalar to a JSON value and comparing both JSON values according to 1. ## Template parameters diff --git a/docs/mkdocs/docs/api/basic_json/operator_ne.md b/docs/mkdocs/docs/api/basic_json/operator_ne.md index f5d989b50..982a06764 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_ne.md +++ b/docs/mkdocs/docs/api/basic_json/operator_ne.md @@ -20,13 +20,12 @@ class basic_json { ``` 1. Compares two JSON values for inequality according to the following rules: - - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either - operand is `NaN` and the other operand is either `NaN` or any other number. - - Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or - `#!cpp !(*this == rhs)` (since C++20). + - The comparison always yields `#!cpp false` if (1) either operand is discarded, or (2) either operand is `NaN` and + the other operand is either `NaN` or any other number. + - Otherwise, returns the result of `#!cpp !(lhs == rhs)` (until C++20) or `#!cpp !(*this == rhs)` (since C++20). -2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the - scalar to a JSON value and comparing both JSON values according to 1. +2. Compares a JSON value and a scalar or a scalar and a JSON value for inequality by converting the scalar to a JSON + value and comparing both JSON values according to 1. ## Template parameters diff --git a/docs/mkdocs/docs/api/basic_json/operator_spaceship.md b/docs/mkdocs/docs/api/basic_json/operator_spaceship.md index f5bf1cf35..9e91d0d2d 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_spaceship.md +++ b/docs/mkdocs/docs/api/basic_json/operator_spaceship.md @@ -12,16 +12,16 @@ class basic_json { 1. 3-way compares two JSON values producing a result of type `std::partial_ordering` according to the following rules: - Two JSON values compare with a result of `std::partial_ordering::unordered` if either value is discarded. - - If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using their + - If both JSON values are of the same type, the result is produced by 3-way comparing their stored values using + their respective `operator<=>`. + - Integer and floating-point numbers are converted to their common type and then 3-way compared using their respective `operator<=>`. - - Integer and floating-point numbers are converted to their common type and then 3-way compared using their respective - `operator<=>`. - For instance, comparing an integer and a floating-point value will 3-way compare the first value convertered to + For instance, comparing an integer and a floating-point value will 3-way compare the first value converted to floating-point with the second value. - Otherwise, yields a result by comparing the type (see [`value_t`](value_t.md)). -2. 3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and 3-way - comparing both JSON values (see 1). +2. 3-way compares a JSON value and a scalar or a scalar and a JSON value by converting the scalar to a JSON value and + 3-way comparing both JSON values (see 1). ## Template parameters diff --git a/docs/mkdocs/docs/api/basic_json/to_bjdata.md b/docs/mkdocs/docs/api/basic_json/to_bjdata.md index 1ea850523..48598a5e6 100644 --- a/docs/mkdocs/docs/api/basic_json/to_bjdata.md +++ b/docs/mkdocs/docs/api/basic_json/to_bjdata.md @@ -13,8 +13,8 @@ static void to_bjdata(const basic_json& j, detail::output_adapter o, const bool use_size = false, const bool use_type = false); ``` -Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData -aims to be more compact than JSON itself, yet more efficient to parse. +Serializes a given JSON value `j` to a byte vector using the BJData (Binary JData) serialization format. BJData aims to +be more compact than JSON itself, yet more efficient to parse. 1. Returns a byte vector containing the BJData serialization. 2. Writes the BJData serialization to an output adapter. diff --git a/docs/mkdocs/docs/api/basic_json/value_t.md b/docs/mkdocs/docs/api/basic_json/value_t.md index f83574083..1505e02d0 100644 --- a/docs/mkdocs/docs/api/basic_json/value_t.md +++ b/docs/mkdocs/docs/api/basic_json/value_t.md @@ -52,10 +52,8 @@ functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_ `operator<` and `operator<=>` (since C++20) are overloaded and compare according to the ordering described above. Until C++20 all other relational and equality operators yield results according to the integer value of each - enumerator. - Since C++20 some compilers consider the _rewritten candidates_ generated from `operator<=>` during overload - resolution, while others do not. - For predictable and portable behavior use: + enumerator. Since C++20 some compilers consider the _rewritten candidates_ generated from `operator<=>` during + overload resolution, while others do not. For predictable and portable behavior use: - `operator<` or `operator<=>` when wanting to compare according to the order described above - `operator==` or `operator!=` when wanting to compare according to each enumerators integer value diff --git a/docs/mkdocs/docs/api/macros/json_use_global_udls.md b/docs/mkdocs/docs/api/macros/json_use_global_udls.md index dc9b55f62..6e42bc0ef 100644 --- a/docs/mkdocs/docs/api/macros/json_use_global_udls.md +++ b/docs/mkdocs/docs/api/macros/json_use_global_udls.md @@ -21,8 +21,7 @@ When the macro is not defined, the library will define it to its default value. !!! info "Future behavior change" - The user-defined string literals will be removed from the global namespace in the next major release of the - library. + The user-defined string literals will be removed from the global namespace in the next major release of the library. To prepare existing code, define `JSON_USE_GLOBAL_UDLS` to `0` and bring the string literals into scope where needed. Refer to any of the [string literals](#see-also) for details. @@ -30,8 +29,8 @@ When the macro is not defined, the library will define it to its default value. !!! hint "CMake option" The placement of user-defined string literals can also be controlled with the CMake option - [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`OFF` by default) - which defines `JSON_USE_GLOBAL_UDLS` accordingly. + [`JSON_GlobalUDLs`](../../integration/cmake.md#json_globaludls) (`OFF` by default) which defines + `JSON_USE_GLOBAL_UDLS` accordingly. ## Examples diff --git a/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md b/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md index bdb0a4607..bc1d1434a 100644 --- a/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md +++ b/docs/mkdocs/docs/api/macros/json_use_legacy_discarded_value_comparison.md @@ -4,8 +4,8 @@ #define JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON /* value */ ``` -This macro enables the (incorrect) legacy comparison behavior of discarded JSON values. -Possible values are `1` to enable or `0` to disable (default). +This macro enables the (incorrect) legacy comparison behavior of discarded JSON values. Possible values are `1` to +enable or `0` to disable (default). When enabled, comparisons involving at least one discarded JSON value yield results as follows: @@ -42,19 +42,16 @@ When the macro is not defined, the library will define it to its default value. `JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON`. - Overloads for the equality and relational operators emulate the legacy behavior. - Code outside your control may use either 3-way comparison or the equality and - relational operators, resulting in inconsistent and unpredictable behavior. + Code outside your control may use either 3-way comparison or the equality and relational operators, resulting in + inconsistent and unpredictable behavior. - See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way - comparison. + See [`operator<=>`](../basic_json/operator_spaceship.md) for more information on 3-way comparison. !!! warning "Deprecation" - The legacy comparison behavior is deprecated and may be removed in a future major - version release. + The legacy comparison behavior is deprecated and may be removed in a future major version release. - New code should not depend on it and existing code should try to remove or rewrite - expressions relying on it. + New code should not depend on it and existing code should try to remove or rewrite expressions relying on it. !!! hint "CMake option" diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md b/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md index 9a14ad723..afd09c6db 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_define_type_intrusive.md @@ -7,9 +7,9 @@ These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as serialization and want to use the member variable names as object keys in that object. The macro is to be defined -**inside** the class/struct to create code for. -Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members. -The first parameter is the name of the class/struct, and all remaining parameters name the members. +**inside** the class/struct to create code for. Unlike +[`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](nlohmann_define_type_non_intrusive.md), it can access private members. The first +parameter is the name of the class/struct, and all remaining parameters name the members. 1. Will use [`at`](../basic_json/at.md) during deserialization and will throw [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object. @@ -40,8 +40,8 @@ See examples below for the concrete generated code. !!! info "Prerequisites" - 1. The type `type` must be default constructible. See [How can I use `get()` for non-default constructible/non-copyable types?][GetNonDefNonCopy] - for how to overcome this limitation. + 1. The type `type` must be default constructible. See [How can I use `get()` for non-default + constructible/non-copyable types?][GetNonDefNonCopy] for how to overcome this limitation. 2. The macro must be used inside the type (class/struct). [GetNonDefNonCopy]: ../../features/arbitrary_types.md#how-can-i-use-get-for-non-default-constructiblenon-copyable-types diff --git a/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md b/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md index 28b358952..70cf934fc 100644 --- a/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md +++ b/docs/mkdocs/docs/api/macros/nlohmann_define_type_non_intrusive.md @@ -7,9 +7,9 @@ These macros can be used to simplify the serialization/deserialization of types if you want to use a JSON object as serialization and want to use the member variable names as object keys in that object. The macro is to be defined -**outside** the class/struct to create code for, but **inside** its namespace. -Unlike [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members. -The first parameter is the name of the class/struct, and all remaining parameters name the members. +**outside** the class/struct to create code for, but **inside** its namespace. Unlike +[`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](nlohmann_define_type_intrusive.md), it **cannot** access private members. The first +parameter is the name of the class/struct, and all remaining parameters name the members. 1. Will use [`at`](../basic_json/at.md) during deserialization and will throw [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a key is missing in the JSON object. @@ -103,7 +103,8 @@ See examples below for the concrete generated code. - `ns::person` is default-constructible. This is a requirement for using the macro. - `ns::person` has only public member variables. This makes `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` applicable. - - The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its namespace `ns`. + - The macro `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE_WITH_DEFAULT` is used _outside_ the class, but _inside_ its + namespace `ns`. - A missing key "age" in the deserialization does not yield an exception. Instead, the default value `-1` is used. The macro is equivalent to: diff --git a/docs/mkdocs/docs/api/operator_literal_json.md b/docs/mkdocs/docs/api/operator_literal_json.md index 6775a3e1b..cda00215c 100644 --- a/docs/mkdocs/docs/api/operator_literal_json.md +++ b/docs/mkdocs/docs/api/operator_literal_json.md @@ -15,8 +15,9 @@ using namespace nlohmann::json_literals; using namespace nlohmann::literals::json_literals; using namespace nlohmann; ``` -This is suggested to ease migration to the next major version release of the library. -See ['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. + +This is suggested to ease migration to the next major version release of the library. See +['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. ## Parameters diff --git a/docs/mkdocs/docs/api/operator_literal_json_pointer.md b/docs/mkdocs/docs/api/operator_literal_json_pointer.md index 9b79697dc..14d5378bc 100644 --- a/docs/mkdocs/docs/api/operator_literal_json_pointer.md +++ b/docs/mkdocs/docs/api/operator_literal_json_pointer.md @@ -15,8 +15,8 @@ using namespace nlohmann::json_literals; using namespace nlohmann::literals::json_literals; using namespace nlohmann; ``` -This is suggested to ease migration to the next major version release of the library. -See ['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. +This is suggested to ease migration to the next major version release of the library. See +['JSON_USE_GLOBAL_UDLS`](macros/json_use_global_udls.md#notes) for details. ## Parameters diff --git a/docs/mkdocs/docs/api/operator_ltlt.md b/docs/mkdocs/docs/api/operator_ltlt.md index ea857718b..1718b3c9e 100644 --- a/docs/mkdocs/docs/api/operator_ltlt.md +++ b/docs/mkdocs/docs/api/operator_ltlt.md @@ -35,7 +35,8 @@ the stream `o` ## Exceptions 1. Throws [`type_error.316`](../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON - value is not UTF-8 encoded. Note that unlike the [`dump`](basic_json/dump.md) member functions, no `error_handler` can be set. + value is not UTF-8 encoded. Note that unlike the [`dump`](basic_json/dump.md) member functions, no `error_handler` + can be set. 2. None. ## Complexity diff --git a/docs/mkdocs/docs/features/binary_formats/bjdata.md b/docs/mkdocs/docs/features/binary_formats/bjdata.md index 74b4499e9..25f0afa37 100644 --- a/docs/mkdocs/docs/features/binary_formats/bjdata.md +++ b/docs/mkdocs/docs/features/binary_formats/bjdata.md @@ -1,20 +1,17 @@ # BJData The [BJData format](https://neurojson.org) was derived from and improved upon -[Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12). -Specifically, it introduces an optimized array container for efficient storage -of N-dimensional packed arrays (**ND-arrays**); it also adds 4 new type markers - -`[u] - uint16`, `[m] - uint32`, `[M] - uint64` and `[h] - float16` - to -unambigiously map common binary numeric types; furthermore, it uses little-endian -(LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid +[Universal Binary JSON(UBJSON)](https://ubjson.org) specification (Draft 12). Specifically, it introduces an optimized +array container for efficient storage of N-dimensional packed arrays (**ND-arrays**); it also adds 4 new type markers - +`[u] - uint16`, `[m] - uint32`, `[M] - uint64` and `[h] - float16` - to unambiguously map common binary numeric types; +furthermore, it uses little-endian (LE) to store all numerics instead of big-endian (BE) as in UBJSON to avoid unnecessary conversions on commonly available platforms. -Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and -UBJSON demonstrate a rare combination of being both binary and **quasi-human-readable**. This -is because all semantic elements in BJData and UBJSON, including the data-type markers -and name/string types are directly human-readable. Data stored in the BJData/UBJSON format -are not only compact in size, fast to read/write, but also can be directly searched -or read using simple processing. +Compared to other binary JSON-like formats such as MessagePack and CBOR, both BJData and UBJSON demonstrate a rare +combination of being both binary and **quasi-human-readable**. This is because all semantic elements in BJData and +UBJSON, including the data-type markers and name/string types are directly human-readable. Data stored in the +BJData/UBJSON format are not only compact in size, fast to read/write, but also can be directly searched or read using +simple processing. !!! abstract "References" @@ -74,48 +71,40 @@ The library uses the following mapping from JSON values types to BJData types ac !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are - serialized properly. This behavior differs from the `dump()` - function which serializes NaN or Infinity to `null`. - + If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the + `dump()` function which serializes NaN or Infinity to `#!json null`. !!! info "Endianness" - A breaking difference between BJData and UBJSON is the endianness - of numerical values. In BJData, all numerical data types (integers - `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) - byte order as opposed to big-endian as used by UBJSON. Adopting LE - to store numeric records avoids unnecessary byte swapping on most modern - computers where LE is used as the default byte order. + A breaking difference between BJData and UBJSON is the endianness of numerical values. In BJData, all numerical data + types (integers `UiuImlML` and floating-point values `hdD`) are stored in the little-endian (LE) byte order as + opposed to big-endian as used by UBJSON. Adopting LE to store numeric records avoids unnecessary byte swapping on + most modern computers where LE is used as the default byte order. !!! info "Optimized formats" Optimized formats for containers are supported via two parameters of [`to_bjdata`](../../api/basic_json/to_bjdata.md): - - Parameter `use_size` adds size information to the beginning of a container and - removes the closing marker. - - Parameter `use_type` further checks whether all elements of a container have the - same type and adds the type marker to the beginning of the container. - The `use_type` parameter must only be used together with `use_size = true`. + - Parameter `use_size` adds size information to the beginning of a container and removes the closing marker. + - Parameter `use_type` further checks whether all elements of a container have the same type and adds the type + marker to the beginning of the container. The `use_type` parameter must only be used together with + `use_size = true`. - Note that `use_size = true` alone may result in larger representations - - the benefit of this parameter is that the receiving side is - immediately informed of the number of elements in the container. + Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the + receiving side is immediately informed of the number of elements in the container. !!! info "ND-array optimized format" - BJData extends UBJSON's optimized array **size** marker to support ND-arrays of - uniform numerical data types (referred to as *packed arrays*). - For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored - as nested optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, - can be further compressed in BJData to `[$U#[$i#i2 2 3 1 2 3 4 5 6` - or `[$U#[i2 i3] 1 2 3 4 5 6`. + BJData extends UBJSON's optimized array **size** marker to support ND-arrays of uniform numerical data types + (referred to as *packed arrays*). For example, the 2-D `uint8` integer array `[[1,2],[3,4],[5,6]]`, stored as nested + optimized array in UBJSON `[ [$U#i2 1 2 [$U#i2 3 4 [$U#i2 5 6 ]`, can be further compressed in BJData to + `[$U#[$i#i2 2 3 1 2 3 4 5 6` or `[$U#[i2 i3] 1 2 3 4 5 6`. - To maintina type and size information, ND-arrays are converted to JSON objects following the - **annotated array format** (defined in the [JData specification (Draft 3)][JDataAAFmt]), - when parsed using [`from_bjdata`](../../api/basic_json/from_bjdata.md). - For example, the above 2-D `uint8` array can be parsed and accessed as + To maintina type and size information, ND-arrays are converted to JSON objects following the **annotated array + format** (defined in the [JData specification (Draft 3)][JDataAAFmt]), when parsed using + [`from_bjdata`](../../api/basic_json/from_bjdata.md). For example, the above 2-D `uint8` array can be parsed and + accessed as ```json { @@ -126,34 +115,28 @@ The library uses the following mapping from JSON values types to BJData types ac ``` Likewise, when a JSON object in the above form is serialzed using - [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted - into a compact BJData ND-array. The only exception is, that when the 1-dimensional - vector stored in `"_ArraySize_"` contains a single integer or two integers with one - being 1, a regular 1-D optimized array is generated. + [`to_bjdata`](../../api/basic_json/to_bjdata.md), it is automatically converted into a compact BJData ND-array. The + only exception is, that when the 1-dimensional vector stored in `"_ArraySize_"` contains a single integer or two + integers with one being 1, a regular 1-D optimized array is generated. - The current version of this library does not yet support automatic detection of and - conversion from a nested JSON array input to a BJData ND-array. + The current version of this library does not yet support automatic detection of and conversion from a nested JSON + array input to a BJData ND-array. [JDataAAFmt]: https://github.com/NeuroJSON/jdata/blob/master/JData_specification.md#annotated-storage-of-n-d-arrays) !!! info "Restrictions in optimized data types for arrays and objects" - Due to diminished space saving, hampered readability, and increased - security risks, in BJData, the allowed data types following the `$` marker - in an optimized array and object container are restricted to - **non-zero-fixed-length** data types. Therefore, the valid optimized - type markers can only be one of `UiuImlMLhdDC`. This also means other - variable (`[{SH`) or zero-length types (`TFN`) can not be used in an - optimized array or object in BJData. + Due to diminished space saving, hampered readability, and increased security risks, in BJData, the allowed data + types following the `$` marker in an optimized array and object container are restricted to + **non-zero-fixed-length** data types. Therefore, the valid optimized type markers can only be one of `UiuImlMLhdDC`. + This also means other variable (`[{SH`) or zero-length types (`TFN`) can not be used in an optimized array or object + in BJData. !!! info "Binary values" - If the JSON data contains the binary type, the value stored is a list - of integers, as suggested by the BJData documentation. In particular, - this means that the serialization and the deserialization of JSON - containing binary values into BJData and back will result in a - different JSON object. - + If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the BJData + documentation. In particular, this means that the serialization and the deserialization of JSON containing binary + values into BJData and back will result in a different JSON object. ??? example @@ -198,7 +181,6 @@ The library maps BJData types to JSON value types as follows: The mapping is **complete** in the sense that any BJData value can be converted to a JSON value. - ??? example ```cpp diff --git a/docs/mkdocs/docs/features/binary_formats/cbor.md b/docs/mkdocs/docs/features/binary_formats/cbor.md index 280bf577f..3db25e2fb 100644 --- a/docs/mkdocs/docs/features/binary_formats/cbor.md +++ b/docs/mkdocs/docs/features/binary_formats/cbor.md @@ -11,7 +11,8 @@ small code size, fairly small message size, and extensibility without the need f ## Serialization -The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification (RFC 7049): +The library uses the following mapping from JSON values types to CBOR types according to the CBOR specification +([RFC 7049](https://www.rfc-editor.org/rfc/rfc7049.html)): | JSON value type | value/range | CBOR type | first byte | |-----------------|--------------------------------------------|-----------------------------------|------------| diff --git a/docs/mkdocs/docs/features/binary_formats/messagepack.md b/docs/mkdocs/docs/features/binary_formats/messagepack.md index b0139b40c..4b6951dd3 100644 --- a/docs/mkdocs/docs/features/binary_formats/messagepack.md +++ b/docs/mkdocs/docs/features/binary_formats/messagepack.md @@ -1,6 +1,8 @@ # MessagePack -MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one extra byte in addition to the strings themselves. +MessagePack is an efficient binary serialization format. It lets you exchange data among multiple languages like JSON. +But it's faster and smaller. Small integers are encoded into a single byte, and typical short strings require only one +extra byte in addition to the strings themselves. !!! abstract "References" @@ -9,7 +11,8 @@ MessagePack is an efficient binary serialization format. It lets you exchange da ## Serialization -The library uses the following mapping from JSON values types to MessagePack types according to the MessagePack specification: +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 | |-----------------|------------------------------------------|------------------|------------| @@ -64,7 +67,8 @@ The library uses the following mapping from JSON values types to MessagePack typ !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or Infinity to `null`. + If NaN or Infinity are stored inside a JSON number, they are serialized properly. function which serializes NaN or + Infinity to `null`. ??? example diff --git a/docs/mkdocs/docs/features/binary_formats/ubjson.md b/docs/mkdocs/docs/features/binary_formats/ubjson.md index 509d9f577..8c8cc1c8b 100644 --- a/docs/mkdocs/docs/features/binary_formats/ubjson.md +++ b/docs/mkdocs/docs/features/binary_formats/ubjson.md @@ -1,6 +1,7 @@ # UBJSON -Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to achieve the generality of JSON, combined with being much easier to process than JSON. +Universal Binary JSON (UBJSON) is a binary form directly imitating JSON, but requiring fewer bytes of data. It aims to +achieve the generality of JSON, combined with being much easier to process than JSON. !!! abstract "References" @@ -55,31 +56,24 @@ The library uses the following mapping from JSON values types to UBJSON types ac !!! info "NaN/infinity handling" - If NaN or Infinity are stored inside a JSON number, they are - serialized properly. This behavior differs from the `dump()` - function which serializes NaN or Infinity to `null`. + If NaN or Infinity are stored inside a JSON number, they are serialized properly. This behavior differs from the + `dump()` function which serializes NaN or Infinity to `null`. !!! info "Optimized formats" - The optimized formats for containers are supported: Parameter - `use_size` adds size information to the beginning of a container and - removes the closing marker. Parameter `use_type` further checks - whether all elements of a container have the same type and adds the - type marker to the beginning of the container. The `use_type` - parameter must only be used together with `use_size = true`. + The optimized formats for containers are supported: Parameter `use_size` adds size information to the beginning of a + container and removes the closing marker. Parameter `use_type` further checks whether all elements of a container + have the same type and adds the type marker to the beginning of the container. The `use_type` parameter must only be + used together with `use_size = true`. - Note that `use_size = true` alone may result in larger representations - - the benefit of this parameter is that the receiving side is - immediately informed on the number of elements of the container. + Note that `use_size = true` alone may result in larger representations - the benefit of this parameter is that the + receiving side is immediately informed on the number of elements of the container. !!! info "Binary values" - If the JSON data contains the binary type, the value stored is a list - of integers, as suggested by the UBJSON documentation. In particular, - this means that serialization and the deserialization of a JSON - containing binary values into UBJSON and back will result in a - different JSON object. - + If the JSON data contains the binary type, the value stored is a list of integers, as suggested by the UBJSON + documentation. In particular, this means that serialization and the deserialization of a JSON containing binary + values into UBJSON and back will result in a different JSON object. ??? example @@ -119,7 +113,6 @@ The library maps UBJSON types to JSON value types as follows: The mapping is **complete** in the sense that any UBJSON value can be converted to a JSON value. - ??? example ```cpp diff --git a/docs/mkdocs/docs/features/element_access/unchecked_access.md b/docs/mkdocs/docs/features/element_access/unchecked_access.md index 1bdea94e7..39f06dc9f 100644 --- a/docs/mkdocs/docs/features/element_access/unchecked_access.md +++ b/docs/mkdocs/docs/features/element_access/unchecked_access.md @@ -99,7 +99,8 @@ that the passed index is the new maximal index. Intermediate values are filled w !!! failure "Exceptions" - `operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown. + `operator[]` can only be used with objects (with a string argument) or with arrays (with a numeric argument). For + other types, a [`basic_json::type_error`](../../home/exceptions.md#jsonexceptiontype_error305) is thrown. ## Summary diff --git a/docs/mkdocs/docs/features/parsing/parse_exceptions.md b/docs/mkdocs/docs/features/parsing/parse_exceptions.md index 879dab0d3..fe41c326c 100644 --- a/docs/mkdocs/docs/features/parsing/parse_exceptions.md +++ b/docs/mkdocs/docs/features/parsing/parse_exceptions.md @@ -1,6 +1,10 @@ # Parsing and Exceptions -When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. This exception contains the position in the input where the error occurred, together with a diagnostic message and the last read input token. The exceptions page contains a [list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like +When the input is not valid JSON, an exception of type [`parse_error`](../../home/exceptions.md#parse-errors) is thrown. +This exception contains the position in the input where the error occurred, together with a diagnostic message and the +last read input token. The exceptions page contains a +[list of examples for parse error exceptions](../../home/exceptions.md#parse-errors). In case you process untrusted +input, always enclose your code with a `#!cpp try`/`#!cpp catch` block, like ```cpp json j; @@ -19,7 +23,9 @@ In case exceptions are undesired or not supported by the environment, there are ## Switch off exceptions -The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned (`#!cpp false`). +The `parse()` function accepts as last parameter a `#!cpp bool` variable `allow_exceptions` which controls whether an +exception is thrown when a parse error occurs (`#!cpp true`, default) or whether a discarded value should be returned +(`#!cpp false`). ```cpp json j = json::parse(my_input, nullptr, false); @@ -33,7 +39,8 @@ Note there is no diagnostic information available in this scenario. ## Use accept() function -Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating whether the input is valid JSON. +Alternatively, function `accept()` can be used which does not return a `json` value, but a `#!cpp bool` indicating +whether the input is valid JSON. ```cpp if (!json::accept(my_input)) diff --git a/docs/mkdocs/docs/features/parsing/parser_callbacks.md b/docs/mkdocs/docs/features/parsing/parser_callbacks.md index 12136f57c..da17e58fe 100644 --- a/docs/mkdocs/docs/features/parsing/parser_callbacks.md +++ b/docs/mkdocs/docs/features/parsing/parser_callbacks.md @@ -2,9 +2,10 @@ ## Overview -With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is called on certain events -(passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and context JSON value `parsed`. The return value of the -callback function is a boolean indicating whether the element that emitted the callback shall be kept or not. +With a parser callback function, the result of parsing a JSON text can be influenced. When passed to `parse`, it is +called on certain events (passed as `parse_event_t` via parameter `event`) with a set recursion depth `depth` and +context JSON value `parsed`. The return value of the callback function is a boolean indicating whether the element that +emitted the callback shall be kept or not. The type of the callback function is: @@ -17,8 +18,8 @@ using parser_callback_t = ## Callback event types -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`. +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` | |-------------------------------|-----------------------------------------------------------|-------------------------------------------|----------------------------------| @@ -59,10 +60,13 @@ of the parameters `depth`, `event`, and `parsed`. ## Return value -Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which function was called: +Discarding a value (i.e., returning `#!c false`) has different effects depending on the context in which function was +called: -- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never read. -- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the top-level element is skipped. +- Discarded values in structured types are skipped. That is, the parser will behave as if the discarded value was never + read. +- In case a value outside a structured type is skipped, it is replaced with `#!json null`. This case happens if the + top-level element is skipped. ??? example