From 874f49e9453eb59b6fcc6a88d65f6bf3337bf61e Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 12 Aug 2020 14:29:25 +0200 Subject: [PATCH] :memo: add more API documentation --- .../docs/api/basic_json/number_integer_t.md | 60 ++++++---------- .../docs/api/basic_json/number_unsigned_t.md | 61 ++++++---------- doc/mkdocs/docs/api/basic_json/object.md | 29 +++----- doc/mkdocs/docs/api/basic_json/object_t.md | 63 +++++++---------- doc/mkdocs/docs/api/basic_json/operator+=.md | 41 +++++------ doc/mkdocs/docs/api/basic_json/operator=.md | 11 ++- doc/mkdocs/docs/api/basic_json/operator==.md | 41 ++++++----- doc/mkdocs/docs/api/basic_json/operator[].md | 70 ++++++++----------- .../docs/api/basic_json/operator_value_t.md | 6 +- .../docs/api/basic_json/parser_callback_t.md | 32 ++++----- doc/mkdocs/docs/api/basic_json/patch.md | 42 +++++------ doc/mkdocs/docs/api/basic_json/push_back.md | 43 +++++------- doc/mkdocs/docs/api/basic_json/rend.md | 4 +- doc/mkdocs/docs/api/basic_json/sax_parse.md | 19 +++-- doc/mkdocs/docs/api/basic_json/size.md | 17 ++--- doc/mkdocs/docs/api/basic_json/string_t.md | 42 ++++------- doc/mkdocs/docs/api/basic_json/type.md | 8 +-- doc/mkdocs/docs/api/basic_json/type_name.md | 7 +- doc/mkdocs/docs/api/basic_json/unflatten.md | 16 ++--- doc/mkdocs/docs/api/basic_json/update.md | 20 +++--- doc/mkdocs/docs/api/basic_json/value.md | 40 +++++------ doc/mkdocs/docs/api/basic_json/value_t.md | 18 ++--- 22 files changed, 285 insertions(+), 405 deletions(-) diff --git a/doc/mkdocs/docs/api/basic_json/number_integer_t.md b/doc/mkdocs/docs/api/basic_json/number_integer_t.md index 9f2f695a7..c10cb7803 100644 --- a/doc/mkdocs/docs/api/basic_json/number_integer_t.md +++ b/doc/mkdocs/docs/api/basic_json/number_integer_t.md @@ -7,41 +7,31 @@ using number_integer_t = NumberIntegerType; The type used to store JSON numbers (integers). [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows: -> The representation of numbers is similar to that used in most -> programming languages. A number is represented in base 10 using decimal -> digits. It contains an integer component that may be prefixed with an -> optional minus sign, which may be followed by a fraction part and/or an -> exponent part. Leading zeros are not allowed. (...) Numeric values that -> cannot be represented in the grammar below (such as Infinity and NaN) -> are not permitted. +> The representation of numbers is similar to that used in most programming languages. A number is represented in base +> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may +> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that +> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted. -This description includes both integer and floating-point numbers. -However, C++ allows more precise storage if it is known whether the number -is a signed integer, an unsigned integer or a floating-point number. -Therefore, three different types, `number_integer_t`, -[`number_unsigned_t`](number_unsigned_t.md) and [`number_float_t`](number_float_t.md) are used. +This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is +known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different +types, `number_integer_t`, [`number_unsigned_t`](number_unsigned_t.md) and [`number_float_t`](number_float_t.md) are +used. -To store integer numbers in C++, a type is defined by the template -parameter `NumberIntegerType` which chooses the type to use. +To store integer numbers in C++, a type is defined by the template parameter `NumberIntegerType` which chooses the type +to use. ## Notes #### Default type -With the default values for `NumberIntegerType` (`std::int64_t`), the default -value for `number_integer_t` is: - -```cpp -std::int64_t -``` +With the default values for `NumberIntegerType` (`std::int64_t`), the default value for `number_integer_t` is +`#!cpp std::int64_t`. #### Default behavior -- The restrictions about leading zeros is not enforced in C++. Instead, - leading zeros in integer literals lead to an interpretation as octal - number. Internally, the value will be stored as decimal number. For - instance, the C++ integer literal `010` will be serialized to `8`. - During deserialization, leading zeros yield an error. +- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an + interpretation as octal number. Internally, the value will be stored as decimal number. For instance, the C++ integer + literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error. - Not-a-number (NaN) values will be serialized to `null`. #### Limits @@ -49,21 +39,17 @@ std::int64_t [RFC 7159](http://rfc7159.net/rfc7159) specifies: > An implementation may set limits on the range and precision of numbers. -When the default type is used, the maximal integer number that can be -stored is `9223372036854775807` (INT64_MAX) and the minimal integer number -that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers -that are out of range will yield over/underflow when used in a -constructor. During deserialization, too large or small integer numbers -will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) -or [`number_float_t`](number_float_t.md). +When the default type is used, the maximal integer number that can be stored is `9223372036854775807` (INT64_MAX) and +the minimal integer number that can be stored is `-9223372036854775808` (INT64_MIN). Integer numbers that are out of +range will yield over/underflow when used in a constructor. During deserialization, too large or small integer numbers +will be automatically be stored as [`number_unsigned_t`](number_unsigned_t.md) or [`number_float_t`](number_float_t.md). [RFC 7159](http://rfc7159.net/rfc7159) further states: -> Note that when such software is used, numbers that are integers and are -> in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense -> that implementations will agree exactly on their numeric values. +> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are +> interoperable in the sense that implementations will agree exactly on their numeric values. -As this range is a subrange of the exactly supported range [INT64_MIN, -INT64_MAX], this class's integer type is interoperable. +As this range is a subrange of the exactly supported range [INT64_MIN, INT64_MAX], this class's integer type is +interoperable. #### Storage diff --git a/doc/mkdocs/docs/api/basic_json/number_unsigned_t.md b/doc/mkdocs/docs/api/basic_json/number_unsigned_t.md index 59698c34d..a28e25351 100644 --- a/doc/mkdocs/docs/api/basic_json/number_unsigned_t.md +++ b/doc/mkdocs/docs/api/basic_json/number_unsigned_t.md @@ -7,41 +7,31 @@ using number_unsigned_t = NumberUnsignedType; The type used to store JSON numbers (unsigned). [RFC 7159](http://rfc7159.net/rfc7159) describes numbers as follows: -> The representation of numbers is similar to that used in most -> programming languages. A number is represented in base 10 using decimal -> digits. It contains an integer component that may be prefixed with an -> optional minus sign, which may be followed by a fraction part and/or an -> exponent part. Leading zeros are not allowed. (...) Numeric values that -> cannot be represented in the grammar below (such as Infinity and NaN) -> are not permitted. +> The representation of numbers is similar to that used in most programming languages. A number is represented in base +> 10 using decimal digits. It contains an integer component that may be prefixed with an optional minus sign, which may +> be followed by a fraction part and/or an exponent part. Leading zeros are not allowed. (...) Numeric values that +> cannot be represented in the grammar below (such as Infinity and NaN) are not permitted. -This description includes both integer and floating-point numbers. -However, C++ allows more precise storage if it is known whether the number -is a signed integer, an unsigned integer or a floating-point number. -Therefore, three different types, [`number_integer_t`](number_integer_t.md), -`number_unsigned_t` and [`number_float_t`](number_float_t.md) are used. +This description includes both integer and floating-point numbers. However, C++ allows more precise storage if it is +known whether the number is a signed integer, an unsigned integer or a floating-point number. Therefore, three different +types, [`number_integer_t`](number_integer_t.md), `number_unsigned_t` and [`number_float_t`](number_float_t.md) are +used. -To store unsigned integer numbers in C++, a type is defined by the -template parameter `NumberUnsignedType` which chooses the type to use. +To store unsigned integer numbers in C++, a type is defined by the template parameter `NumberUnsignedType` which chooses +the type to use. ## Notes #### Default type -With the default values for `NumberUnsignedType` (`std::uint64_t`), the -default value for `number_unsigned_t` is: - -```cpp -std::uint64_t -``` +With the default values for `NumberUnsignedType` (`std::uint64_t`), the default value for `number_unsigned_t` is +`#!cpp std::uint64_t`. #### Default behavior -- The restrictions about leading zeros is not enforced in C++. Instead, - leading zeros in integer literals lead to an interpretation as octal - number. Internally, the value will be stored as decimal number. For - instance, the C++ integer literal `010` will be serialized to `8`. - During deserialization, leading zeros yield an error. +- The restrictions about leading zeros is not enforced in C++. Instead, leading zeros in integer literals lead to an + interpretation as octal number. Internally, the value will be stored as decimal number. For instance, the C++ integer + literal `010` will be serialized to `8`. During deserialization, leading zeros yield an error. - Not-a-number (NaN) values will be serialized to `null`. #### Limits @@ -49,22 +39,17 @@ std::uint64_t [RFC 7159](http://rfc7159.net/rfc7159) specifies: > An implementation may set limits on the range and precision of numbers. -When the default type is used, the maximal integer number that can be -stored is `18446744073709551615` (UINT64_MAX) and the minimal integer -number that can be stored is `0`. Integer numbers that are out of range -will yield over/underflow when used in a constructor. During -deserialization, too large or small integer numbers will be automatically -be stored as [`number_integer_t`](number_integer_t.md) or -[`number_float_t`](number_float_t.md). +When the default type is used, the maximal integer number that can be stored is `18446744073709551615` (UINT64_MAX) and +the minimal integer number that can be stored is `0`. Integer numbers that are out of range will yield over/underflow +when used in a constructor. During deserialization, too large or small integer numbers will be automatically be stored +as [`number_integer_t`](number_integer_t.md) or [`number_float_t`](number_float_t.md). [RFC 7159](http://rfc7159.net/rfc7159) further states: -> Note that when such software is used, numbers that are integers and are -> in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are interoperable in the sense -> that implementations will agree exactly on their numeric values. +> Note that when such software is used, numbers that are integers and are in the range \f$[-2^{53}+1, 2^{53}-1]\f$ are +> interoperable in the sense that implementations will agree exactly on their numeric values. -As this range is a subrange (when considered in conjunction with the -number_integer_t type) of the exactly supported range [0, UINT64_MAX], -this class's integer type is interoperable. +As this range is a subrange (when considered in conjunction with the `number_integer_t` type) of the exactly supported +range [0, UINT64_MAX], this class's integer type is interoperable. #### Storage diff --git a/doc/mkdocs/docs/api/basic_json/object.md b/doc/mkdocs/docs/api/basic_json/object.md index 02429751c..4aae6fe2a 100644 --- a/doc/mkdocs/docs/api/basic_json/object.md +++ b/doc/mkdocs/docs/api/basic_json/object.md @@ -4,9 +4,8 @@ static basic_json object(initializer_list_t init = {}); ``` -Creates a JSON object value from a given initializer list. The initializer -lists elements must be pairs, and their first elements must be strings. If -the initializer list is empty, the empty object `#!json {}` is created. +Creates a JSON object value from a given initializer list. The initializer lists elements must be pairs, and their first +elements must be strings. If the initializer list is empty, the empty object `#!json {}` is created. ## Parameters @@ -19,17 +18,14 @@ JSON object value ## Exceptions -Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) -if `init` is not a list of pairs whose first -elements are strings. In this case, no object can be created. When such a -value is passed to `basic_json(initializer_list_t, bool, value_t)`, -an array would have been created from the passed initializer list `init`. -See example below. +Throws [`type_error.301`](../../home/exceptions.md#jsonexceptiontype_error301) if `init` is not a list of pairs whose +first elements are strings. In this case, no object can be created. When such a value is passed to +`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. +Strong guarantee: if an exception is thrown, there are no changes in the JSON value. ## Complexity @@ -37,18 +33,15 @@ Linear in the size of `init`. ## Notes -This function is only added for symmetry reasons. In contrast to the -related function `array(initializer_list_t)`, there are -no cases which can only be expressed by this function. That is, any -initializer list `init` can also be passed to the initializer list -constructor `basic_json(initializer_list_t, bool, value_t)`. +This function is only added for symmetry reasons. In contrast to the related function `array(initializer_list_t)`, there +are no cases which can only be expressed by this function. That is, any initializer list `init` can also be passed to +the initializer list constructor `basic_json(initializer_list_t, bool, value_t)`. ## Examples ??? example - The following code shows an example for the `object` - function. + The following code shows an example for the `object` function. ```cpp --8<-- "examples/object.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/object_t.md b/doc/mkdocs/docs/api/basic_json/object_t.md index a2b0c13b6..a3d2b7c54 100644 --- a/doc/mkdocs/docs/api/basic_json/object_t.md +++ b/doc/mkdocs/docs/api/basic_json/object_t.md @@ -10,12 +10,10 @@ using object_t = ObjectType An object is an unordered collection of zero or more name/value pairs, -> where a name is a string and a value is a string, number, boolean, null, -> object, or array. +> An object is an unordered collection of zero or more name/value pairs, where a name is a string and a value is a +> string, number, boolean, null, object, or array. -To store objects in C++, a type is defined by the template parameters -described below. +To store objects in C++, a type is defined by the template parameters described below. ## Template parameters @@ -23,9 +21,8 @@ described below. : the container to store objects (e.g., `std::map` or `std::unordered_map`) `StringType` -: the type of the keys or names (e.g., `std::string`). - The comparison function `std::less` is used to order elements - inside the container. +: the type of the keys or names (e.g., `std::string`). The comparison function `std::less` is used to + order elements inside the container. `AllocatorType` : the allocator to use for objects (e.g., `std::allocator`) @@ -34,9 +31,8 @@ described below. #### Default type -With the default values for `ObjectType` (`std::map`), `StringType` -(`std::string`), and `AllocatorType` (`std::allocator`), the default -value for `object_t` is: +With the default values for `ObjectType` (`std::map`), `StringType` (`std::string`), and `AllocatorType` +(`std::allocator`), the default value for `object_t` is: ```cpp std::map< @@ -49,23 +45,19 @@ std::map< #### Behavior -The choice of `object_t` influences the behavior of the JSON class. With -the default type, objects have the following behavior: +The choice of `object_t` influences the behavior of the JSON class. With the default type, objects have the following +behavior: -- When all names are unique, objects will be interoperable in the sense - that all software implementations receiving that object will agree on - the name-value mappings. -- When the names within an object are not unique, it is unspecified which - one of the values for a given key will be chosen. For instance, - `#!json {"key": 2, "key": 1}` could be equal to either `#!json {"key": 1}` or +- When all names are unique, objects will be interoperable in the sense that all software implementations receiving that + object will agree on the name-value mappings. +- When the names within an object are not unique, it is unspecified which one of the values for a given key will be + chosen. For instance, `#!json {"key": 2, "key": 1}` could be equal to either `#!json {"key": 1}` or `#!json {"key": 2}`. -- Internally, name/value pairs are stored in lexicographical order of the - names. Objects will also be serialized (see [`dump`](dump.md)) in this order. - For instance, `#!json {"b": 1, "a": 2}` and `#!json {"a": 2, "b": 1}` will be stored +- Internally, name/value pairs are stored in lexicographical order of the names. Objects will also be serialized (see + [`dump`](dump.md)) in this order. For instance, `#!json {"b": 1, "a": 2}` and `#!json {"a": 2, "b": 1}` will be stored and serialized as `#!json {"a": 2, "b": 1}`. -- When comparing objects, the order of the name/value pairs is irrelevant. - This makes objects interoperable in the sense that they will not be - affected by these differences. For instance, `#!json {"b": 1, "a": 2}` and +- When comparing objects, the order of the name/value pairs is irrelevant. This makes objects interoperable in the sense + that they will not be affected by these differences. For instance, `#!json {"b": 1, "a": 2}` and `#!json {"a": 2, "b": 1}` will be treated as equal. #### Limits @@ -73,26 +65,21 @@ the default type, objects have the following behavior: [RFC 7159](http://rfc7159.net/rfc7159) specifies: > An implementation may set limits on the maximum depth of nesting. -In this class, the object's limit of nesting is not explicitly constrained. -However, a maximum depth of nesting may be introduced by the compiler or -runtime environment. A theoretical limit can be queried by calling the +In this class, the object's limit of nesting is not explicitly constrained. However, a maximum depth of nesting may be +introduced by the compiler or runtime environment. A theoretical limit can be queried by calling the [`max_size`](max_size.md) function of a JSON object. #### Storage -Objects are stored as pointers in a `basic_json` type. That is, for any -access to object values, a pointer of type `object_t*` must be -dereferenced. +Objects are stored as pointers in a `basic_json` type. That is, for any access to object values, a pointer of type +`object_t*` must be dereferenced. #### Object key order -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 -7159](http://rfc7159.net/rfc7159), because any order implements the -specified "unordered" nature of JSON objects. +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 7159](http://rfc7159.net/rfc7159), because any order implements the specified "unordered" nature of JSON objects. ## Version history diff --git a/doc/mkdocs/docs/api/basic_json/operator+=.md b/doc/mkdocs/docs/api/basic_json/operator+=.md index 2cdac5c09..59001a58f 100644 --- a/doc/mkdocs/docs/api/basic_json/operator+=.md +++ b/doc/mkdocs/docs/api/basic_json/operator+=.md @@ -12,13 +12,11 @@ reference operator+=(const typename object_t::value_type& val); reference operator+=(initializer_list_t init); ``` -1. Appends the given element `val` to the end of the JSON array. If the - function is called on a JSON null value, an empty array is created before - appending `val`. +1. Appends the given element `val` to the end of the JSON array. If the function is called on a JSON null value, an + empty array is created before appending `val`. -2. Inserts the given element `val` to the JSON object. If the function is - called on a JSON null value, an empty object is created before inserting - `val`. +2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object + is created before inserting `val`. 3. This function allows to use `operator+=` with an initializer list. In case @@ -26,9 +24,8 @@ reference operator+=(initializer_list_t init); 2. the initializer list `init` contains only two elements, and 3. the first element of `init` is a string, - `init` is converted into an object element and added using - `operator+=(const typename object_t::value_type&)`. Otherwise, `init` - is converted to a JSON value and added using `operator+=(basic_json&&)`. + `init` is converted into an object element and added using `operator+=(const typename object_t::value_type&)`. + Otherwise, `init` is converted to a JSON value and added using `operator+=(basic_json&&)`. ## Parameters @@ -45,11 +42,11 @@ reference operator+=(initializer_list_t init); ## Exceptions 1. The function can throw the following exceptions: - - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON array or - null; example: `"cannot use operator+=() with number"` + - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than + JSON array or null; example: `"cannot use operator+=() with number"` 2. The function can throw the following exceptions: - - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON object or - null; example: `"cannot use operator+=() with number"` + - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than + JSON object or null; example: `"cannot use operator+=() with number"` ## Complexity @@ -59,18 +56,16 @@ reference operator+=(initializer_list_t init); ## Notes -(3) This function is required to resolve an ambiguous overload error, -because pairs like `{"key", "value"}` can be both interpreted as -`object_t::value_type` or `std::initializer_list`, see +(3) This function is required to resolve an ambiguous overload error, because pairs like `{"key", "value"}` can be both +interpreted as `object_t::value_type` or `std::initializer_list`, see [#235](https://github.com/nlohmann/json/issues/235) for more information. ## Examples ??? example - The example shows how `push_back()` and `+=` can be used to - add elements to a JSON array. Note how the `null` value was silently - converted to a JSON array. + The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value + was silently converted to a JSON array. ```cpp --8<-- "examples/push_back.cpp" @@ -84,9 +79,8 @@ because pairs like `{"key", "value"}` can be both interpreted as ??? example - The example shows how `push_back()` and `+=` can be used to - add elements to a JSON object. Note how the `null` value was silently - converted to a JSON object. + The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value + was silently converted to a JSON object. ```cpp --8<-- "examples/push_back__object_t__value.cpp" @@ -100,8 +94,7 @@ because pairs like `{"key", "value"}` can be both interpreted as ??? example - The example shows how initializer lists are treated as - objects when possible. + The example shows how initializer lists are treated as objects when possible. ```cpp --8<-- "examples/push_back__initializer_list.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/operator=.md b/doc/mkdocs/docs/api/basic_json/operator=.md index 7e32714f3..340f8eaf3 100644 --- a/doc/mkdocs/docs/api/basic_json/operator=.md +++ b/doc/mkdocs/docs/api/basic_json/operator=.md @@ -9,9 +9,8 @@ basic_json& operator=(basic_json other) noexcept ( ); ``` -Copy assignment operator. Copies a JSON value via the "copy and swap" -strategy: It is expressed in terms of the copy constructor, destructor, -and the `swap()` member function. +Copy assignment operator. Copies a JSON value via the "copy and swap" strategy: It is expressed in terms of the copy +constructor, destructor, and the `swap()` member function. ## Parameters @@ -26,10 +25,8 @@ Linear. ??? example - The code below shows and example for the copy assignment. It - creates a copy of value `a` which is then swapped with `b`. Finally\, the - copy of `a` (which is the null value after the swap) is - destroyed. + The code below shows and example for the copy assignment. It creates a copy of value `a` which is then swapped with + `b`. Finally, the copy of `a` (which is the null value after the swap) is destroyed. ```cpp --8<-- "examples/basic_json__copyassignment.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/operator==.md b/doc/mkdocs/docs/api/basic_json/operator==.md index f744d5a3c..d087d99cc 100644 --- a/doc/mkdocs/docs/api/basic_json/operator==.md +++ b/doc/mkdocs/docs/api/basic_json/operator==.md @@ -12,11 +12,10 @@ bool operator==(ScalarType lhs, const const_reference rhs) noexcept; Compares two JSON values for equality according to the following rules: -- Two JSON values are equal if (1) they are from the same type and (2) - their stored values are the same according to their respective - `operator==`. -- Integer and floating-point numbers are automatically converted before - comparison. Note that two NaN values are always treated as unequal. +- Two JSON values are equal if (1) they are from the same type and (2) their stored values are the same according to + their respective `operator==`. +- Integer and floating-point numbers are automatically converted before comparison. Note that two NaN values are always + treated as unequal. - Two JSON null values are equal. ## Template parameters @@ -46,11 +45,10 @@ Linear. ## Notes -- Floating-point inside JSON values numbers are compared with -`json::number_float_t::operator==` which is `double::operator==` by -default. To compare floating-point while respecting an epsilon, an alternative -[comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39) -could be used, for instance +- Floating-point inside JSON values numbers are compared with `json::number_float_t::operator==` which is + `double::operator==` by default. To compare floating-point while respecting an epsilon, an alternative + [comparison function](https://github.com/mariokonrad/marnav/blob/master/include/marnav/math/floatingpoint.hpp#L34-#L39) + could be used, for instance ```cpp template::value, T>::type> @@ -84,18 +82,19 @@ could be used, for instance ## Example -The example demonstrates comparing several JSON -types. +??? example + + The example demonstrates comparing several JSON types. + + ```cpp + --8<-- "examples/operator__equal.cpp" + ``` -```cpp ---8<-- "examples/operator__equal.cpp" -``` - -Output: - -```json ---8<-- "examples/operator__equal.output" -``` + Output: + + ```json + --8<-- "examples/operator__equal.output" + ``` ## Version history diff --git a/doc/mkdocs/docs/api/basic_json/operator[].md b/doc/mkdocs/docs/api/basic_json/operator[].md index 971a55123..4b36f1a91 100644 --- a/doc/mkdocs/docs/api/basic_json/operator[].md +++ b/doc/mkdocs/docs/api/basic_json/operator[].md @@ -47,51 +47,45 @@ const_reference operator[](const json_pointer& ptr) const; ## Exceptions 1. The function can throw the following exceptions: - - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array or null; in that - cases, using the `[]` operator with an index makes no sense. + - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array + or null; in that cases, using the `[]` operator with an index makes no sense. 2. The function can throw the following exceptions: - - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array or null; in that - cases, using the `[]` operator with an index makes no sense. + - Throws [`type_error.305`](../../home/exceptions.md#jsonexceptiontype_error305) if the JSON value is not an array + or null; in that cases, using the `[]` operator with an index makes no sense. 3. The function can throw the following exceptions: - - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed JSON pointer `ptr` - begins with '0'. - - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed JSON pointer `ptr` - is not a number. - - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used in the passed JSON - pointer `ptr` for the const version. - - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can not be resolved. + - Throws [`parse_error.106`](../../home/exceptions.md#jsonexceptionparse_error106) if an array index in the passed + JSON pointer `ptr` begins with '0'. + - Throws [`parse_error.109`](../../home/exceptions.md#jsonexceptionparse_error109) if an array index in the passed + JSON pointer `ptr` is not a number. + - Throws [`out_of_range.402`](../../home/exceptions.md#jsonexceptionout_of_range402) if the array index '-' is used + in the passed JSON pointer `ptr` for the const version. + - Throws [`out_of_range.404`](../../home/exceptions.md#jsonexceptionout_of_range404) if the JSON pointer `ptr` can + not be resolved. ## Notes !!! danger - 1. If the element with key `idx` does not exist, the behavior is - undefined. - 2. If the element with key `key` does not exist, the behavior is - undefined and is **guarded by an assertion**! + 1. If the element with key `idx` does not exist, the behavior is undefined. + 2. If the element with key `key` does not exist, the behavior is undefined and is **guarded by an assertion**! -1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), - then the array is silently filled up with `#!json null` values to make `idx` a - valid reference to the last stored element. - In case the value was `#!json null` before, it is converted to an array. +1. The non-const version may add values: If `idx` is beyond the range of the array (i.e., `idx >= size()`), then the + array is silently filled up with `#!json null` values to make `idx` a valid reference to the last stored element. In + case the value was `#!json null` before, it is converted to an array. -2. If `key` is not found in the object, then it is silently added to - the object and filled with a `#!json null` value to make `key` a valid reference. - In case the value was `#!json null` before, it is converted to an object. +2. If `key` is not found in the object, then it is silently added to the object and filled with a `#!json null` value to + make `key` a valid reference. In case the value was `#!json null` before, it is converted to an object. 3. `null` values are created in arrays and objects if necessary. In particular: - - If the JSON pointer points to an object key that does not exist, it - is created an filled with a `null` value before a reference to it - is returned. - - If the JSON pointer points to an array index that does not exist, it - is created an filled with a `null` value before a reference to it - is returned. All indices between the current maximum and the given - index are also filled with `null`. - - The special value `-` is treated as a synonym for the index past the - end. + - If the JSON pointer points to an object key that does not exist, it is created an filled with a `#!json null` + value before a reference to it is returned. + - If the JSON pointer points to an array index that does not exist, it is created an filled with a `#!json null` + value before a reference to it is returned. All indices between the current maximum and the given index are also + filled with `#!json null`. + - The special value `-` is treated as a synonym for the index past the end. ## Exception safety @@ -107,9 +101,8 @@ Strong exception safety: if an exception occurs, the original value stays intact ??? example - The example below shows how array elements can be read and - written using `[]` operator. Note the addition of `null` - values. + The example below shows how array elements can be read and written using `[]` operator. Note the addition of + `#!json null` values. ```cpp --8<-- "examples/operatorarray__size_type.cpp" @@ -123,8 +116,7 @@ Strong exception safety: if an exception occurs, the original value stays intact ??? example - The example below shows how array elements can be read using - the `[]` operator. + The example below shows how array elements can be read using the `[]` operator. ```cpp --8<-- "examples/operatorarray__size_type_const.cpp" @@ -138,8 +130,7 @@ Strong exception safety: if an exception occurs, the original value stays intact ??? example - The example below shows how object elements can be read and - written using the `[]` operator. + The example below shows how object elements can be read and written using the `[]` operator. ```cpp --8<-- "examples/operatorarray__key_type.cpp" @@ -153,8 +144,7 @@ Strong exception safety: if an exception occurs, the original value stays intact ??? example - The example below shows how object elements can be read using - the `[]` operator. + The example below shows how object elements can be read using the `[]` operator. ```cpp --8<-- "examples/operatorarray__key_type_const.cpp" 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 0681deb72..52125146c 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_value_t.md +++ b/doc/mkdocs/docs/api/basic_json/operator_value_t.md @@ -4,8 +4,7 @@ constexpr operator value_t() const noexcept; ``` -Return the type of the JSON value as a value from the [`value_t`](value_t.md) -enumeration. +Return the type of the JSON value as a value from the [`value_t`](value_t.md) enumeration. ## Return value @@ -36,8 +35,7 @@ Constant. ??? example - The following code exemplifies `operator value_t()` for all JSON - types. + The following code exemplifies `operator value_t()` for all JSON types. ```cpp --8<-- "examples/operator__value_t.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/parser_callback_t.md b/doc/mkdocs/docs/api/basic_json/parser_callback_t.md index 58fe645df..aeb7c2706 100644 --- a/doc/mkdocs/docs/api/basic_json/parser_callback_t.md +++ b/doc/mkdocs/docs/api/basic_json/parser_callback_t.md @@ -6,16 +6,13 @@ using parser_callback_t = std::function; ``` -With a parser callback function, the result of parsing a JSON text can be -influenced. When passed to [`parse`](parse.md), it is called on certain events -(passed as [`parse_event_t`](parse_event_t.md) 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`](parse.md), it is called on certain events (passed as [`parse_event_t`](parse_event_t.md) 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. -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` ------------------ | ----------- | ------------------ | ------------------- @@ -28,13 +25,13 @@ parameter `event` | description | parameter `depth` | parameter `parsed` ![Example when certain parse events are triggered](../../images/callback_events.png) -Discarding a value (i.e., returning `#!cpp false`) has different effects -depending on the context in which function was called: +Discarding a value (i.e., returning `#!cpp 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 `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 `null`. This case happens if the top-level + element is skipped. ## Parameters @@ -51,9 +48,8 @@ depending on the context in which function was called: ## Return value -Whether the JSON value which called the function during parsing -should be kept (`#!cpp true`) or not (`#!cpp false`). In the latter case, it is either -skipped completely or replaced by an empty discarded object. +Whether the JSON value which called the function during parsing should be kept (`#!cpp true`) or not (`#!cpp false`). In +the latter case, it is either skipped completely or replaced by an empty discarded object. # Example diff --git a/doc/mkdocs/docs/api/basic_json/patch.md b/doc/mkdocs/docs/api/basic_json/patch.md index 0434967e4..d73e9c0d3 100644 --- a/doc/mkdocs/docs/api/basic_json/patch.md +++ b/doc/mkdocs/docs/api/basic_json/patch.md @@ -4,10 +4,9 @@ basic_json patch(const basic_json& json_patch) const; ``` -[JSON Patch](http://jsonpatch.com) defines a JSON document structure for -expressing a sequence of operations to apply to a JSON) document. With -this function, a JSON Patch is applied to the current JSON value by -executing all operations from the patch. +[JSON Patch](http://jsonpatch.com) defines a JSON document structure for expressing a sequence of operations to apply to +a JSON) document. With this function, a JSON Patch is applied to the current JSON value by executing all operations from +the patch. ## Parameters @@ -20,40 +19,37 @@ patched document ## Exceptions -- Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of an array of - objects. -- Throws [`parse_error.105`](../../home/exceptions.md#jsonexceptionparse_error105) if the JSON patch is malformed (e.g., mandatory - attributes are missing); example: `"operation add must have member path"`. +- Throws [`parse_error.104`](../../home/exceptions.md#jsonexceptionparse_error104) if the JSON patch does not consist of + an array of objects. +- Throws [`parse_error.105`](../../home/exceptions.md#jsonexceptionparse_error105) if the JSON patch is malformed (e.g., + mandatory attributes are missing); example: `"operation add must have member path"`. - Throws [`out_of_range.401`](../../home/exceptions.md#jsonexceptionout_of_range401) if an array index is out of range. -- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a JSON pointer inside the patch could not be - resolved successfully in the current JSON value; example: `"key baz not found"`. -- Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent ("add", "remove", "move") -- Throws [`out_of_range.501`](../../home/exceptions.md#jsonexceptionother_error501) if "test" operation was unsuccessful. +- Throws [`out_of_range.403`](../../home/exceptions.md#jsonexceptionout_of_range403) if a JSON pointer inside the patch + could not be resolved successfully in the current JSON value; example: `"key baz not found"`. +- Throws [`out_of_range.405`](../../home/exceptions.md#jsonexceptionout_of_range405) if JSON pointer has no parent + ("add", "remove", "move") +- 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. +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. +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 -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. +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 ??? example - The following code shows how a JSON patch is applied to a - value. + The following code shows how a JSON patch is applied to a value. ```cpp --8<-- "examples/patch.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/push_back.md b/doc/mkdocs/docs/api/basic_json/push_back.md index 7795c380c..c10c94a3e 100644 --- a/doc/mkdocs/docs/api/basic_json/push_back.md +++ b/doc/mkdocs/docs/api/basic_json/push_back.md @@ -12,13 +12,11 @@ void push_back(const typename object_t::value_type& val); void push_back(initializer_list_t init); ``` -1. Appends the given element `val` to the end of the JSON array. If the - function is called on a JSON null value, an empty array is created before - appending `val`. +1. Appends the given element `val` to the end of the JSON array. If the function is called on a JSON null value, an + empty array is created before appending `val`. -2. Inserts the given element `val` to the JSON object. If the function is - called on a JSON null value, an empty object is created before inserting - `val`. +2. Inserts the given element `val` to the JSON object. If the function is called on a JSON null value, an empty object + is created before inserting `val`. 3. This function allows to use `push_back` with an initializer list. In case @@ -26,9 +24,8 @@ void push_back(initializer_list_t init); 2. the initializer list `init` contains only two elements, and 3. the first element of `init` is a string, - `init` is converted into an object element and added using - `push_back(const typename object_t::value_type&)`. Otherwise, `init` - is converted to a JSON value and added using `push_back(basic_json&&)`. + `init` is converted into an object element and added using `push_back(const typename object_t::value_type&)`. + Otherwise, `init` is converted to a JSON value and added using `push_back(basic_json&&)`. ## Parameters @@ -41,11 +38,11 @@ void push_back(initializer_list_t init); ## Exceptions 1. The function can throw the following exceptions: - - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON array or - null; example: `"cannot use push_back() with number"` + - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than + JSON array or null; example: `"cannot use push_back() with number"` 2. The function can throw the following exceptions: - - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than JSON object or - null; example: `"cannot use push_back() with number"` + - Throws [`type_error.308`](../../home/exceptions.md#jsonexceptiontype_error308) when called on a type other than + JSON object or null; example: `"cannot use push_back() with number"` ## Complexity @@ -55,18 +52,16 @@ void push_back(initializer_list_t init); ## Notes -(3) This function is required to resolve an ambiguous overload error, -because pairs like `{"key", "value"}` can be both interpreted as -`object_t::value_type` or `std::initializer_list`, see -[#235](https://github.com/nlohmann/json/issues/235) for more information. +(3) This function is required to resolve an ambiguous overload error, because pairs like `{"key", "value"}` can be both + interpreted as `object_t::value_type` or `std::initializer_list`, see + [#235](https://github.com/nlohmann/json/issues/235) for more information. ## Examples ??? example - The example shows how `push_back()` and `+=` can be used to - add elements to a JSON array. Note how the `null` value was silently - converted to a JSON array. + The example shows how `push_back()` and `+=` can be used to add elements to a JSON array. Note how the `null` value + was silently converted to a JSON array. ```cpp --8<-- "examples/push_back.cpp" @@ -80,9 +75,8 @@ because pairs like `{"key", "value"}` can be both interpreted as ??? example - The example shows how `push_back()` and `+=` can be used to - add elements to a JSON object. Note how the `null` value was silently - converted to a JSON object. + The example shows how `push_back()` and `+=` can be used to add elements to a JSON object. Note how the `null` value + was silently converted to a JSON object. ```cpp --8<-- "examples/push_back__object_t__value.cpp" @@ -96,8 +90,7 @@ because pairs like `{"key", "value"}` can be both interpreted as ??? example - The example shows how initializer lists are treated as - objects when possible. + The example shows how initializer lists are treated as objects when possible. ```cpp --8<-- "examples/push_back__initializer_list.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/rend.md b/doc/mkdocs/docs/api/basic_json/rend.md index 679c1a6f3..5d5f21310 100644 --- a/doc/mkdocs/docs/api/basic_json/rend.md +++ b/doc/mkdocs/docs/api/basic_json/rend.md @@ -5,8 +5,8 @@ reverse_iterator rend() noexcept; const_reverse_iterator rend() const noexcept; ``` -Returns an iterator to the reverse-end; that is, one before the first -element. This element acts as a placeholder, attempting to access it results in undefined behavior. +Returns an iterator to the reverse-end; that is, one before the first element. This element acts as a placeholder, +attempting to access it results in undefined behavior. ![Illustration from cppreference.com](../../images/range-rbegin-rend.svg) diff --git a/doc/mkdocs/docs/api/basic_json/sax_parse.md b/doc/mkdocs/docs/api/basic_json/sax_parse.md index 14ef68648..0bb745805 100644 --- a/doc/mkdocs/docs/api/basic_json/sax_parse.md +++ b/doc/mkdocs/docs/api/basic_json/sax_parse.md @@ -23,8 +23,8 @@ Read from input and generate SAX events 1. Read from a compatible input. 2. Read from a pair of character iterators - The value_type of the iterator must be a integral type with size of 1, 2 or - 4 bytes, which will be interpreted respectively as UTF-8, UTF-16 and UTF-32. + The value_type of the iterator must be a integral type with size of 1, 2 or 4 bytes, which will be interpreted + respectively as UTF-8, UTF-16 and UTF-32. The SAX event lister must follow the interface of `json_sax`. @@ -61,9 +61,8 @@ The SAX event lister must follow the interface of `json_sax`. : whether the input has to be consumed completely (optional, `#!cpp true` by default) `ignore_comments` (in) -: whether comments should be ignored and treated - like whitespace (`#!cpp true`) or yield a parse error (`#!cpp false`); (optional, `#!cpp false` by - default) +: whether comments should be ignored and treated like whitespace (`#!cpp true`) or yield a parse error + (`#!cpp false`); (optional, `#!cpp false` by default) `first` (in) : iterator to start of character range @@ -79,9 +78,8 @@ return value of the last processed SAX event ## Complexity -Linear in the length of the input. The parser is a predictive -LL(1) parser. The complexity can be higher if the SAX consumer `sax` has -a super-linear complexity. +Linear in the length of the input. The parser is a predictive LL(1) parser. The complexity can be higher if the SAX +consumer `sax` has a super-linear complexity. ## Notes @@ -91,9 +89,8 @@ A UTF-8 byte order mark is silently ignored. ??? example - The example below demonstrates the `sax_parse()` function - reading from string and processing the events with a user-defined SAX - event consumer. + The example below demonstrates the `sax_parse()` function reading from string and processing the events with a + user-defined SAX event consumer. ```cpp --8<-- "examples/sax_parse.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/size.md b/doc/mkdocs/docs/api/basic_json/size.md index 125d80822..36a9daeb6 100644 --- a/doc/mkdocs/docs/api/basic_json/size.md +++ b/doc/mkdocs/docs/api/basic_json/size.md @@ -8,8 +8,7 @@ Returns the number of elements in a JSON value. ## Return value -The return value depends on the different types and is -defined as follows: +The return value depends on the different types and is defined as follows: Value type | return value ----------- | ------------- @@ -27,22 +26,20 @@ No-throw guarantee: this function never throws exceptions. ## Complexity -Constant, as long as [`array_t`](array_t.md) and [`object_t`](object_t.md) satisfy -the Container concept; that is, their `size()` functions have constant -complexity. +Constant, as long as [`array_t`](array_t.md) and [`object_t`](object_t.md) satisfy the +[Container](https://en.cppreference.com/w/cpp/named_req/Container) concept; that is, their `size()` functions have +constant complexity. ## Notes -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. +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 ??? example - The following code calls `size()` on the different value - types. + The following code calls `size()` on the different value types. ```cpp --8<-- "examples/size.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/string_t.md b/doc/mkdocs/docs/api/basic_json/string_t.md index cee6016e1..acdd351b5 100644 --- a/doc/mkdocs/docs/api/basic_json/string_t.md +++ b/doc/mkdocs/docs/api/basic_json/string_t.md @@ -9,53 +9,41 @@ The type used to store JSON strings. [RFC 7159](http://rfc7159.net/rfc7159) describes JSON strings as follows: > A string is a sequence of zero or more Unicode characters. -To store objects in C++, a type is defined by the template parameter -described below. Unicode values are split by the JSON class into -byte-sized characters during deserialization. +To store objects in C++, a type is defined by the template parameter described below. Unicode values are split by the +JSON class into byte-sized characters during deserialization. ## Template parameters `StringType` -: the container to store strings (e.g., `std::string`). - Note this container is used for keys/names in objects, see [object_t](object_t.md). +: the container to store strings (e.g., `std::string`). Note this container is used for keys/names in objects, see + [object_t](object_t.md). ## Notes #### Default type -With the default values for `StringType` (`std::string`), the default -value for `string_t` is: - -```cpp -std::string -``` +With the default values for `StringType` (`std::string`), the default value for `string_t` is `#!cpp std::string`. #### Encoding -Strings are stored in UTF-8 encoding. Therefore, functions like -`std::string::size()` or `std::string::length()` return the number of -bytes in the string rather than the number of characters or glyphs. +Strings are stored in UTF-8 encoding. Therefore, functions like `std::string::size()` or `std::string::length()` return +the number of bytes in the string rather than the number of characters or glyphs. #### String comparison [RFC 7159](http://rfc7159.net/rfc7159) states: -> Software implementations are typically required to test names of object -> members for equality. Implementations that transform the textual -> representation into sequences of Unicode code units and then perform the -> comparison numerically, code unit by code unit, are interoperable in the -> sense that implementations will agree in all cases on equality or -> inequality of two strings. For example, implementations that compare -> strings with escaped characters unconverted may incorrectly find that -> `"a\\b"` and `"a\u005Cb"` are not equal. +> Software implementations are typically required to test names of object members for equality. Implementations that +> transform the textual representation into sequences of Unicode code units and then perform the comparison numerically, +> code unit by code unit, are interoperable in the sense that implementations will agree in all cases on equality or +> inequality of two strings. For example, implementations that compare strings with escaped characters unconverted may +> incorrectly find that `"a\\b"` and `"a\u005Cb"` are not equal. -This implementation is interoperable as it does compare strings code unit -by code unit. +This implementation is interoperable as it does compare strings code unit by code unit. #### Storage -String values are stored as pointers in a `basic_json` type. That is, -for any access to string values, a pointer of type `string_t*` must be -dereferenced. +String values are stored as pointers in a `basic_json` type. That is, for any access to string values, a pointer of type +`string_t*` must be dereferenced. ## Version history diff --git a/doc/mkdocs/docs/api/basic_json/type.md b/doc/mkdocs/docs/api/basic_json/type.md index bede413d7..b3482117b 100644 --- a/doc/mkdocs/docs/api/basic_json/type.md +++ b/doc/mkdocs/docs/api/basic_json/type.md @@ -4,9 +4,8 @@ constexpr value_t type() const noexcept; ``` -Return the type of the JSON value as a value from the [`value_t`](value_t.md) -enumeration. - +Return the type of the JSON value as a value from the [`value_t`](value_t.md) enumeration. + ## Return value the type of the JSON value @@ -36,8 +35,7 @@ Constant. ??? example - The following code exemplifies `type()` for all JSON - types. + The following code exemplifies `type()` for all JSON types. ```cpp --8<-- "examples/type.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/type_name.md b/doc/mkdocs/docs/api/basic_json/type_name.md index 714ad2f30..1a1752610 100644 --- a/doc/mkdocs/docs/api/basic_json/type_name.md +++ b/doc/mkdocs/docs/api/basic_json/type_name.md @@ -4,8 +4,8 @@ const char* type_name() const noexcept; ``` -Returns the type name as string to be used in error messages - usually to -indicate that a function was called on a wrong JSON type. +Returns the type name as string to be used in error messages -- usually to indicate that a function was called on a +wrong JSON type. ## Return value @@ -34,8 +34,7 @@ Constant. ??? example - The following code exemplifies `type_name()` for all JSON - types. + The following code exemplifies `type_name()` for all JSON types. ```cpp --8<-- "examples/type_name.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/unflatten.md b/doc/mkdocs/docs/api/basic_json/unflatten.md index 9e6afe800..379428639 100644 --- a/doc/mkdocs/docs/api/basic_json/unflatten.md +++ b/doc/mkdocs/docs/api/basic_json/unflatten.md @@ -4,13 +4,11 @@ basic_json unflatten() const; ``` -The function restores the arbitrary nesting of a JSON value that has been -flattened before using the [`flatten()`](flatten.md) function. The JSON value must -meet certain constraints: +The function restores the arbitrary nesting of a JSON value that has been flattened before using the +[`flatten()`](flatten.md) function. The JSON value must meet certain constraints: 1. The value must be an object. -2. The keys must be JSON pointers (see - [RFC 6901](https://tools.ietf.org/html/rfc6901)) +2. The keys must be JSON pointers (see [RFC 6901](https://tools.ietf.org/html/rfc6901)) 3. The mapped values must be primitive JSON types. ## Return value @@ -34,17 +32,15 @@ Linear in the size the JSON value. ## Notes -Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` -values and can not unflattened to their original type. Apart from -this example, for a JSON value `j`, the following is always true: +Empty objects and arrays are flattened by [`flatten()`](flatten.md) to `#!json null` values and can not unflattened to +their original type. Apart from this example, for a JSON value `j`, the following is always true: `#!cpp j == j.flatten().unflatten()`. ## Example ??? example - The following code shows how a flattened JSON object is - unflattened into the original nested JSON object. + The following code shows how a flattened JSON object is unflattened into the original nested JSON object. ```cpp --8<-- "examples/unflatten.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/update.md b/doc/mkdocs/docs/api/basic_json/update.md index 3a71b8c5e..9c237118b 100644 --- a/doc/mkdocs/docs/api/basic_json/update.md +++ b/doc/mkdocs/docs/api/basic_json/update.md @@ -11,7 +11,8 @@ void update(const_iterator first, const_iterator last); 1. Inserts all values from JSON object `j` and overwrites existing keys. 2. Inserts all values from from range `[first, last)` and overwrites existing keys. -The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update) function. +The function is motivated by Python's [dict.update](https://docs.python.org/3.6/library/stdtypes.html#dict.update) +function. ## Parameters @@ -27,16 +28,15 @@ The function is motivated by Python's [dict.update](https://docs.python.org/3.6/ ## Exceptions 1. The function can throw thw following exceptions: - - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than objects; - example: `"cannot use update() with string"` + - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than + objects; example: `"cannot use update() with string"` 2. The function can throw thw following exceptions: - - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than objects; - example: `"cannot use update() with string"` - - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an iterator which does not belong - to the current JSON value; example: `"iterator does not fit current - value"` - - 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"` + - Throws [`type_error.312`](../../home/exceptions.md#jsonexceptiontype_error312) if called on JSON values other than + objects; example: `"cannot use update() with string"` + - Throws [`invalid_iterator.202`](../../home/exceptions.md#jsonexceptioninvalid_iterator202) if called on an + iterator which does not belong to the current JSON value; example: `"iterator does not fit current value"` + - 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"` ## Complexity diff --git a/doc/mkdocs/docs/api/basic_json/value.md b/doc/mkdocs/docs/api/basic_json/value.md index f34c76f00..8fdbc238f 100644 --- a/doc/mkdocs/docs/api/basic_json/value.md +++ b/doc/mkdocs/docs/api/basic_json/value.md @@ -12,8 +12,8 @@ ValueType value(const json_pointer& ptr, const ValueType& default_value) const; ``` -1. Returns either a copy of an object's element at the specified key `key` - or a given default value if no element with key `key` exists. +1. Returns either a copy of an object's element at the specified key `key` or a given default value if no element with + key `key` exists. The function is basically equivalent to executing ```cpp @@ -24,8 +24,8 @@ ValueType value(const json_pointer& ptr, } ``` -2. Returns either a copy of an object's element at the specified JSON pointer `ptr` - or a given default value if no value at `ptr` exists. +2. Returns either a copy of an object's element at the specified JSON pointer `ptr` or a given default value if no value + at `ptr` exists. The function is basically equivalent to executing ```cpp @@ -36,16 +36,14 @@ ValueType value(const json_pointer& ptr, } ``` -Unlike [`operator[]`](operator[].md), this -function does not implicitly add an element to the position defined by `key`/`ptr` -key. This function is furthermore also applicable to const objects. +Unlike [`operator[]`](operator[].md), this function does not implicitly add an element to the position defined by +`key`/`ptr` key. This function is furthermore also applicable to const objects. ## Template parameters `ValueType` -: type compatible to JSON values, for instance `#!cpp int` for - JSON integer numbers, `#!cpp bool` for JSON booleans, or `#!cpp std::vector` types for - JSON arrays. Note the type of the expected value at `key`/`ptr` and the default +: type compatible to JSON values, for instance `#!cpp int` for JSON integer numbers, `#!cpp bool` for JSON booleans, + or `#!cpp std::vector` types for JSON arrays. Note the type of the expected value at `key`/`ptr` and the default value `default_value` must be compatible. ## Parameters @@ -72,15 +70,15 @@ changes to any JSON value. ## Exceptions 1. The function can throw thw following exceptions: - - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match the type of the - value at `key` - - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object; in that case, - using `value()` with a key makes no sense. + - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match + the type of the value at `key` + - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object; + in that case, using `value()` with a key makes no sense. 2. The function can throw thw following exceptions: - - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match the type of the - value at `ptr` - - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object; in that case, - using `value()` with a key makes no sense. + - Throws [`type_error.302`](../../home/exceptions.md#jsonexceptiontype_error302) if `default_value` does not match + the type of the value at `ptr` + - Throws [`type_error.306`](../../home/exceptions.md#jsonexceptiontype_error306) if the JSON value is not an object; + in that case, using `value()` with a key makes no sense. ## Complexity @@ -91,8 +89,7 @@ changes to any JSON value. ??? example - The example below shows how object elements can be queried - with a default value. + The example below shows how object elements can be queried with a default value. ```cpp --8<-- "examples/basic_json__value.cpp" @@ -106,8 +103,7 @@ changes to any JSON value. ??? example - The example below shows how object elements can be queried - with a default value. + The example below shows how object elements can be queried with a default value. ```cpp --8<-- "examples/basic_json__value_ptr.cpp" diff --git a/doc/mkdocs/docs/api/basic_json/value_t.md b/doc/mkdocs/docs/api/basic_json/value_t.md index e8979be86..5fa9501fc 100644 --- a/doc/mkdocs/docs/api/basic_json/value_t.md +++ b/doc/mkdocs/docs/api/basic_json/value_t.md @@ -15,23 +15,19 @@ enum class value_t : std::uint8_t { }; ``` -This enumeration collects the different JSON types. It is internally used to -distinguish the stored values, and the functions [`is_null`](is_null.md), -[`is_object`](is_object.md), [`is_array`](is_array.md), -[`is_string`](is_string.md), [`is_boolean`](is_boolean.md), -[`is_number`](is_number.md) (with [`is_number_integer`](is_number_integer.md), +This enumeration collects the different JSON types. It is internally used to distinguish the stored values, and the +functions [`is_null`](is_null.md), [`is_object`](is_object.md), [`is_array`](is_array.md), [`is_string`](is_string.md), +[`is_boolean`](is_boolean.md), [`is_number`](is_number.md) (with [`is_number_integer`](is_number_integer.md), [`is_number_unsigned`](is_number_unsigned.md), and [`is_number_float`](is_number_float.md)), [`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 -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, -[`number_integer_t`](number_integer_t.md) is used for signed integers, and -[`number_float_t`](number_float_t.md) is used for floating-point numbers or to -approximate integers which do not fit in the limits of their respective type. +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, +[`number_integer_t`](number_integer_t.md) is used for signed integers, and [`number_float_t`](number_float_t.md) is used +for floating-point numbers or to approximate integers which do not fit in the limits of their respective type. ## Version history