From ca5ecc29457ac615e2cd08435e877638100e3333 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Wed, 3 Nov 2021 14:51:19 +0100 Subject: [PATCH] :fire: consolidate documentation --- doc/mkdocs/docs/api/basic_json/index.md | 2 +- .../docs/api/basic_json/operator_gtgt.md | 58 ++++++++++++++++++ .../docs/api/basic_json/operator_ltlt.md | 1 + doc/mkdocs/mkdocs.yml | 1 + include/nlohmann/json.hpp | 60 ++++++------------- single_include/nlohmann/json.hpp | 60 ++++++------------- 6 files changed, 99 insertions(+), 83 deletions(-) create mode 100644 doc/mkdocs/docs/api/basic_json/operator_gtgt.md diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 5a9506798..6dedba231 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -280,7 +280,7 @@ Access to the JSON value ## Non-member functions - [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream -- operator>>(std::istream&) - deserialize from stream +- [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream ## Literals diff --git a/doc/mkdocs/docs/api/basic_json/operator_gtgt.md b/doc/mkdocs/docs/api/basic_json/operator_gtgt.md new file mode 100644 index 000000000..99079d002 --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/operator_gtgt.md @@ -0,0 +1,58 @@ +# operator>>(basic_json) + +```cpp +std::istream& operator>>(std::istream& i, basic_json& j) +``` + +Deserializes an input stream to a JSON value. + +## Parameters + +`i` (in, out) +: input stream to read a serialized JSON value from + +`j` (in, out) +: JSON value to write the deserialized input to + +## Return value + +the stream `i` + +## Exceptions + +- Throws [`parse_error.101`](../../home/exceptions.md#jsonexceptionparse_error101) in case of an unexpected token. +- Throws [`parse_error.102`](../../home/exceptions.md#jsonexceptionparse_error102) if to_unicode fails or surrogate + error. +- Throws [`parse_error.103`](../../home/exceptions.md#jsonexceptionparse_error103) if to_unicode fails. + +## Complexity + +Linear in the length of the input. The parser is a predictive LL(1) parser. + +## Note + +A UTF-8 byte order mark is silently ignored. + +## Example + +??? example + + The example below shows how a JSON value is constructed by reading a serialization from a stream. + + ```cpp + --8<-- "examples/operator_deserialize.cpp" + ``` + + Output: + + ```json + --8<-- "examples/operator_deserialize.output" + ``` + +## See also + +- [parse](parse.md) for a variant with a parser callback function to filter values while parsing + +## Version history + +- Added in version 1.0.0 diff --git a/doc/mkdocs/docs/api/basic_json/operator_ltlt.md b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md index deb21563f..4ff023687 100644 --- a/doc/mkdocs/docs/api/basic_json/operator_ltlt.md +++ b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md @@ -3,6 +3,7 @@ ```cpp std::ostream& operator<<(std::ostream& o, const basic_json& j) ``` + Serialize the given JSON value `j` to the output stream `o`. The JSON value will be serialized using the [`dump`](dump.md) member function. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 520e1e319..22c5a4f85 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -151,6 +151,7 @@ nav: - api/basic_json/operator_ltlt.md - api/basic_json/operator_le.md - api/basic_json/operator_gt.md + - api/basic_json/operator_gtgt.md - api/basic_json/operator_ge.md - api/basic_json/operator+=.md - api/basic_json/operator_literal_json.md diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 19fc9da39..8140702de 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -3640,14 +3640,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return o; } - /*! - @brief serialize to stream - @deprecated This stream operator is deprecated and will be removed in - future 4.0.0 of the library. Please use - @ref operator<<(std::ostream&, const basic_json&) - instead; that is, replace calls like `j >> o;` with `o << j;`. - @since version 1.0.0; deprecated since version 3.0.0 - */ + /// @brief serialize to stream + /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/ + /// @deprecated This function is deprecated since 3.0.0 and will be removed in + /// version 4.0.0 of the library. Please use + /// operator<<(std::ostream&, const basic_json&) instead; that is, + /// replace calls like `j >> o;` with `o << j;`. JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator<<(std::ostream&, const basic_json&)) friend std::ostream& operator>>(const basic_json& j, std::ostream& o) { @@ -3761,6 +3759,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec : detail::binary_reader(std::move(ia)).sax_parse(format, sax, strict); } + /// @brief generate SAX events + /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/ + /// @deprecated This function is deprecated since 3.8.0 and will be removed in + /// version 4.0.0 of the library. Please use + /// sax_parse(ptr, ptr + len) instead. template JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...)) JSON_HEDLEY_NON_NULL(2) @@ -3777,45 +3780,20 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec : detail::binary_reader(std::move(ia)).sax_parse(format, sax, strict); } #ifndef JSON_NO_IO - /*! - @brief deserialize from stream - @deprecated This stream operator is deprecated and will be removed in - version 4.0.0 of the library. Please use - @ref operator>>(std::istream&, basic_json&) - instead; that is, replace calls like `j << i;` with `i >> j;`. - @since version 1.0.0; deprecated since version 3.0.0 - */ + /// @brief deserialize from stream + /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/ + /// @deprecated This stream operator is deprecated since 3.0.0 and will be removed in + /// version 4.0.0 of the library. Please use + /// operator>>(std::istream&, basic_json&) instead; that is, + /// replace calls like `j << i;` with `i >> j;`. JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator>>(std::istream&, basic_json&)) friend std::istream& operator<<(basic_json& j, std::istream& i) { return operator>>(i, j); } - /*! - @brief deserialize from stream - - Deserializes an input stream to a JSON value. - - @param[in,out] i input stream to read a serialized JSON value from - @param[in,out] j JSON value to write the deserialized input to - - @throw parse_error.101 in case of an unexpected token - @throw parse_error.102 if to_unicode fails or surrogate error - @throw parse_error.103 if to_unicode fails - - @complexity Linear in the length of the input. The parser is a predictive - LL(1) parser. - - @note A UTF-8 byte order mark is silently ignored. - - @liveexample{The example below shows how a JSON value is constructed by - reading a serialization from a stream.,operator_deserialize} - - @sa parse(std::istream&, const parser_callback_t) for a variant with a - parser callback function to filter values while parsing - - @since version 1.0.0 - */ + /// @brief deserialize from stream + /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/ friend std::istream& operator>>(std::istream& i, basic_json& j) { parser(detail::input_adapter(i)).parse(false, j); diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 3b7d86671..8e933daa6 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -21141,14 +21141,12 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec return o; } - /*! - @brief serialize to stream - @deprecated This stream operator is deprecated and will be removed in - future 4.0.0 of the library. Please use - @ref operator<<(std::ostream&, const basic_json&) - instead; that is, replace calls like `j >> o;` with `o << j;`. - @since version 1.0.0; deprecated since version 3.0.0 - */ + /// @brief serialize to stream + /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/ + /// @deprecated This function is deprecated since 3.0.0 and will be removed in + /// version 4.0.0 of the library. Please use + /// operator<<(std::ostream&, const basic_json&) instead; that is, + /// replace calls like `j >> o;` with `o << j;`. JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator<<(std::ostream&, const basic_json&)) friend std::ostream& operator>>(const basic_json& j, std::ostream& o) { @@ -21262,6 +21260,11 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec : detail::binary_reader(std::move(ia)).sax_parse(format, sax, strict); } + /// @brief generate SAX events + /// @sa https://json.nlohmann.me/api/basic_json/sax_parse/ + /// @deprecated This function is deprecated since 3.8.0 and will be removed in + /// version 4.0.0 of the library. Please use + /// sax_parse(ptr, ptr + len) instead. template JSON_HEDLEY_DEPRECATED_FOR(3.8.0, sax_parse(ptr, ptr + len, ...)) JSON_HEDLEY_NON_NULL(2) @@ -21278,45 +21281,20 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec : detail::binary_reader(std::move(ia)).sax_parse(format, sax, strict); } #ifndef JSON_NO_IO - /*! - @brief deserialize from stream - @deprecated This stream operator is deprecated and will be removed in - version 4.0.0 of the library. Please use - @ref operator>>(std::istream&, basic_json&) - instead; that is, replace calls like `j << i;` with `i >> j;`. - @since version 1.0.0; deprecated since version 3.0.0 - */ + /// @brief deserialize from stream + /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/ + /// @deprecated This stream operator is deprecated since 3.0.0 and will be removed in + /// version 4.0.0 of the library. Please use + /// operator>>(std::istream&, basic_json&) instead; that is, + /// replace calls like `j << i;` with `i >> j;`. JSON_HEDLEY_DEPRECATED_FOR(3.0.0, operator>>(std::istream&, basic_json&)) friend std::istream& operator<<(basic_json& j, std::istream& i) { return operator>>(i, j); } - /*! - @brief deserialize from stream - - Deserializes an input stream to a JSON value. - - @param[in,out] i input stream to read a serialized JSON value from - @param[in,out] j JSON value to write the deserialized input to - - @throw parse_error.101 in case of an unexpected token - @throw parse_error.102 if to_unicode fails or surrogate error - @throw parse_error.103 if to_unicode fails - - @complexity Linear in the length of the input. The parser is a predictive - LL(1) parser. - - @note A UTF-8 byte order mark is silently ignored. - - @liveexample{The example below shows how a JSON value is constructed by - reading a serialization from a stream.,operator_deserialize} - - @sa parse(std::istream&, const parser_callback_t) for a variant with a - parser callback function to filter values while parsing - - @since version 1.0.0 - */ + /// @brief deserialize from stream + /// @sa https://json.nlohmann.me/api/basic_json/operator_gtgt/ friend std::istream& operator>>(std::istream& i, basic_json& j) { parser(detail::input_adapter(i)).parse(false, j);