From d54fd353553b64f6ede679053e7f7b036b2c7a44 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Fri, 5 Nov 2021 14:26:19 +0100 Subject: [PATCH] :rotating_light: fix linter warnings --- .../docs/api/adl_serializer/from_json.md | 4 ++ doc/mkdocs/docs/api/adl_serializer/index.md | 4 ++ doc/mkdocs/docs/api/adl_serializer/to_json.md | 4 ++ doc/mkdocs/docs/api/basic_json/at.md | 10 +-- doc/mkdocs/docs/api/basic_json/back.md | 12 ++-- doc/mkdocs/docs/api/basic_json/basic_json.md | 34 +++++------ doc/mkdocs/docs/api/basic_json/begin.md | 2 +- doc/mkdocs/docs/api/basic_json/cbegin.md | 2 +- doc/mkdocs/docs/api/basic_json/cend.md | 2 +- doc/mkdocs/docs/api/basic_json/clear.md | 2 +- doc/mkdocs/docs/api/basic_json/contains.md | 2 +- doc/mkdocs/docs/api/basic_json/count.md | 2 +- doc/mkdocs/docs/api/basic_json/crbegin.md | 2 +- doc/mkdocs/docs/api/basic_json/crend.md | 2 +- doc/mkdocs/docs/api/basic_json/diff.md | 4 +- doc/mkdocs/docs/api/basic_json/dump.md | 10 +-- doc/mkdocs/docs/api/basic_json/empty.md | 2 +- doc/mkdocs/docs/api/basic_json/end.md | 2 +- doc/mkdocs/docs/api/basic_json/erase.md | 10 +-- doc/mkdocs/docs/api/basic_json/exception.md | 2 +- doc/mkdocs/docs/api/basic_json/find.md | 2 +- doc/mkdocs/docs/api/basic_json/flatten.md | 2 +- doc/mkdocs/docs/api/basic_json/from_bson.md | 10 +-- doc/mkdocs/docs/api/basic_json/from_cbor.md | 10 +-- .../docs/api/basic_json/from_msgpack.md | 10 +-- doc/mkdocs/docs/api/basic_json/from_ubjson.md | 10 +-- doc/mkdocs/docs/api/basic_json/front.md | 12 ++-- doc/mkdocs/docs/api/basic_json/get.md | 2 +- doc/mkdocs/docs/api/basic_json/get_ptr.md | 4 +- doc/mkdocs/docs/api/basic_json/get_ref.md | 4 +- doc/mkdocs/docs/api/basic_json/get_to.md | 2 +- doc/mkdocs/docs/api/basic_json/index.md | 4 ++ doc/mkdocs/docs/api/basic_json/insert.md | 10 +-- .../docs/api/basic_json/invalid_iterator.md | 2 +- doc/mkdocs/docs/api/basic_json/is_array.md | 2 +- doc/mkdocs/docs/api/basic_json/is_binary.md | 2 +- doc/mkdocs/docs/api/basic_json/is_boolean.md | 2 +- .../docs/api/basic_json/is_discarded.md | 2 +- doc/mkdocs/docs/api/basic_json/is_null.md | 2 +- doc/mkdocs/docs/api/basic_json/is_number.md | 2 +- .../docs/api/basic_json/is_number_float.md | 2 +- .../docs/api/basic_json/is_number_integer.md | 2 +- .../docs/api/basic_json/is_number_unsigned.md | 2 +- doc/mkdocs/docs/api/basic_json/is_object.md | 2 +- .../docs/api/basic_json/is_primitive.md | 2 +- doc/mkdocs/docs/api/basic_json/is_string.md | 2 +- .../docs/api/basic_json/is_structured.md | 2 +- doc/mkdocs/docs/api/basic_json/items.md | 2 +- doc/mkdocs/docs/api/basic_json/max_size.md | 2 +- doc/mkdocs/docs/api/basic_json/merge_patch.md | 2 +- doc/mkdocs/docs/api/basic_json/meta.md | 2 +- doc/mkdocs/docs/api/basic_json/object.md | 8 +-- doc/mkdocs/docs/api/basic_json/operator=.md | 2 +- doc/mkdocs/docs/api/basic_json/operator[].md | 22 +++---- .../docs/api/basic_json/operator_ValueType.md | 2 +- doc/mkdocs/docs/api/basic_json/operator_eq.md | 2 +- doc/mkdocs/docs/api/basic_json/operator_ge.md | 2 +- doc/mkdocs/docs/api/basic_json/operator_gt.md | 2 +- .../docs/api/basic_json/operator_gtgt.md | 4 +- doc/mkdocs/docs/api/basic_json/operator_le.md | 2 +- doc/mkdocs/docs/api/basic_json/operator_lt.md | 2 +- .../docs/api/basic_json/operator_ltlt.md | 2 +- doc/mkdocs/docs/api/basic_json/operator_ne.md | 2 +- .../docs/api/basic_json/operator_value_t.md | 2 +- doc/mkdocs/docs/api/basic_json/other_error.md | 2 +- .../docs/api/basic_json/out_of_range.md | 2 +- doc/mkdocs/docs/api/basic_json/parse_error.md | 4 +- .../docs/api/basic_json/parse_event_t.md | 2 +- doc/mkdocs/docs/api/basic_json/patch.md | 12 ++-- doc/mkdocs/docs/api/basic_json/rbegin.md | 2 +- doc/mkdocs/docs/api/basic_json/rend.md | 2 +- doc/mkdocs/docs/api/basic_json/size.md | 2 +- doc/mkdocs/docs/api/basic_json/swap.md | 2 +- doc/mkdocs/docs/api/basic_json/to_bson.md | 2 +- doc/mkdocs/docs/api/basic_json/to_cbor.md | 2 +- doc/mkdocs/docs/api/basic_json/to_msgpack.md | 2 +- doc/mkdocs/docs/api/basic_json/to_string.md | 8 +-- doc/mkdocs/docs/api/basic_json/to_ubjson.md | 2 +- doc/mkdocs/docs/api/basic_json/type.md | 2 +- doc/mkdocs/docs/api/basic_json/type_error.md | 2 +- doc/mkdocs/docs/api/basic_json/type_name.md | 2 +- doc/mkdocs/docs/api/basic_json/unflatten.md | 10 +-- doc/mkdocs/docs/api/basic_json/update.md | 2 +- doc/mkdocs/docs/api/basic_json/value.md | 2 +- doc/mkdocs/docs/api/basic_json/value_t.md | 2 +- .../byte_container_with_subtype.md | 3 + .../clear_subtype.md | 8 +-- .../has_subtype.md | 8 +-- .../set_subtype.md | 8 +-- .../byte_container_with_subtype/subtype.md | 8 +-- doc/mkdocs/docs/api/json_pointer.md | 4 ++ doc/mkdocs/docs/api/json_sax/binary.md | 2 +- doc/mkdocs/docs/api/json_sax/key.md | 2 +- doc/mkdocs/docs/api/json_sax/start_array.md | 2 +- doc/mkdocs/docs/api/json_sax/start_object.md | 2 +- doc/mkdocs/docs/api/json_sax/string.md | 2 +- doc/mkdocs/scripts/check_strcuture.py | 61 +++++++++++++++++++ 97 files changed, 274 insertions(+), 190 deletions(-) create mode 100644 doc/mkdocs/scripts/check_strcuture.py diff --git a/doc/mkdocs/docs/api/adl_serializer/from_json.md b/doc/mkdocs/docs/api/adl_serializer/from_json.md index 3c955079c..0524c82ce 100644 --- a/doc/mkdocs/docs/api/adl_serializer/from_json.md +++ b/doc/mkdocs/docs/api/adl_serializer/from_json.md @@ -35,3 +35,7 @@ Copy of the JSON value, converted to `ValueType` !!! note This documentation page is a stub. + +## Version history + +- Added in version 2.1.0. diff --git a/doc/mkdocs/docs/api/adl_serializer/index.md b/doc/mkdocs/docs/api/adl_serializer/index.md index 4ab8da4de..784ab5da6 100644 --- a/doc/mkdocs/docs/api/adl_serializer/index.md +++ b/doc/mkdocs/docs/api/adl_serializer/index.md @@ -29,3 +29,7 @@ struct adl_serializer { - [**from_json**](from_json.md) - convert a JSON value to any value type - [**to_json**](to_json.md) - convert any value type to a JSON value + +## Version history + +- Added in version 2.1.0. diff --git a/doc/mkdocs/docs/api/adl_serializer/to_json.md b/doc/mkdocs/docs/api/adl_serializer/to_json.md index 9289914db..37aff5c1a 100644 --- a/doc/mkdocs/docs/api/adl_serializer/to_json.md +++ b/doc/mkdocs/docs/api/adl_serializer/to_json.md @@ -20,3 +20,7 @@ This function is usually called by the constructors of the [basic_json](../basic !!! note This documentation page is a stub. + +## Version history + +- Added in version 2.1.0. diff --git a/doc/mkdocs/docs/api/basic_json/at.md b/doc/mkdocs/docs/api/basic_json/at.md index 488747d68..9f5023313 100644 --- a/doc/mkdocs/docs/api/basic_json/at.md +++ b/doc/mkdocs/docs/api/basic_json/at.md @@ -35,6 +35,10 @@ const_reference at(const json_pointer& ptr) const; 2. reference to the element at key `key` 3. reference to the element pointed to by `ptr` +## Exception safety + +Strong exception safety: if an exception occurs, the original value stays intact. + ## Exceptions 1. The function can throw the following exceptions: @@ -62,17 +66,13 @@ const_reference at(const json_pointer& ptr) const; - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can not be resolved. See example below. -## Exception safety - -Strong exception safety: if an exception occurs, the original value stays intact. - ## Complexity 1. Constant 2. Logarithmic in the size of the container. 3. Constant -## Example +## Examples ??? example "Example: (1) access specified array element with bounds checking" diff --git a/doc/mkdocs/docs/api/basic_json/back.md b/doc/mkdocs/docs/api/basic_json/back.md index 2acee240a..a66b2d73e 100644 --- a/doc/mkdocs/docs/api/basic_json/back.md +++ b/doc/mkdocs/docs/api/basic_json/back.md @@ -20,26 +20,26 @@ return *tmp; In case of a structured type (array or object), a reference to the last element is returned. In case of number, string, boolean, or binary values, a reference to the value is returned. +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. + ## Exceptions If the JSON value is `#!json null`, exception [`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown. -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. - ## Complexity Constant. -## Note +## Notes !!! danger Calling `back` on an empty array or object is undefined behavior and is **guarded by an assertion**! -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/basic_json.md b/doc/mkdocs/docs/api/basic_json/basic_json.md index 04aa90253..2e93ce40a 100644 --- a/doc/mkdocs/docs/api/basic_json/basic_json.md +++ b/doc/mkdocs/docs/api/basic_json/basic_json.md @@ -183,6 +183,22 @@ basic_json(basic_json&& other) noexcept; `other` (in) : the JSON value to copy/move +## Exception safety + +1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. +2. No-throw guarantee: this constructor never throws exceptions. +3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no + `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any + JSON value. +4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no + `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any + JSON value. +5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. +6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. +7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. +8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. +9. No-throw guarantee: this constructor never throws exceptions. + ## Exceptions 1. / @@ -207,22 +223,6 @@ basic_json(basic_json&& other) noexcept; 8. / 9. The function does not throw exceptions. -## Exception safety - -1. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. -2. No-throw guarantee: this constructor never throws exceptions. -3. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no - `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any - JSON value. -4. Depends on the called constructor. For types directly supported by the library (i.e., all types for which no - `to_json()` function was provided), strong guarantee holds: if an exception is thrown, there are no changes to any - JSON value. -5. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. -6. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. -7. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. -8. Strong guarantee: if an exception is thrown, there are no changes to any JSON value. -9. No-throw guarantee: this constructor never throws exceptions. - ## Complexity 1. Constant. @@ -275,7 +275,7 @@ basic_json(basic_json&& other) noexcept; - `#!cpp `*this` has the same value as `other` before the call. - `other` is a JSON `#!json null` value -## Example +## Examples ??? example "Example: (1) create an empty value with a given type" diff --git a/doc/mkdocs/docs/api/basic_json/begin.md b/doc/mkdocs/docs/api/basic_json/begin.md index 25d93b8f8..a1de9d4d0 100644 --- a/doc/mkdocs/docs/api/basic_json/begin.md +++ b/doc/mkdocs/docs/api/basic_json/begin.md @@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/cbegin.md b/doc/mkdocs/docs/api/basic_json/cbegin.md index 132934a8f..68a881443 100644 --- a/doc/mkdocs/docs/api/basic_json/cbegin.md +++ b/doc/mkdocs/docs/api/basic_json/cbegin.md @@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/cend.md b/doc/mkdocs/docs/api/basic_json/cend.md index e5de7e94e..3786e1df2 100644 --- a/doc/mkdocs/docs/api/basic_json/cend.md +++ b/doc/mkdocs/docs/api/basic_json/cend.md @@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/clear.md b/doc/mkdocs/docs/api/basic_json/clear.md index 5119b8389..c34439ef2 100644 --- a/doc/mkdocs/docs/api/basic_json/clear.md +++ b/doc/mkdocs/docs/api/basic_json/clear.md @@ -35,7 +35,7 @@ Linear in the size of the JSON value. All iterators, pointers and references related to this container are invalidated. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/contains.md b/doc/mkdocs/docs/api/basic_json/contains.md index 23dacb47e..2c9ebaac0 100644 --- a/doc/mkdocs/docs/api/basic_json/contains.md +++ b/doc/mkdocs/docs/api/basic_json/contains.md @@ -58,7 +58,7 @@ Logarithmic in the size of the JSON object. If `#!cpp j.contains(x)` returns `#!c true` for a key or JSON pointer `x`, then it is safe to call `j[x]`. -## Example +## Examples ??? example "Example (1) check with key" diff --git a/doc/mkdocs/docs/api/basic_json/count.md b/doc/mkdocs/docs/api/basic_json/count.md index 34f1605d3..5ed627bf1 100644 --- a/doc/mkdocs/docs/api/basic_json/count.md +++ b/doc/mkdocs/docs/api/basic_json/count.md @@ -34,7 +34,7 @@ Logarithmic in the size of the JSON object. This method always returns `0` when executed on a JSON type that is not an object. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/crbegin.md b/doc/mkdocs/docs/api/basic_json/crbegin.md index 14196627e..5b2f6101c 100644 --- a/doc/mkdocs/docs/api/basic_json/crbegin.md +++ b/doc/mkdocs/docs/api/basic_json/crbegin.md @@ -20,7 +20,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/crend.md b/doc/mkdocs/docs/api/basic_json/crend.md index 4b78f6f72..82375890f 100644 --- a/doc/mkdocs/docs/api/basic_json/crend.md +++ b/doc/mkdocs/docs/api/basic_json/crend.md @@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/diff.md b/doc/mkdocs/docs/api/basic_json/diff.md index 3359333ba..6f68b25a9 100644 --- a/doc/mkdocs/docs/api/basic_json/diff.md +++ b/doc/mkdocs/docs/api/basic_json/diff.md @@ -33,11 +33,11 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va Linear in the lengths of `source` and `target`. -## Note +## Notes Currently, only `remove`, `add`, and `replace` operations are generated. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/dump.md b/doc/mkdocs/docs/api/basic_json/dump.md index d0e78cec5..21fd33014 100644 --- a/doc/mkdocs/docs/api/basic_json/dump.md +++ b/doc/mkdocs/docs/api/basic_json/dump.md @@ -34,15 +34,15 @@ and `ensure_ascii` parameters. string containing the serialization of the JSON value +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes to any JSON value. + ## Exceptions Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value is not UTF-8 encoded and `error_handler` is set to `strict` -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes to any JSON value. - ## Complexity Linear. @@ -54,7 +54,7 @@ Binary values are serialized as object containing two keys: - "bytes": an array of bytes as integers - "subtype": the subtype as integer or `#!json null` if the binary has no subtype -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/empty.md b/doc/mkdocs/docs/api/basic_json/empty.md index 151e0739b..41d4f4996 100644 --- a/doc/mkdocs/docs/api/basic_json/empty.md +++ b/doc/mkdocs/docs/api/basic_json/empty.md @@ -44,7 +44,7 @@ bool empty() const noexcept This function does not return whether a string stored as JSON value is empty -- it returns whether the JSON container itself is empty which is `#!cpp false` in the case of a string. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/end.md b/doc/mkdocs/docs/api/basic_json/end.md index 52bfec2e3..d6948a726 100644 --- a/doc/mkdocs/docs/api/basic_json/end.md +++ b/doc/mkdocs/docs/api/basic_json/end.md @@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/erase.md b/doc/mkdocs/docs/api/basic_json/erase.md index 4f032c4f7..fd83635a0 100644 --- a/doc/mkdocs/docs/api/basic_json/erase.md +++ b/doc/mkdocs/docs/api/basic_json/erase.md @@ -58,6 +58,10 @@ void erase(const size_type idx); (`key` was not found) or `1` (`key` was found). 4. / +## Exception safety + +Strong exception safety: if an exception occurs, the original value stays intact. + ## Exceptions 1. The function can throw the following exceptions: @@ -85,10 +89,6 @@ void erase(const size_type idx); - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) when `idx >= size()`; example: `"array index 17 is out of range"` -## Exception safety - -Strong exception safety: if an exception occurs, the original value stays intact. - ## Complexity 1. The complexity depends on the type: @@ -112,7 +112,7 @@ Strong exception safety: if an exception occurs, the original value stays intact 3. References and iterators to the erased elements are invalidated. Other references and iterators are not affected. 4. / -## Example +## Examples ??? example "Example: (1) remove element given an iterator" diff --git a/doc/mkdocs/docs/api/basic_json/exception.md b/doc/mkdocs/docs/api/basic_json/exception.md index deedae5a6..9c807fc5e 100644 --- a/doc/mkdocs/docs/api/basic_json/exception.md +++ b/doc/mkdocs/docs/api/basic_json/exception.md @@ -44,7 +44,7 @@ Subclasses: - **id** - the id of the exception -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/find.md b/doc/mkdocs/docs/api/basic_json/find.md index 6086cc002..7e2e48fc4 100644 --- a/doc/mkdocs/docs/api/basic_json/find.md +++ b/doc/mkdocs/docs/api/basic_json/find.md @@ -38,7 +38,7 @@ Logarithmic in the size of the JSON object. This method always returns `end()` when executed on a JSON type that is not an object. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/flatten.md b/doc/mkdocs/docs/api/basic_json/flatten.md index f6621099a..0c6f640cb 100644 --- a/doc/mkdocs/docs/api/basic_json/flatten.md +++ b/doc/mkdocs/docs/api/basic_json/flatten.md @@ -25,7 +25,7 @@ Linear in the size the JSON value. Empty objects and arrays are flattened to `#!json null` and will not be reconstructed correctly by the [`unflatten()`](unflatten.md) function. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/from_bson.md b/doc/mkdocs/docs/api/basic_json/from_bson.md index 0396cd89e..968a33547 100644 --- a/doc/mkdocs/docs/api/basic_json/from_bson.md +++ b/doc/mkdocs/docs/api/basic_json/from_bson.md @@ -56,20 +56,20 @@ The exact mapping and its limitations is described on a [dedicated page](../../f deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md). +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. + ## Exceptions Throws [`parse_error.114`](../../home/exceptions.md#jsonexceptionparse_error114) if an unsupported BSON record type is encountered. -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. - ## Complexity Linear in the size of the input. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/from_cbor.md b/doc/mkdocs/docs/api/basic_json/from_cbor.md index a26a8f0b7..6e8bff60f 100644 --- a/doc/mkdocs/docs/api/basic_json/from_cbor.md +++ b/doc/mkdocs/docs/api/basic_json/from_cbor.md @@ -63,6 +63,10 @@ The exact mapping and its limitations is described on a [dedicated page](../../f deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md). +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. + ## Exceptions - Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or @@ -72,15 +76,11 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to - Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key, but not found -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. - ## Complexity Linear in the size of the input. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/from_msgpack.md b/doc/mkdocs/docs/api/basic_json/from_msgpack.md index fbee878df..cf191ec63 100644 --- a/doc/mkdocs/docs/api/basic_json/from_msgpack.md +++ b/doc/mkdocs/docs/api/basic_json/from_msgpack.md @@ -56,6 +56,10 @@ The exact mapping and its limitations is described on a [dedicated page](../../f deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md). +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. + ## Exceptions - Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or @@ -65,15 +69,11 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to - Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string was expected as map key, but not found -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. - ## Complexity Linear in the size of the input. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/from_ubjson.md b/doc/mkdocs/docs/api/basic_json/from_ubjson.md index b688c9841..6ab8df66f 100644 --- a/doc/mkdocs/docs/api/basic_json/from_ubjson.md +++ b/doc/mkdocs/docs/api/basic_json/from_ubjson.md @@ -56,6 +56,10 @@ The exact mapping and its limitations is described on a [dedicated page](../../f deserialized JSON value; in case of a parse error and `allow_exceptions` set to `#!cpp false`, the return value will be `value_t::discarded`. The latter can be checked with [`is_discarded`](is_discarded.md). +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. + ## Exceptions - Throws [parse_error.110](../../home/exceptions.md#jsonexceptionparse_error110) if the given input ends prematurely or @@ -64,15 +68,11 @@ deserialized JSON value; in case of a parse error and `allow_exceptions` set to - Throws [parse_error.113](../../home/exceptions.md#jsonexceptionparse_error113) if a string could not be parsed successfully -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. - ## Complexity Linear in the size of the input. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/front.md b/doc/mkdocs/docs/api/basic_json/front.md index af29def17..33b617014 100644 --- a/doc/mkdocs/docs/api/basic_json/front.md +++ b/doc/mkdocs/docs/api/basic_json/front.md @@ -13,26 +13,26 @@ Returns a reference to the first element in the container. For a JSON container In case of a structured type (array or object), a reference to the first element is returned. In case of number, string, boolean, or binary values, a reference to the value is returned. +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. + ## Exceptions If the JSON value is `#!json null`, exception [`invalid_iterator.214`](../../home/exceptions.md#jsonexceptioninvalid_iterator214) is thrown. -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. - ## Complexity Constant. -## Note +## Notes !!! danger Calling `front` on an empty array or object is undefined behavior and is **guarded by an assertion**! -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/get.md b/doc/mkdocs/docs/api/basic_json/get.md index 3ca4a237b..86b8166e5 100644 --- a/doc/mkdocs/docs/api/basic_json/get.md +++ b/doc/mkdocs/docs/api/basic_json/get.md @@ -94,7 +94,7 @@ Depends on what `json_serializer` `from_json()` method throws Writing data to the pointee (overload 3) of the result yields an undefined state. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/get_ptr.md b/doc/mkdocs/docs/api/basic_json/get_ptr.md index 7554844bb..f85a73db2 100644 --- a/doc/mkdocs/docs/api/basic_json/get_ptr.md +++ b/doc/mkdocs/docs/api/basic_json/get_ptr.md @@ -10,7 +10,7 @@ constexpr const PointerType get_ptr() const noexcept; Implicit pointer access to the internally stored JSON value. No copies are made. -## Template arguments +## Template parameters `PointerType` : pointer type; must be a pointer to [`array_t`](array_t.md), [`object_t`](object_t.md), [`string_t`](string_t.md), @@ -37,7 +37,7 @@ Constant. Writing data to the pointee of the result yields an undefined state. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/get_ref.md b/doc/mkdocs/docs/api/basic_json/get_ref.md index 102aff1ef..a819e24eb 100644 --- a/doc/mkdocs/docs/api/basic_json/get_ref.md +++ b/doc/mkdocs/docs/api/basic_json/get_ref.md @@ -10,7 +10,7 @@ const ReferenceType get_ref() const; Implicit reference access to the internally stored JSON value. No copies are made. -## Template arguments +## Template parameters `ReferenceType` : reference type; must be a reference to [`array_t`](array_t.md), [`object_t`](object_t.md), @@ -42,7 +42,7 @@ Constant. Writing data to the referee of the result yields an undefined state. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/get_to.md b/doc/mkdocs/docs/api/basic_json/get_to.md index 7af46a4c0..df2c3ad86 100644 --- a/doc/mkdocs/docs/api/basic_json/get_to.md +++ b/doc/mkdocs/docs/api/basic_json/get_to.md @@ -34,7 +34,7 @@ the input parameter, allowing chaining calls Depends on what `json_serializer` `from_json()` method throws -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index da332f13c..dbb585115 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -296,3 +296,7 @@ Access to the JSON value ## See also - [RFC 8259: The JavaScript Object Notation (JSON) Data Interchange Format](https://tools.ietf.org/html/rfc8259) + +## Version history + +- Added in version 1.0.0. diff --git a/doc/mkdocs/docs/api/basic_json/insert.md b/doc/mkdocs/docs/api/basic_json/insert.md index 5bd8ff1a3..821e91907 100644 --- a/doc/mkdocs/docs/api/basic_json/insert.md +++ b/doc/mkdocs/docs/api/basic_json/insert.md @@ -52,6 +52,10 @@ void insert(const_iterator first, const_iterator last); 4. iterator pointing to the first element inserted, or `pos` if `ilist` is empty 5. / +## Exception safety + +Strong exception safety: if an exception occurs, the original value stays intact. + ## Exceptions 1. The function can throw the following exceptions: @@ -86,10 +90,6 @@ void insert(const_iterator first, const_iterator last); - Throws [`invalid_iterator.210`](../../home/exceptions.md#jsonexceptioninvalid_iterator210) if `first` and `last` do not belong to the same JSON value; example: `"iterators do not fit"` -## Exception safety - -Strong exception safety: if an exception occurs, the original value stays intact. - ## Complexity 1. Constant plus linear in the distance between `pos` and end of the container. @@ -98,7 +98,7 @@ Strong exception safety: if an exception occurs, the original value stays intact 4. Linear in `ilist.size()` plus linear in the distance between `pos` and end of the container. 5. Logarithmic: `O(N*log(size() + N))`, where `N` is the number of elements to insert. -## Example +## Examples ??? example "Example (1): insert element into array" diff --git a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md index b11b27dfc..d64f801c7 100644 --- a/doc/mkdocs/docs/api/basic_json/invalid_iterator.md +++ b/doc/mkdocs/docs/api/basic_json/invalid_iterator.md @@ -38,7 +38,7 @@ class basic_json::invalid_iterator #FFFF00 {} - **id** - the id of the exception -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_array.md b/doc/mkdocs/docs/api/basic_json/is_array.md index a30379561..42f9c4651 100644 --- a/doc/mkdocs/docs/api/basic_json/is_array.md +++ b/doc/mkdocs/docs/api/basic_json/is_array.md @@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_binary.md b/doc/mkdocs/docs/api/basic_json/is_binary.md index f2285bb59..6c234d0ee 100644 --- a/doc/mkdocs/docs/api/basic_json/is_binary.md +++ b/doc/mkdocs/docs/api/basic_json/is_binary.md @@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_boolean.md b/doc/mkdocs/docs/api/basic_json/is_boolean.md index 32bb8c458..019dd81b6 100644 --- a/doc/mkdocs/docs/api/basic_json/is_boolean.md +++ b/doc/mkdocs/docs/api/basic_json/is_boolean.md @@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_discarded.md b/doc/mkdocs/docs/api/basic_json/is_discarded.md index b733f623c..c46d215d2 100644 --- a/doc/mkdocs/docs/api/basic_json/is_discarded.md +++ b/doc/mkdocs/docs/api/basic_json/is_discarded.md @@ -51,7 +51,7 @@ Constant. This function will always be `#!cpp false` for JSON values after parsing. That is, discarded values can only occur during parsing, but will be removed when inside a structured value or replaced by null in other cases. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_null.md b/doc/mkdocs/docs/api/basic_json/is_null.md index 8072642a9..1a03898fe 100644 --- a/doc/mkdocs/docs/api/basic_json/is_null.md +++ b/doc/mkdocs/docs/api/basic_json/is_null.md @@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_number.md b/doc/mkdocs/docs/api/basic_json/is_number.md index dbfda2a02..eff1751a4 100644 --- a/doc/mkdocs/docs/api/basic_json/is_number.md +++ b/doc/mkdocs/docs/api/basic_json/is_number.md @@ -28,7 +28,7 @@ constexpr bool is_number() const noexcept } ``` -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_number_float.md b/doc/mkdocs/docs/api/basic_json/is_number_float.md index 1ecd35b2d..8380907d8 100644 --- a/doc/mkdocs/docs/api/basic_json/is_number_float.md +++ b/doc/mkdocs/docs/api/basic_json/is_number_float.md @@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_number_integer.md b/doc/mkdocs/docs/api/basic_json/is_number_integer.md index bd539be2e..94c1c1a56 100644 --- a/doc/mkdocs/docs/api/basic_json/is_number_integer.md +++ b/doc/mkdocs/docs/api/basic_json/is_number_integer.md @@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_number_unsigned.md b/doc/mkdocs/docs/api/basic_json/is_number_unsigned.md index 90c6a1a03..5a56e27c6 100644 --- a/doc/mkdocs/docs/api/basic_json/is_number_unsigned.md +++ b/doc/mkdocs/docs/api/basic_json/is_number_unsigned.md @@ -19,7 +19,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_object.md b/doc/mkdocs/docs/api/basic_json/is_object.md index 22a15634c..bad30f33b 100644 --- a/doc/mkdocs/docs/api/basic_json/is_object.md +++ b/doc/mkdocs/docs/api/basic_json/is_object.md @@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_primitive.md b/doc/mkdocs/docs/api/basic_json/is_primitive.md index b38264250..96f50d5c2 100644 --- a/doc/mkdocs/docs/api/basic_json/is_primitive.md +++ b/doc/mkdocs/docs/api/basic_json/is_primitive.md @@ -38,7 +38,7 @@ The term *primitive* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259): This library extends primitive types to binary types, because binary types are roughly comparable to strings. Hence, `is_primitive()` returns `#!cpp true` for binary values. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_string.md b/doc/mkdocs/docs/api/basic_json/is_string.md index af725fb87..8b91a7f82 100644 --- a/doc/mkdocs/docs/api/basic_json/is_string.md +++ b/doc/mkdocs/docs/api/basic_json/is_string.md @@ -18,7 +18,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/is_structured.md b/doc/mkdocs/docs/api/basic_json/is_structured.md index 4890a301e..50246b73b 100644 --- a/doc/mkdocs/docs/api/basic_json/is_structured.md +++ b/doc/mkdocs/docs/api/basic_json/is_structured.md @@ -36,7 +36,7 @@ The term *structured* stems from [RFC 8259](https://tools.ietf.org/html/rfc8259) Note that though strings are containers in C++, they are treated as primitive values in JSON. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/items.md b/doc/mkdocs/docs/api/basic_json/items.md index 5e4483889..3d9c6fb78 100644 --- a/doc/mkdocs/docs/api/basic_json/items.md +++ b/doc/mkdocs/docs/api/basic_json/items.md @@ -68,7 +68,7 @@ When iterating over an array, `key()` will return the index of the element as st Using `items()` on temporary objects is dangerous. Make sure the object's lifetime exeeds the iteration. See for more information. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/max_size.md b/doc/mkdocs/docs/api/basic_json/max_size.md index 21fffa717..7b408f0e7 100644 --- a/doc/mkdocs/docs/api/basic_json/max_size.md +++ b/doc/mkdocs/docs/api/basic_json/max_size.md @@ -36,7 +36,7 @@ constant complexity. This function does not return the maximal length of a string stored as JSON value -- it returns the maximal number of string elements the JSON value can store which is `1`. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/merge_patch.md b/doc/mkdocs/docs/api/basic_json/merge_patch.md index 466416ce0..12007d448 100644 --- a/doc/mkdocs/docs/api/basic_json/merge_patch.md +++ b/doc/mkdocs/docs/api/basic_json/merge_patch.md @@ -37,7 +37,7 @@ Thereby, `Target` is the current object; that is, the patch is applied to the cu Linear in the lengths of `apply_patch`. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/meta.md b/doc/mkdocs/docs/api/basic_json/meta.md index 61218c3fa..78287d21d 100644 --- a/doc/mkdocs/docs/api/basic_json/meta.md +++ b/doc/mkdocs/docs/api/basic_json/meta.md @@ -28,7 +28,7 @@ Strong guarantee: if an exception is thrown, there are no changes to any JSON va Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/object.md b/doc/mkdocs/docs/api/basic_json/object.md index 3060b70a0..c250829cf 100644 --- a/doc/mkdocs/docs/api/basic_json/object.md +++ b/doc/mkdocs/docs/api/basic_json/object.md @@ -16,6 +16,10 @@ elements must be strings. If the initializer list is empty, the empty object `#! JSON object value +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. + ## Exceptions Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `init` is not a list of pairs whose @@ -23,10 +27,6 @@ first elements are strings. In this case, no object can be created. When such a `basic_json(initializer_list_t, bool, value_t)`, an array would have been created from the passed initializer list `init`. See example below. -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. - ## Complexity Linear in the size of `init`. diff --git a/doc/mkdocs/docs/api/basic_json/operator=.md b/doc/mkdocs/docs/api/basic_json/operator=.md index 340f8eaf3..02e908b4f 100644 --- a/doc/mkdocs/docs/api/basic_json/operator=.md +++ b/doc/mkdocs/docs/api/basic_json/operator=.md @@ -21,7 +21,7 @@ constructor, destructor, and the `swap()` member function. Linear. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator[].md b/doc/mkdocs/docs/api/basic_json/operator[].md index 81bcbdcfe..f582402ac 100644 --- a/doc/mkdocs/docs/api/basic_json/operator[].md +++ b/doc/mkdocs/docs/api/basic_json/operator[].md @@ -44,6 +44,10 @@ const_reference operator[](const json_pointer& ptr) const; 2. reference to the element at key `key` 3. reference to the element pointed to by `ptr` +## Exception safety + +Strong exception safety: if an exception occurs, the original value stays intact. + ## Exceptions 1. The function can throw the following exceptions: @@ -62,6 +66,12 @@ const_reference operator[](const json_pointer& ptr) const; - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can not be resolved. +## Complexity + +1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`. +2. Logarithmic in the size of the container. +3. Constant + ## Notes !!! danger @@ -87,17 +97,7 @@ const_reference operator[](const json_pointer& ptr) const; filled with `#!json null`. - The special value `-` is treated as a synonym for the index past the end. -## Exception safety - -Strong exception safety: if an exception occurs, the original value stays intact. - -## Complexity - -1. Constant if `idx` is in the range of the array. Otherwise, linear in `idx - size()`. -2. Logarithmic in the size of the container. -3. Constant - -## Example +## Examples ??? example "Example (1): access specified array element" diff --git a/doc/mkdocs/docs/api/basic_json/operator_ValueType.md b/doc/mkdocs/docs/api/basic_json/operator_ValueType.md index cfb5e64c8..c35ecac6b 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_ValueType.md +++ b/doc/mkdocs/docs/api/basic_json/operator_ValueType.md @@ -45,7 +45,7 @@ explicit operator ValueType() const; That is, implicit conversions can be switched off by defining [`JSON_USE_IMPLICIT_CONVERSIONS`](../../features/macros.md#json_use_implicit_conversions) to `0`. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator_eq.md b/doc/mkdocs/docs/api/basic_json/operator_eq.md index 34cf5537d..31fc76b46 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_eq.md +++ b/doc/mkdocs/docs/api/basic_json/operator_eq.md @@ -85,7 +85,7 @@ Linear. } ``` -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator_ge.md b/doc/mkdocs/docs/api/basic_json/operator_ge.md index 19834c0d8..08abbe15e 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_ge.md +++ b/doc/mkdocs/docs/api/basic_json/operator_ge.md @@ -38,7 +38,7 @@ No-throw guarantee: this function never throws exceptions. Linear. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator_gt.md b/doc/mkdocs/docs/api/basic_json/operator_gt.md index b9e32629d..b027a165d 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_gt.md +++ b/doc/mkdocs/docs/api/basic_json/operator_gt.md @@ -37,7 +37,7 @@ No-throw guarantee: this function never throws exceptions. Linear. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator_gtgt.md b/doc/mkdocs/docs/api/basic_json/operator_gtgt.md index 99079d002..8ef3ca187 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_gtgt.md +++ b/doc/mkdocs/docs/api/basic_json/operator_gtgt.md @@ -29,11 +29,11 @@ the stream `i` Linear in the length of the input. The parser is a predictive LL(1) parser. -## Note +## Notes A UTF-8 byte order mark is silently ignored. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator_le.md b/doc/mkdocs/docs/api/basic_json/operator_le.md index 452ee4966..b4f7be718 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_le.md +++ b/doc/mkdocs/docs/api/basic_json/operator_le.md @@ -38,7 +38,7 @@ No-throw guarantee: this function never throws exceptions. Linear. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator_lt.md b/doc/mkdocs/docs/api/basic_json/operator_lt.md index e8d2fb359..f9ac6c778 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_lt.md +++ b/doc/mkdocs/docs/api/basic_json/operator_lt.md @@ -52,7 +52,7 @@ No-throw guarantee: this function never throws exceptions. Linear. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator_ltlt.md b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md index 4ff023687..f0c05fdf7 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_ltlt.md +++ b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md @@ -34,7 +34,7 @@ is not UTF-8 encoded. Note that unlike the [`dump`](dump.md) member functions, n Linear. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/operator_ne.md b/doc/mkdocs/docs/api/basic_json/operator_ne.md index 5a86201ef..a9bb109d5 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_ne.md +++ b/doc/mkdocs/docs/api/basic_json/operator_ne.md @@ -37,7 +37,7 @@ No-throw guarantee: this function never throws exceptions. Linear. -## Example +## Examples The example demonstrates comparing several JSON types. 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 52125146c..a89aa8b19 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_value_t.md +++ b/doc/mkdocs/docs/api/basic_json/operator_value_t.md @@ -31,7 +31,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/other_error.md b/doc/mkdocs/docs/api/basic_json/other_error.md index 492b2d484..01f072e9f 100644 --- a/doc/mkdocs/docs/api/basic_json/other_error.md +++ b/doc/mkdocs/docs/api/basic_json/other_error.md @@ -38,7 +38,7 @@ class basic_json::other_error #FFFF00 {} - **id** - the id of the exception -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/out_of_range.md b/doc/mkdocs/docs/api/basic_json/out_of_range.md index 47ead87c2..8e5091ee2 100644 --- a/doc/mkdocs/docs/api/basic_json/out_of_range.md +++ b/doc/mkdocs/docs/api/basic_json/out_of_range.md @@ -39,7 +39,7 @@ class basic_json::out_of_range #FFFF00 {} - **id** - the id of the exception -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/parse_error.md b/doc/mkdocs/docs/api/basic_json/parse_error.md index de0ee4010..0e794f084 100644 --- a/doc/mkdocs/docs/api/basic_json/parse_error.md +++ b/doc/mkdocs/docs/api/basic_json/parse_error.md @@ -38,12 +38,12 @@ class basic_json::parse_error #FFFF00 { - **id** - the id of the exception - **byte** - byte index of the parse error -## Note +## Notes For an input with _n_ bytes, 1 is the index of the first character and _n_+1 is the index of the terminating null byte or the end of file. This also holds true when reading a byte vector for binary formats. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/parse_event_t.md b/doc/mkdocs/docs/api/basic_json/parse_event_t.md index 867de48bd..d6917127b 100644 --- a/doc/mkdocs/docs/api/basic_json/parse_event_t.md +++ b/doc/mkdocs/docs/api/basic_json/parse_event_t.md @@ -20,7 +20,7 @@ The parser callback distinguishes the following events: - `array_end`: the parser read `]` and finished processing a JSON array - `value`: the parser finished reading a JSON value -## Example +## Examples ![Example when certain parse events are triggered](../../images/callback_events.png) diff --git a/doc/mkdocs/docs/api/basic_json/patch.md b/doc/mkdocs/docs/api/basic_json/patch.md index f35985911..3ca5aebf3 100644 --- a/doc/mkdocs/docs/api/basic_json/patch.md +++ b/doc/mkdocs/docs/api/basic_json/patch.md @@ -17,6 +17,10 @@ the patch. patched document +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. + ## Exceptions - Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of @@ -31,21 +35,17 @@ patched document - Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was unsuccessful. -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes in the JSON value. - ## Complexity Linear in the size of the JSON value and the length of the JSON patch. As usually only a fraction of the JSON value is affected by the patch, the complexity can usually be neglected. -## Note +## Notes The application of a patch is atomic: Either all operations succeed and the patched document is returned or an exception is thrown. In any case, the original value is not changed: the patch is applied to a copy of the value. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/rbegin.md b/doc/mkdocs/docs/api/basic_json/rbegin.md index 57957b3b4..0c94bb818 100644 --- a/doc/mkdocs/docs/api/basic_json/rbegin.md +++ b/doc/mkdocs/docs/api/basic_json/rbegin.md @@ -21,7 +21,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/rend.md b/doc/mkdocs/docs/api/basic_json/rend.md index 5d5f21310..74a261bb3 100644 --- a/doc/mkdocs/docs/api/basic_json/rend.md +++ b/doc/mkdocs/docs/api/basic_json/rend.md @@ -22,7 +22,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/size.md b/doc/mkdocs/docs/api/basic_json/size.md index 36a9daeb6..ce4ee8eb7 100644 --- a/doc/mkdocs/docs/api/basic_json/size.md +++ b/doc/mkdocs/docs/api/basic_json/size.md @@ -35,7 +35,7 @@ constant complexity. This function does not return the length of a string stored as JSON value -- it returns the number of elements in the JSON value which is `1` in the case of a string. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/swap.md b/doc/mkdocs/docs/api/basic_json/swap.md index 47ca2d0da..ae6f0d455 100644 --- a/doc/mkdocs/docs/api/basic_json/swap.md +++ b/doc/mkdocs/docs/api/basic_json/swap.md @@ -70,7 +70,7 @@ void swap(typename binary_t::container_type& other); Constant. -## Example +## Examples ??? example "Example: Swap JSON value (1, 2)" diff --git a/doc/mkdocs/docs/api/basic_json/to_bson.md b/doc/mkdocs/docs/api/basic_json/to_bson.md index c4687488d..ad4811b4f 100644 --- a/doc/mkdocs/docs/api/basic_json/to_bson.md +++ b/doc/mkdocs/docs/api/basic_json/to_bson.md @@ -38,7 +38,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va Linear in the size of the JSON value `j`. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/to_cbor.md b/doc/mkdocs/docs/api/basic_json/to_cbor.md index bd863c324..5dc7836f2 100644 --- a/doc/mkdocs/docs/api/basic_json/to_cbor.md +++ b/doc/mkdocs/docs/api/basic_json/to_cbor.md @@ -39,7 +39,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va Linear in the size of the JSON value `j`. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/to_msgpack.md b/doc/mkdocs/docs/api/basic_json/to_msgpack.md index 432f18cd0..4b640c63a 100644 --- a/doc/mkdocs/docs/api/basic_json/to_msgpack.md +++ b/doc/mkdocs/docs/api/basic_json/to_msgpack.md @@ -38,7 +38,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va Linear in the size of the JSON value `j`. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/to_string.md b/doc/mkdocs/docs/api/basic_json/to_string.md index 9678ad32b..bdf42c3a9 100644 --- a/doc/mkdocs/docs/api/basic_json/to_string.md +++ b/doc/mkdocs/docs/api/basic_json/to_string.md @@ -16,15 +16,15 @@ This function implements a user-defined to_string for JSON objects. string containing the serialization of the JSON value +## Exception safety + +Strong guarantee: if an exception is thrown, there are no changes to any JSON value. + ## Exceptions Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value is not UTF-8 encoded -## Exception safety - -Strong guarantee: if an exception is thrown, there are no changes to any JSON value. - ## Complexity Linear. diff --git a/doc/mkdocs/docs/api/basic_json/to_ubjson.md b/doc/mkdocs/docs/api/basic_json/to_ubjson.md index f8f5e48aa..2edc0638f 100644 --- a/doc/mkdocs/docs/api/basic_json/to_ubjson.md +++ b/doc/mkdocs/docs/api/basic_json/to_ubjson.md @@ -49,7 +49,7 @@ Strong guarantee: if an exception is thrown, there are no changes in the JSON va Linear in the size of the JSON value `j`. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/type.md b/doc/mkdocs/docs/api/basic_json/type.md index b3482117b..15b09d8fe 100644 --- a/doc/mkdocs/docs/api/basic_json/type.md +++ b/doc/mkdocs/docs/api/basic_json/type.md @@ -31,7 +31,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/type_error.md b/doc/mkdocs/docs/api/basic_json/type_error.md index ea0154e39..d74b48fc5 100644 --- a/doc/mkdocs/docs/api/basic_json/type_error.md +++ b/doc/mkdocs/docs/api/basic_json/type_error.md @@ -39,7 +39,7 @@ class basic_json::type_error #FFFF00 {} - **id** - the id of the exception -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/type_name.md b/doc/mkdocs/docs/api/basic_json/type_name.md index 02b3e545b..d35b8220c 100644 --- a/doc/mkdocs/docs/api/basic_json/type_name.md +++ b/doc/mkdocs/docs/api/basic_json/type_name.md @@ -30,7 +30,7 @@ No-throw guarantee: this member function never throws exceptions. Constant. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/unflatten.md b/doc/mkdocs/docs/api/basic_json/unflatten.md index c4d258cc7..23c8b0751 100644 --- a/doc/mkdocs/docs/api/basic_json/unflatten.md +++ b/doc/mkdocs/docs/api/basic_json/unflatten.md @@ -15,6 +15,10 @@ The function restores the arbitrary nesting of a JSON value that has been flatte the original JSON from a flattened version +## Exception safety + +Strong exception safety: if an exception occurs, the original value stays intact. + ## Exceptions The function can throw the following exceptions: @@ -22,10 +26,6 @@ The function can throw the following exceptions: - Throws [`type_error.314`](../../home/exceptions.md#jsonexceptiontype_error314) if value is not an object - Throws [`type_error.315`](../../home/exceptions.md#jsonexceptiontype_error315) if object values are not primitive -## Exception safety - -Strong exception safety: if an exception occurs, the original value stays intact. - ## Complexity Linear in the size the JSON value. @@ -36,7 +36,7 @@ Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json n their original type. Apart from this example, for a JSON value `j`, the following is always true: `#!cpp j == j.flatten().unflatten()`. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/update.md b/doc/mkdocs/docs/api/basic_json/update.md index 63894c077..f6fb2fec2 100644 --- a/doc/mkdocs/docs/api/basic_json/update.md +++ b/doc/mkdocs/docs/api/basic_json/update.md @@ -50,7 +50,7 @@ function. 1. O(N*log(size() + N)), where N is the number of elements to insert. 2. O(N*log(size() + N)), where N is the number of elements to insert. -## Example +## Examples ??? example diff --git a/doc/mkdocs/docs/api/basic_json/value.md b/doc/mkdocs/docs/api/basic_json/value.md index 7f2592f42..18135a44c 100644 --- a/doc/mkdocs/docs/api/basic_json/value.md +++ b/doc/mkdocs/docs/api/basic_json/value.md @@ -88,7 +88,7 @@ changes to any JSON value. 1. Logarithmic in the size of the container. 2. Logarithmic in the size of the container. -## Example +## Examples ??? example "Example (1): access specified object element with default value" diff --git a/doc/mkdocs/docs/api/basic_json/value_t.md b/doc/mkdocs/docs/api/basic_json/value_t.md index 5fa9501fc..fc9b38f4d 100644 --- a/doc/mkdocs/docs/api/basic_json/value_t.md +++ b/doc/mkdocs/docs/api/basic_json/value_t.md @@ -22,7 +22,7 @@ functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_ [`is_discarded`](is_discarded.md), [`is_binary`](is_binary.md), [`is_primitive`](is_primitive.md), and [`is_structured`](is_structured.md) rely on it. -## Note +## Notes There are three enumeration entries (number_integer, number_unsigned, and number_float), because the library distinguishes these three types for numbers: [`number_unsigned_t`](number_unsigned_t.md) is used for unsigned integers, diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md index 0ad701eb4..895fbe2bb 100644 --- a/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/byte_container_with_subtype.md @@ -25,3 +25,6 @@ byte_container_with_subtype(container_type&& container, subtype_type subtype); `subtype` (in) : subtype +## Version history + +Since version 3.8.0. diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md index b7afbda0f..c87b3d666 100644 --- a/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/clear_subtype.md @@ -7,14 +7,14 @@ void clear_subtype() noexcept; Clears the binary subtype and flags the value as not having a subtype, which has implications for serialization; for instance MessagePack will prefer the bin family over the ext family. -## Complexity - -Constant. - ## Exception safety No-throw guarantee: this function never throws exceptions. +## Complexity + +Constant. + ## Version history Since version 3.8.0. diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md index 5fcec994d..80afaf11e 100644 --- a/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/has_subtype.md @@ -10,14 +10,14 @@ Returns whether the value has a subtype. whether the value has a subtype -## Complexity - -Constant. - ## Exception safety No-throw guarantee: this function never throws exceptions. +## Complexity + +Constant. + ## Version history Since version 3.8.0. diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md index f9b44fc3a..7c5360446 100644 --- a/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/set_subtype.md @@ -12,14 +12,14 @@ serialization. `subtype` (in) : subtype to set -## Complexity - -Constant. - ## Exception safety No-throw guarantee: this function never throws exceptions. +## Complexity + +Constant. + ## Version history Since version 3.8.0. diff --git a/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md b/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md index d7bc5ba74..0e9f034d4 100644 --- a/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md +++ b/doc/mkdocs/docs/api/byte_container_with_subtype/subtype.md @@ -11,14 +11,14 @@ Returns the numerical subtype of the value if it has a subtype. If it does not h the numerical subtype of the binary value, or `subtype_type(-1)` if no subtype is set -## Complexity - -Constant. - ## Exception safety No-throw guarantee: this function never throws exceptions. +## Complexity + +Constant. + ## Version history - Added in version 3.8.0 diff --git a/doc/mkdocs/docs/api/json_pointer.md b/doc/mkdocs/docs/api/json_pointer.md index 5aa0399cd..69983ab89 100644 --- a/doc/mkdocs/docs/api/json_pointer.md +++ b/doc/mkdocs/docs/api/json_pointer.md @@ -22,3 +22,7 @@ class json_pointer; - **back** - return last reference token - **push_back** - append an unescaped token at the end of the pointer - **empty** - return whether pointer points to the root document + +## Version history + +Added in version 2.0.0. diff --git a/doc/mkdocs/docs/api/json_sax/binary.md b/doc/mkdocs/docs/api/json_sax/binary.md index e724eb7c2..98254a067 100644 --- a/doc/mkdocs/docs/api/json_sax/binary.md +++ b/doc/mkdocs/docs/api/json_sax/binary.md @@ -15,7 +15,7 @@ A binary value was read. Whether parsing should proceed. -## Note +## Notes It is safe to move the passed binary value. diff --git a/doc/mkdocs/docs/api/json_sax/key.md b/doc/mkdocs/docs/api/json_sax/key.md index 4593b43ab..9afcea3a2 100644 --- a/doc/mkdocs/docs/api/json_sax/key.md +++ b/doc/mkdocs/docs/api/json_sax/key.md @@ -15,7 +15,7 @@ An object key was read. Whether parsing should proceed. -## Note +## Notes It is safe to move the passed object key value. diff --git a/doc/mkdocs/docs/api/json_sax/start_array.md b/doc/mkdocs/docs/api/json_sax/start_array.md index a762fc8c0..16855ee18 100644 --- a/doc/mkdocs/docs/api/json_sax/start_array.md +++ b/doc/mkdocs/docs/api/json_sax/start_array.md @@ -15,7 +15,7 @@ The beginning of an array was read. Whether parsing should proceed. -## Note +## Notes Binary formats may report the number of elements. diff --git a/doc/mkdocs/docs/api/json_sax/start_object.md b/doc/mkdocs/docs/api/json_sax/start_object.md index ab9bc61f5..34103cd22 100644 --- a/doc/mkdocs/docs/api/json_sax/start_object.md +++ b/doc/mkdocs/docs/api/json_sax/start_object.md @@ -15,7 +15,7 @@ The beginning of an object was read. Whether parsing should proceed. -## Note +## Notes Binary formats may report the number of elements. diff --git a/doc/mkdocs/docs/api/json_sax/string.md b/doc/mkdocs/docs/api/json_sax/string.md index 7ae050b19..f0ab328eb 100644 --- a/doc/mkdocs/docs/api/json_sax/string.md +++ b/doc/mkdocs/docs/api/json_sax/string.md @@ -15,7 +15,7 @@ A string value was read. Whether parsing should proceed. -## Note +## Notes It is safe to move the passed string value. diff --git a/doc/mkdocs/scripts/check_strcuture.py b/doc/mkdocs/scripts/check_strcuture.py new file mode 100644 index 000000000..50a79e8eb --- /dev/null +++ b/doc/mkdocs/scripts/check_strcuture.py @@ -0,0 +1,61 @@ +#!/usr/bin/env python + +import glob + + +def check_structure(): + expected_headers = [ + 'Specializations', + 'Template parameters', + 'Iterator invalidation', + 'Requirements', + 'Member types', + 'Member functions', + 'Member variables', + 'Static functions', + 'Non-member functions', + 'Literals', + 'Helper classes', + 'Parameters', + 'Return value', + 'Exception safety', + 'Exceptions', + 'Complexity', + 'Possible implementation', + 'Notes', + 'Examples', + 'See also', + 'Version history' + ] + + required_headers = [ + 'Version history' + ] + + for file in glob.glob('api/**/*.md', recursive=True): + with open(file) as file_content: + header_idx = -1 + existing_headers = [] + + for lineno, line in enumerate(file_content.readlines()): + line = line.strip() + + if line.startswith('## '): + header = line.strip('## ') + existing_headers.append(header) + + if header in expected_headers: + idx = expected_headers.index(header) + if idx <= header_idx: + print(f'{file}:{lineno+1}: Error: header "{header}" is in an unexpected order (should be before "{expected_headers[header_idx]}")!') + header_idx = idx + else: + print(f'{file}:{lineno+1}: Error: header "{header}" is not part of the expected headers!') + + for required_header in required_headers: + if required_header not in existing_headers: + print(f'{file}:{lineno+1}: Error: required header "{required_header}" was not found!') + + +if __name__ == '__main__': + check_structure()