From df12a090e8dee24c411b3f0af3bfc8a4136dcdea Mon Sep 17 00:00:00 2001 From: Florian Albrechtskirchinger Date: Sat, 23 Jul 2022 19:14:38 +0200 Subject: [PATCH] Update documentation --- .../docs/api/basic_json/operator_gtgt.md | 16 +++--- .../docs/api/basic_json/operator_ltlt.md | 55 +++++++++++-------- .../docs/api/json_pointer/operator_string.md | 9 ++- docs/mkdocs/mkdocs.yml | 2 +- 4 files changed, 50 insertions(+), 32 deletions(-) diff --git a/docs/mkdocs/docs/api/basic_json/operator_gtgt.md b/docs/mkdocs/docs/api/basic_json/operator_gtgt.md index 97c2f0b4e..b18f9bb27 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_gtgt.md +++ b/docs/mkdocs/docs/api/basic_json/operator_gtgt.md @@ -1,4 +1,4 @@ -# operator>>(basic_json) +# nlohmann::operator>>(basic_json) ```cpp std::istream& operator>>(std::istream& i, basic_json& j); @@ -33,6 +33,12 @@ Linear in the length of the input. The parser is a predictive LL(1) parser. A UTF-8 byte order mark is silently ignored. +!!! warning "Deprecation" + + This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has + been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;` + with `#!cpp i >> j;`. + ## Examples ??? example @@ -56,10 +62,4 @@ A UTF-8 byte order mark is silently ignored. ## Version history -- Added in version 1.0.0 - -!!! warning "Deprecation" - - This function replaces function `#!cpp std::istream& operator<<(basic_json& j, std::istream& i)` which has - been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j << i;` - with `#!cpp i >> j;`. +- Added in version 1.0.0. Deprecated in version 3.0.0. diff --git a/docs/mkdocs/docs/api/basic_json/operator_ltlt.md b/docs/mkdocs/docs/api/basic_json/operator_ltlt.md index 0cba5ea3c..e56ec14f2 100644 --- a/docs/mkdocs/docs/api/basic_json/operator_ltlt.md +++ b/docs/mkdocs/docs/api/basic_json/operator_ltlt.md @@ -1,42 +1,58 @@ -# operator<<(basic_json) +# nlohmann::operator<<(basic_json), nlohmann::operator<<(json_pointer) ```cpp -std::ostream& operator<<(std::ostream& o, const basic_json& j); +std::ostream& operator<<(std::ostream& o, const basic_json& j); // (1) + +std::ostream& operator<<(std::ostream& o, const json_pointer& ptr); // (2) ``` -Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the -[`dump`](dump.md) member function. - -- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For - instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization result - is the same as calling `dump(4)`. -- The indentation character can be controlled with the member variable `fill` of the output stream `o`. For instance, - the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the default space character. +1. Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the + [`dump`](dump.md) member function. + - The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For + instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4` and the serialization + result is the same as calling `dump(4)`. + - The indentation character can be controlled with the member variable `fill` of the output stream `o`. + For instance, the manipulator `std::setfill('\\t')` sets indentation to use a tab character rather than the + default space character. +2. Write a string representation of the given JSON pointer `ptr` to the output stream `o`. The string representation is + obtained using the [`to_string`](../json_pointer/to_string.md) member function. ## Parameters `o` (in, out) -: stream to serialize to +: stream to write to `j` (in) : JSON value to serialize +`ptr` (in) +: JSON pointer to write + ## Return value the stream `o` ## Exceptions -Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON value -is not UTF-8 encoded. Note that unlike the [`dump`](dump.md) member functions, no `error_handler` can be set. +1. Throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) if a string stored inside the JSON + value is not UTF-8 encoded. Note that unlike the [`dump`](dump.md) member functions, no `error_handler` can be set. +2. None. ## Complexity Linear. +## Notes + +!!! warning "Deprecation" + + Function `#!cpp std::ostream& operator<<(std::ostream& o, const basic_json& j)` replaces function + `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has been deprecated in version 3.0.0. + It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;` with `#!cpp o << j;`. + ## Examples -??? example +??? example "Example: (1) serialize JSON value to stream" The example below shows the serialization with different parameters to `width` to adjust the indentation level. @@ -52,11 +68,6 @@ Linear. ## Version history -- Added in version 1.0.0 -- Support for indentation character added in version 3.0.0. - -!!! warning "Deprecation" - - This function replaces function `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` which has - been deprecated in version 3.0.0. It will be removed in version 4.0.0. Please replace calls like `#!cpp j >> o;` - with `#!cpp o << j;`. +1. Added in version 1.0.0. Added support for indentation character and deprecated + `#!cpp std::ostream& operator>>(const basic_json& j, std::ostream& o)` in version 3.0.0. +3. Added in version 3.11.0. diff --git a/docs/mkdocs/docs/api/json_pointer/operator_string.md b/docs/mkdocs/docs/api/json_pointer/operator_string.md index f2f99cae7..ec49ba4f6 100644 --- a/docs/mkdocs/docs/api/json_pointer/operator_string.md +++ b/docs/mkdocs/docs/api/json_pointer/operator_string.md @@ -19,6 +19,13 @@ operator string_t() const } ``` +## Notes + +!!! warning "Deprecation" + + This function is deprecated in favor of [`to_string`](to_string.md) and will be removed in a future major version + release. + ## Examples ??? example @@ -38,4 +45,4 @@ operator string_t() const ## Version history - Since version 2.0.0. -- Changed type to `string_t` in version 3.11.0. +- Changed type to `string_t` and deprecated in version 3.11.0. diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index fe822b0c8..2030a9f58 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/docs/mkdocs/mkdocs.yml @@ -212,7 +212,7 @@ nav: - '(Constructor)': api/json_pointer/json_pointer.md - 'back': api/json_pointer/back.md - 'empty': api/json_pointer/empty.md - - 'operator std::string': api/json_pointer/operator_string.md + - 'operator string_t': api/json_pointer/operator_string.md - 'operator/': api/json_pointer/operator_slash.md - 'operator/=': api/json_pointer/operator_slasheq.md - 'parent_pointer': api/json_pointer/parent_pointer.md