diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index bd88cbf1a..5a9506798 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -279,7 +279,7 @@ Access to the JSON value ## Non-member functions -- operator<<(std::ostream&) - serialize to stream +- [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream - operator>>(std::istream&) - deserialize from stream ## Literals diff --git a/doc/mkdocs/docs/api/basic_json/operator_ltlt.md b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md new file mode 100644 index 000000000..deb21563f --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/operator_ltlt.md @@ -0,0 +1,55 @@ +# operator<<(basic_json) + +```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. + +- 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. + +## Parameters + +`o` (in, out) +: stream to serialize to + +`j` (in) +: JSON value to serialize + +## 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. + +## Complexity + +Linear. + +## Example + +??? example + + The example below shows the serialization with different parameters to `width` to adjust the indentation level. + + ```cpp + --8<-- "examples/operator_serialize.cpp" + ``` + + Output: + + ```json + --8<-- "examples/operator_serialize.output" + ``` + +## Version history + +- Added in version 1.0.0 +- Support for indentation character added in version 3.0.0. diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index bae5ad446..520e1e319 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -148,6 +148,7 @@ nav: - api/basic_json/operator_eq.md - api/basic_json/operator_ne.md - api/basic_json/operator_lt.md + - api/basic_json/operator_ltlt.md - api/basic_json/operator_le.md - api/basic_json/operator_gt.md - api/basic_json/operator_ge.md diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index ae0dafbbf..bde30abec 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -3638,37 +3638,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec /// @name serialization /// @{ #ifndef JSON_NO_IO - /*! - @brief serialize to stream - - Serialize the given JSON value @a j to the output stream @a o. The JSON - value will be serialized using the @ref dump member function. - - - The indentation of the output can be controlled with the member variable - `width` of the output stream @a o. For instance, using the manipulator - `std::setw(4)` on @a 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 @a o. For instance, the manipulator - `std::setfill('\\t')` sets indentation to use a tab character rather than - the default space character. - - @param[in,out] o stream to serialize to - @param[in] j JSON value to serialize - - @return the stream @a o - - @throw type_error.316 if a string stored inside the JSON value is not - UTF-8 encoded - - @complexity Linear. - - @liveexample{The example below shows the serialization with different - parameters to `width` to adjust the indentation level.,operator_serialize} - - @since version 1.0.0; indentation character added in version 3.0.0 - */ + /// @brief serialize to stream + /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/ friend std::ostream& operator<<(std::ostream& o, const basic_json& j) { // read width member and use it as indentation parameter if nonzero diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index af4b6522c..aba56bc24 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -21139,37 +21139,8 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec /// @name serialization /// @{ #ifndef JSON_NO_IO - /*! - @brief serialize to stream - - Serialize the given JSON value @a j to the output stream @a o. The JSON - value will be serialized using the @ref dump member function. - - - The indentation of the output can be controlled with the member variable - `width` of the output stream @a o. For instance, using the manipulator - `std::setw(4)` on @a 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 @a o. For instance, the manipulator - `std::setfill('\\t')` sets indentation to use a tab character rather than - the default space character. - - @param[in,out] o stream to serialize to - @param[in] j JSON value to serialize - - @return the stream @a o - - @throw type_error.316 if a string stored inside the JSON value is not - UTF-8 encoded - - @complexity Linear. - - @liveexample{The example below shows the serialization with different - parameters to `width` to adjust the indentation level.,operator_serialize} - - @since version 1.0.0; indentation character added in version 3.0.0 - */ + /// @brief serialize to stream + /// @sa https://json.nlohmann.me/api/basic_json/operator_ltlt/ friend std::ostream& operator<<(std::ostream& o, const basic_json& j) { // read width member and use it as indentation parameter if nonzero