diff --git a/doc/mkdocs/docs/api/basic_json/index.md b/doc/mkdocs/docs/api/basic_json/index.md index 6dedba231..da332f13c 100644 --- a/doc/mkdocs/docs/api/basic_json/index.md +++ b/doc/mkdocs/docs/api/basic_json/index.md @@ -239,7 +239,6 @@ Access to the JSON value ### Serialization / Dumping - [**dump**](dump.md) - serialization -- to_string - user-defined to_string function for JSON values ### Deserialization / Parsing @@ -281,6 +280,7 @@ Access to the JSON value - [**operator<<(std::ostream&)**](operator_ltlt.md) - serialize to stream - [**operator>>(std::istream&)**](operator_gtgt.md) - deserialize from stream +- [**to_string**](to_string.md) - user-defined `to_string` function for JSON values ## Literals diff --git a/doc/mkdocs/docs/api/basic_json/to_string.md b/doc/mkdocs/docs/api/basic_json/to_string.md new file mode 100644 index 000000000..9678ad32b --- /dev/null +++ b/doc/mkdocs/docs/api/basic_json/to_string.md @@ -0,0 +1,48 @@ +# to_string(basic_json) + +```cpp +template +std::string to_string(const BasicJsonType& j) +``` + +This function implements a user-defined to_string for JSON objects. + +## Template parameters + +`BasicJsonType` +: a specialization of [`basic_json`](index.md) + +## Return value + +string containing the serialization of the 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. + +## Possible implementation + +```cpp +template +std::string to_string(const BasicJsonType& j) +{ + return j.dump(); +} +``` + +## See also + +- [dump](dump.md) + +## Version history + +Added in version 3.7.0. diff --git a/doc/mkdocs/docs/features/macros.md b/doc/mkdocs/docs/features/macros.md index 512caea4e..29d3b6b74 100644 --- a/doc/mkdocs/docs/features/macros.md +++ b/doc/mkdocs/docs/features/macros.md @@ -8,43 +8,59 @@ The default value is `#!cpp assert(x)`. ## `JSON_CATCH_USER(exception)` -This macro overrides `#!cpp catch` calls inside the library. The argument is the type of the exception to catch. As of version 3.8.0, the library only catches `std::out_of_range` exceptions internally to rethrow them as [`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The macro is always followed by a scope. +This macro overrides `#!cpp catch` calls inside the library. The argument is the type of the exception to catch. As of +version 3.8.0, the library only catches `std::out_of_range` exceptions internally to rethrow them as +[`json::out_of_range`](../home/exceptions.md#out-of-range) exceptions. The macro is always followed by a scope. See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. ## `JSON_DIAGNOSTICS` -This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable (default). +This macro enables extended diagnostics for exception messages. Possible values are `1` to enable or `0` to disable +(default). -When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. Note that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead. +When enabled, exception messages contain a [JSON Pointer](json_pointer.md) to the JSON value that triggered the +exception, see [Extended diagnostic messages](../home/exceptions.md#extended-diagnostic-messages) for an example. Note +that enabling this macro increases the size of every JSON value by one pointer and adds some runtime overhead. -The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets `JSON_DIAGNOSTICS` accordingly. +The diagnostics messages can also be controlled with the CMake option `JSON_Diagnostics` (`OFF` by default) which sets +`JSON_DIAGNOSTICS` accordingly. ## `JSON_HAS_CPP_11`, `JSON_HAS_CPP_14`, `JSON_HAS_CPP_17`, `JSON_HAS_CPP_20` -The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view` support for C++17). For these new features, the library implements some preprocessor checks to determine the C++ standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be detected incorrectly. +The library targets C++11, but also supports some features introduced in later C++ versions (e.g., `std::string_view` +support for C++17). For these new features, the library implements some preprocessor checks to determine the C++ +standard. By defining any of these symbols, the internal check is overridden and the provided C++ version is +unconditionally assumed. This can be helpful for compilers that only implement parts of the standard and would be +detected incorrectly. ## `JSON_NOEXCEPTION` -Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. -When defining `JSON_NOEXCEPTION`, `#!cpp try` is replaced by `#!cpp if (true)`, -`#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by `#!cpp std::abort()`. +Exceptions can be switched off by defining the symbol `JSON_NOEXCEPTION`. When defining `JSON_NOEXCEPTION`, `#!cpp try` +is replaced by `#!cpp if (true)`, `#!cpp catch` is replaced by `#!cpp if (false)`, and `#!cpp throw` is replaced by +`#!cpp std::abort()`. The same effect is achieved by setting the compiler flag `-fno-exceptions`. -Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824). +Note the explanatory [`what()`](https://en.cppreference.com/w/cpp/error/exception/what) string of exceptions is not +available for MSVC if exceptions are disabled, see [#2824](https://github.com/nlohmann/json/discussions/2824). ## `JSON_NO_IO` -When defined, headers ``, ``, ``, ``, and `` are not included and parse functions relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for security reasons (e.g., Intel Software Guard Extensions (SGX)). +When defined, headers ``, ``, ``, ``, and `` are not included and parse functions +relying on these headers are excluded. This is relevant for environment where these I/O functions are disallowed for +security reasons (e.g., Intel Software Guard Extensions (SGX)). ## `JSON_SKIP_UNSUPPORTED_COMPILER_CHECK` -When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used. +When defined, the library will not create a compile error when a known unsupported compiler is detected. This allows to +use the library with compilers that do not fully support C++11 and may only work if unsupported features are not used. ## `JSON_THROW_USER(exception)` -This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that `JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield undefined behavior. +This macro overrides `#!cpp throw` calls inside the library. The argument is the exception to be thrown. Note that +`JSON_THROW_USER` should leave the current scope (e.g., by throwing or aborting), as continuing after it may yield +undefined behavior. See [Switch off exceptions](../home/exceptions.md#switch-off-exceptions) for an example. @@ -67,33 +83,45 @@ When defined to `0`, implicit conversions are switched off. By default, implicit std::string s = j; ``` - When `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`, the code above does no longer compile. Instead, it must be written like this: + When `JSON_USE_IMPLICIT_CONVERSIONS` is defined to `0`, the code above does no longer compile. Instead, it must be + written like this: ```cpp json j = "Hello, world!"; auto s = j.get(); ``` -Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly. +Implicit conversions can also be controlled with the CMake option `JSON_ImplicitConversions` (`ON` by default) which +sets `JSON_USE_IMPLICIT_CONVERSIONS` accordingly. ## `NLOHMANN_DEFINE_TYPE_INTRUSIVE(type, member...)` -This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object. +This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as +serialization and (2) want to use the member variable names as object keys in that object. -The macro is to be defined inside the class/struct to create code for. Unlike [`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](#nlohmann_define_type_non_intrusivetype-member), it can access private members. +The macro is to be defined inside the class/struct to create code for. Unlike +[`NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE`](#nlohmann_define_type_non_intrusivetype-member), it can access private members. The first parameter is the name of the class/struct, and all remaining parameters name the members. See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example. ## `NLOHMANN_DEFINE_TYPE_NON_INTRUSIVE(type, member...)` -This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as serialization and (2) want to use the member variable names as object keys in that object. +This macro can be used to simplify the serialization/deserialization of types if (1) want to use a JSON object as +serialization and (2) want to use the member variable names as object keys in that object. -The macro is to be defined inside the namespace of the class/struct to create code for. Private members cannot be accessed. Use [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](#nlohmann_define_type_intrusivetype-member) in these scenarios. -The first parameter is the name of the class/struct, and all remaining parameters name the members. +The macro is to be defined inside the namespace of the class/struct to create code for. Private members cannot be +accessed. Use [`NLOHMANN_DEFINE_TYPE_INTRUSIVE`](#nlohmann_define_type_intrusivetype-member) in these scenarios. The +first parameter is the name of the class/struct, and all remaining parameters name the members. See [Simplify your life with macros](arbitrary_types.md#simplify-your-life-with-macros) for an example. ## `NLOHMANN_JSON_SERIALIZE_ENUM(type, ...)` -This macro simplifies the serialization/deserialization of enum types. See [Specializing enum conversion](enum_conversion.md) for more information. +This macro simplifies the serialization/deserialization of enum types. See +[Specializing enum conversion](enum_conversion.md) for more information. + +## `NLOHMANN_JSON_VERSION_MAJOR`, `NLOHMANN_JSON_VERSION_MINOR`, `NLOHMANN_JSON_VERSION_PATCH` + +These macros are defined by the library and contain the version numbers according to +[Semantic Versioning 2.0.0](https://semver.org). diff --git a/doc/mkdocs/docs/features/parsing/sax_interface.md b/doc/mkdocs/docs/features/parsing/sax_interface.md index 9510be6da..0796a55f5 100644 --- a/doc/mkdocs/docs/features/parsing/sax_interface.md +++ b/doc/mkdocs/docs/features/parsing/sax_interface.md @@ -69,5 +69,5 @@ Note the `sax_parse` function only returns a `#!cpp bool` indicating the result ## See also -- [json_say](../../api/json_sax/index.md) - documentation of the SAX interface +- [json_sax](../../api/json_sax/index.md) - documentation of the SAX interface - [sax_parse](../../api/basic_json/sax_parse.md) - SAX parser diff --git a/doc/mkdocs/mkdocs.yml b/doc/mkdocs/mkdocs.yml index 53def30a4..d67ee200a 100644 --- a/doc/mkdocs/mkdocs.yml +++ b/doc/mkdocs/mkdocs.yml @@ -173,6 +173,7 @@ nav: - api/basic_json/to_bson.md - api/basic_json/to_cbor.md - api/basic_json/to_msgpack.md + - api/basic_json/to_string.md - api/basic_json/to_ubjson.md - api/basic_json/type.md - api/basic_json/type_error.md diff --git a/include/nlohmann/json.hpp b/include/nlohmann/json.hpp index 187cfe6ad..9cb0d8dd3 100644 --- a/include/nlohmann/json.hpp +++ b/include/nlohmann/json.hpp @@ -6,7 +6,7 @@ Licensed under the MIT License . SPDX-License-Identifier: MIT -Copyright (c) 2013-2019 Niels Lohmann . +Copyright (c) 2013-2021 Niels Lohmann . Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -4687,20 +4687,14 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec /// @} }; -/*! -@brief user-defined to_string function for JSON values - -This function implements a user-defined to_string for JSON objects. - -@param[in] j a JSON object -@return a std::string object -*/ - +/// @brief user-defined to_string function for JSON values +/// @sa https://json.nlohmann.me/api/basic_json/to_string/ NLOHMANN_BASIC_JSON_TPL_DECLARATION std::string to_string(const NLOHMANN_BASIC_JSON_TPL& j) { return j.dump(); } + } // namespace nlohmann /////////////////////// diff --git a/single_include/nlohmann/json.hpp b/single_include/nlohmann/json.hpp index 93289308c..a9bb8d478 100644 --- a/single_include/nlohmann/json.hpp +++ b/single_include/nlohmann/json.hpp @@ -6,7 +6,7 @@ Licensed under the MIT License . SPDX-License-Identifier: MIT -Copyright (c) 2013-2019 Niels Lohmann . +Copyright (c) 2013-2021 Niels Lohmann . Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal @@ -22162,20 +22162,14 @@ class basic_json // NOLINT(cppcoreguidelines-special-member-functions,hicpp-spec /// @} }; -/*! -@brief user-defined to_string function for JSON values - -This function implements a user-defined to_string for JSON objects. - -@param[in] j a JSON object -@return a std::string object -*/ - +/// @brief user-defined to_string function for JSON values +/// @sa https://json.nlohmann.me/api/basic_json/to_string/ NLOHMANN_BASIC_JSON_TPL_DECLARATION std::string to_string(const NLOHMANN_BASIC_JSON_TPL& j) { return j.dump(); } + } // namespace nlohmann ///////////////////////