From 48545f5b180c633b94fe15f629be9fd3a633e065 Mon Sep 17 00:00:00 2001 From: Niels Date: Mon, 22 Jun 2015 23:21:49 +0200 Subject: [PATCH] more documentation --- .../basic_json__CompatibleNumberFloatType.cpp | 21 ++ ...sic_json__CompatibleNumberFloatType.output | 3 + .../basic_json__CompatibleStringType.cpp | 15 ++ .../basic_json__CompatibleStringType.output | 1 + doc/examples/basic_json__InputIt_InputIt.cpp | 21 ++ .../basic_json__InputIt_InputIt.output | 3 + doc/examples/basic_json__boolean_t.cpp | 14 ++ doc/examples/basic_json__boolean_t.output | 2 + doc/examples/basic_json__const_int.cpp | 15 ++ doc/examples/basic_json__const_int.output | 1 + doc/examples/operator_deserialize.cpp | 23 ++ doc/examples/operator_deserialize.output | 13 ++ src/json.hpp | 216 ++++++++++++++---- src/json.hpp.re2c | 216 ++++++++++++++---- 14 files changed, 486 insertions(+), 78 deletions(-) create mode 100644 doc/examples/basic_json__CompatibleNumberFloatType.cpp create mode 100644 doc/examples/basic_json__CompatibleNumberFloatType.output create mode 100644 doc/examples/basic_json__CompatibleStringType.cpp create mode 100644 doc/examples/basic_json__CompatibleStringType.output create mode 100644 doc/examples/basic_json__InputIt_InputIt.cpp create mode 100644 doc/examples/basic_json__InputIt_InputIt.output create mode 100644 doc/examples/basic_json__boolean_t.cpp create mode 100644 doc/examples/basic_json__boolean_t.output create mode 100644 doc/examples/basic_json__const_int.cpp create mode 100644 doc/examples/basic_json__const_int.output create mode 100644 doc/examples/operator_deserialize.cpp create mode 100644 doc/examples/operator_deserialize.output diff --git a/doc/examples/basic_json__CompatibleNumberFloatType.cpp b/doc/examples/basic_json__CompatibleNumberFloatType.cpp new file mode 100644 index 00000000..73adf78e --- /dev/null +++ b/doc/examples/basic_json__CompatibleNumberFloatType.cpp @@ -0,0 +1,21 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create values of different floating-point types + float f42 = 42.23; + float f_nan = 1.0f / 0.0f; + double f23 = 23.42; + + // create JSON numbers + json j42(f42); + json j_nan(f_nan); + json j23(f23); + + // serialize the JSON numbers + std::cout << j42 << '\n'; + std::cout << j_nan << '\n'; + std::cout << j23 << '\n'; +} diff --git a/doc/examples/basic_json__CompatibleNumberFloatType.output b/doc/examples/basic_json__CompatibleNumberFloatType.output new file mode 100644 index 00000000..64bb796c --- /dev/null +++ b/doc/examples/basic_json__CompatibleNumberFloatType.output @@ -0,0 +1,3 @@ +42.2299995422363 +null +23.42 diff --git a/doc/examples/basic_json__CompatibleStringType.cpp b/doc/examples/basic_json__CompatibleStringType.cpp new file mode 100644 index 00000000..d9dc181a --- /dev/null +++ b/doc/examples/basic_json__CompatibleStringType.cpp @@ -0,0 +1,15 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create a string value + std::string s = "The quick brown fox jumps over the lazy dog."; + + // create a JSON string value + json j = s; + + // serialize the JSON string + std::cout << j << '\n'; +} diff --git a/doc/examples/basic_json__CompatibleStringType.output b/doc/examples/basic_json__CompatibleStringType.output new file mode 100644 index 00000000..1316dd98 --- /dev/null +++ b/doc/examples/basic_json__CompatibleStringType.output @@ -0,0 +1 @@ +"The quick brown fox jumps over the lazy dog." diff --git a/doc/examples/basic_json__InputIt_InputIt.cpp b/doc/examples/basic_json__InputIt_InputIt.cpp new file mode 100644 index 00000000..a1fe0e5a --- /dev/null +++ b/doc/examples/basic_json__InputIt_InputIt.cpp @@ -0,0 +1,21 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create JSON values + json j_array = {"alpha", "bravo", "charly", "delta", "easy"}; + json j_number = 42; + json j_object = {{"one", "eins"}, {"two", "zwei"}}; + + // create copies using iterators + json j_array_range(j_array.begin() + 1, j_array.end() - 2); + json j_number_range(j_number.begin(), j_number.end()); + json j_object_range(j_object.begin(), j_object.find("two")); + + // serialize the values + std::cout << j_array_range << '\n'; + std::cout << j_number_range << '\n'; + std::cout << j_object_range << '\n'; +} diff --git a/doc/examples/basic_json__InputIt_InputIt.output b/doc/examples/basic_json__InputIt_InputIt.output new file mode 100644 index 00000000..36714200 --- /dev/null +++ b/doc/examples/basic_json__InputIt_InputIt.output @@ -0,0 +1,3 @@ +["bravo","charly"] +42 +{"one":"eins"} diff --git a/doc/examples/basic_json__boolean_t.cpp b/doc/examples/basic_json__boolean_t.cpp new file mode 100644 index 00000000..cd6117c8 --- /dev/null +++ b/doc/examples/basic_json__boolean_t.cpp @@ -0,0 +1,14 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create boolean values + json j_truth = true; + json j_falsity = false; + + // serialize the JSON booleans + std::cout << j_truth << '\n'; + std::cout << j_falsity << '\n'; +} diff --git a/doc/examples/basic_json__boolean_t.output b/doc/examples/basic_json__boolean_t.output new file mode 100644 index 00000000..da29283a --- /dev/null +++ b/doc/examples/basic_json__boolean_t.output @@ -0,0 +1,2 @@ +true +false diff --git a/doc/examples/basic_json__const_int.cpp b/doc/examples/basic_json__const_int.cpp new file mode 100644 index 00000000..b0797f57 --- /dev/null +++ b/doc/examples/basic_json__const_int.cpp @@ -0,0 +1,15 @@ +#include + +using namespace nlohmann; + +int main() +{ + // an anonymous enum + enum { t = 17 }; + + // create a JSON number from the enum + json j(t); + + // serialize the JSON numbers + std::cout << j << '\n'; +} diff --git a/doc/examples/basic_json__const_int.output b/doc/examples/basic_json__const_int.output new file mode 100644 index 00000000..98d9bcb7 --- /dev/null +++ b/doc/examples/basic_json__const_int.output @@ -0,0 +1 @@ +17 diff --git a/doc/examples/operator_deserialize.cpp b/doc/examples/operator_deserialize.cpp new file mode 100644 index 00000000..af82c74e --- /dev/null +++ b/doc/examples/operator_deserialize.cpp @@ -0,0 +1,23 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create stream with serialized JSON + std::stringstream ss; + ss << R"({ + "number": 23, + "string": "Hello, world!", + "array": [1, 2, 3, 4, 5], + "boolean": false, + "null": null + })"; + + // create JSON value and read the serialization from the stream + json j; + j << ss; + + // serialize JSON + std::cout << std::setw(2) << j << '\n'; +} diff --git a/doc/examples/operator_deserialize.output b/doc/examples/operator_deserialize.output new file mode 100644 index 00000000..81a203fb --- /dev/null +++ b/doc/examples/operator_deserialize.output @@ -0,0 +1,13 @@ +{ + "array": [ + 1, + 2, + 3, + 4, + 5 + ], + "boolean": false, + "null": null, + "number": 23, + "string": "Hello, world!" +} diff --git a/src/json.hpp b/src/json.hpp index 8cd614c9..d1977e49 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -404,7 +404,7 @@ class basic_json @complexity Constant. - @exception std::bad_alloc if allocation for object, array, or string value + @throw std::bad_alloc if allocation for object, array, or string value fails (thrown by the constructors of @ref json_value) @liveexample{The following code shows the constructor for different @ref @@ -463,7 +463,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for object value fails (thrown by + @throw std::bad_alloc if allocation for object value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with an @ref object_t @@ -489,7 +489,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for object value fails (thrown by + @throw std::bad_alloc if allocation for object value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with several @@ -521,7 +521,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for array value fails (thrown by + @throw std::bad_alloc if allocation for array value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with an @ref array_t @@ -547,7 +547,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for array value fails (thrown by + @throw std::bad_alloc if allocation for array value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with several @@ -584,7 +584,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for string value fails (thrown by + @throw std::bad_alloc if allocation for string value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with an @ref string_t @@ -606,7 +606,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for string value fails (thrown by + @throw std::bad_alloc if allocation for string value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with string literal @@ -619,7 +619,26 @@ class basic_json : basic_json(string_t(value)) {} - /// create a string (implicit) + /*! + @brief create a string (implicit) + + Create a string JSON value with a given content. + + @param[in] value a value for the string + + @tparam CompatibleStringType an string type which is compatible to @ref + string_t + + @complexity Linear in the size of the passed @a value. + + @throw std::bad_alloc if allocation for string value fails (thrown by + the constructor of @ref json_value) + + @liveexample{The following code shows the construction of a string value + from a compatible type.,basic_json__CompatibleStringType} + + @sa basic_json(const string_t&) + */ template ::value, int>::type @@ -628,7 +647,18 @@ class basic_json : basic_json(string_t(value)) {} - /// create a boolean (explicit) + /*! + @brief create a boolean (explicit) + + Creates a JSON boolean type from a given value. + + @param[in] value a boolean value to store + + @complexity Constant. + + @liveexample{The example below demonstrates boolean + values.,basic_json__boolean_t} + */ basic_json(boolean_t value) : m_type(value_t::boolean), m_value(value) {} @@ -649,7 +679,8 @@ class basic_json @complexity Constant. - @todo Add example. + @liveexample{The example below shows the construction of a JSON integer + number value.,basic_json__number_integer_t} @sa basic_json(const int) */ @@ -665,7 +696,7 @@ class basic_json /*! @brief create an integer number from an enum type (explicit) - Create an interger number JSON value with a given content. + Create an integer number JSON value with a given content. @param[in] value an integer to create a JSON number from @@ -678,7 +709,7 @@ class basic_json @complexity Constant. @liveexample{The example below shows the construction of a JSON integer - number value.,basic_json__number_integer_t} + number value from an anonymous enum.,basic_json__const_int} @sa basic_json(const number_integer_t) */ @@ -690,7 +721,7 @@ class basic_json /*! @brief create an integer number (implicit) - Create an inteher numnbr JSON value with a given content. This constructor + Create an integer number JSON value with a given content. This constructor allows any type that can be used to construct values of type @ref number_integer_t. Examples may include the types `int`, `int32_t`, or `short`. @@ -732,7 +763,7 @@ class basic_json In case the parameter @a value is not a number, a JSON null value is created instead. - @complexity Linear. + @complexity Constant. @liveexample{The following example creates several floating-point values.,basic_json__number_float_t} @@ -748,7 +779,33 @@ class basic_json } } - /// create a floating-point number (implicit) + /*! + @brief create an floating-point number (implicit) + + Create an floating-point number JSON value with a given content. This + constructor allows any type that can be used to construct values of type + @ref number_float_t. Examples may include the types `float`. + + @tparam CompatibleNumberFloatType a floating-point type which is compatible + to @ref number_float_t. + + @param[in] value a floating-point to create a JSON number from + + @note RFC 7159 , section 6 + disallows NaN values: + > Numeric values that cannot be represented in the grammar below (such + > as Infinity and NaN) are not permitted. + In case the parameter @a value is not a number, a JSON null value is + created instead. + + @complexity Constant. + + @liveexample{The example below shows the construction of several JSON + floating-point number values from compatible + types.,basic_json__CompatibleNumberFloatType} + + @sa basic_json(const number_float_t) + */ template::value and @@ -974,26 +1031,51 @@ class basic_json alloc.construct(m_value.array, count, value); } - /// construct a JSON container given an iterator range - template ::value or - std::is_same::value + std::is_same::value or + std::is_same::value , int>::type = 0> - basic_json(T first, T last) + basic_json(InputIT first, InputIT last) : m_type(first.m_object->m_type) { // make sure iterator fits the current value - if (first.m_object != last.m_object or - first.m_object->m_type != last.m_object->m_type) + if (first.m_object != last.m_object) { throw std::domain_error("iterators are not compatible"); } - // set the type - m_type = first.m_object->m_type; - - // check if iterator range is complete for non-compound values + // check if iterator range is complete for atomic values switch (m_type) { case value_t::number_integer: @@ -1080,7 +1162,7 @@ class basic_json - The complexity is linear. - As postcondition, it holds: `other == basic_json(other)`. - @exception std::bad_alloc if allocation for object, array, or string fails. + @throw std::bad_alloc if allocation for object, array, or string fails. @liveexample{The following code shows an example for the copy constructor.,basic_json__basic_json} @@ -1844,7 +1926,7 @@ class basic_json @note Calling `front` on an empty container is undefined. - @throw std::out_of_range when called on null value. + @throw std::out_of_range when called on null value @liveexample{The following code shows an example for @ref front.,front} */ @@ -2960,7 +3042,8 @@ class basic_json @complexity Linear. - @liveexample{,operator_serialize} + @liveexample{The example below shows the serialization with different + parameters to `width` to adjust the indentation level.,operator_serialize} */ friend std::ostream& operator<<(std::ostream& o, const basic_json& j) { @@ -2995,27 +3078,82 @@ class basic_json /// @name deserialization /// @{ - /// deserialize from string + /*! + @brief deserialize from string + + @param[in] s string to read a serialized JSON value from + @param[in] cb a parser callback function of type parser_callback_t which is + used to control the deserialization by filtering unwanted values (optional) + + @return result of the deserialization + + @complexity Linear in the length of the input. The parser is a predictive + LL(1) parser. The complexity can be higher if the parser callback function + @a cb has a super-linear complexity. + + @todo Add example. + + @sa parse(std::istream&, parser_callback_t) for a version that reads from + an input stream + */ static basic_json parse(const string_t& s, parser_callback_t cb = nullptr) { return parser(s, cb).parse(); } - /// deserialize from stream + /*! + @brief deserialize from stream + + @param[in,out] i stream to read a serialized JSON value from + @param[in] cb a parser callback function of type parser_callback_t which is + used to control the deserialization by filtering unwanted values (optional) + + @return result of the deserialization + + @complexity Linear in the length of the input. The parser is a predictive + LL(1) parser. The complexity can be higher if the parser callback function + @a cb has a super-linear complexity. + + @todo Add example. + + @sa parse(const string_t&, parser_callback_t) for a version that reads + from a string + */ static basic_json parse(std::istream& i, parser_callback_t cb = nullptr) { return parser(i, cb).parse(); } - /// deserialize from stream - friend std::istream& operator>>(std::istream& i, basic_json& 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 std::invalid_argument in case of parse errors + + @complexity Linear in the length of the input. The parser is a predictive + LL(1) parser. + + @liveexample{The example below shows how a JSON value is constructed by + reading a serialization from a stream.,operator_deserialize} + + @sa parse(std::istream&, parser_callback_t) for a variant with a parser + callback function to filter values while parsing + */ + friend std::istream& operator<<(basic_json& j, std::istream& i) { j = parser(i).parse(); return i; } - /// deserialize from stream - friend std::istream& operator<<(basic_json& j, std::istream& i) + /*! + @brief deserialize from stream + @copydoc operator<<(basic_json&, std::istream&) + */ + friend std::istream& operator>>(std::istream& i, basic_json& j) { j = parser(i).parse(); return i; @@ -4464,8 +4602,8 @@ class basic_json @param[in] codepoint1 the code point (can be high surrogate) @param[in] codepoint2 the code point (can be low surrogate or 0) @return string representation of the code point - @exception std::out_of_range if code point is >0x10ffff - @exception std::invalid_argument if the low surrogate is invalid + @throw std::out_of_range if code point is >0x10ffff + @throw std::invalid_argument if the low surrogate is invalid @see */ @@ -5393,7 +5531,7 @@ basic_json_parser_59: 2. Unescaped characters are copied as is. @return string value of current token without opening and closing quotes - @exception std::out_of_range if to_unicode fails + @throw std::out_of_range if to_unicode fails */ string_t get_string() const { @@ -5513,7 +5651,7 @@ basic_json_parser_59: read past the current token. The latter case needs to be treated by the caller function. - @exception std::range_error if passed value is out of range + @throw std::range_error if passed value is out of range */ long double get_number() const { diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index 8929cc3b..6b5b760c 100644 --- a/src/json.hpp.re2c +++ b/src/json.hpp.re2c @@ -404,7 +404,7 @@ class basic_json @complexity Constant. - @exception std::bad_alloc if allocation for object, array, or string value + @throw std::bad_alloc if allocation for object, array, or string value fails (thrown by the constructors of @ref json_value) @liveexample{The following code shows the constructor for different @ref @@ -463,7 +463,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for object value fails (thrown by + @throw std::bad_alloc if allocation for object value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with an @ref object_t @@ -489,7 +489,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for object value fails (thrown by + @throw std::bad_alloc if allocation for object value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with several @@ -521,7 +521,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for array value fails (thrown by + @throw std::bad_alloc if allocation for array value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with an @ref array_t @@ -547,7 +547,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for array value fails (thrown by + @throw std::bad_alloc if allocation for array value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with several @@ -584,7 +584,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for string value fails (thrown by + @throw std::bad_alloc if allocation for string value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with an @ref string_t @@ -606,7 +606,7 @@ class basic_json @complexity Linear in the size of the passed @a value. - @exception std::bad_alloc if allocation for string value fails (thrown by + @throw std::bad_alloc if allocation for string value fails (thrown by the constructor of @ref json_value) @liveexample{The following code shows the constructor with string literal @@ -619,7 +619,26 @@ class basic_json : basic_json(string_t(value)) {} - /// create a string (implicit) + /*! + @brief create a string (implicit) + + Create a string JSON value with a given content. + + @param[in] value a value for the string + + @tparam CompatibleStringType an string type which is compatible to @ref + string_t + + @complexity Linear in the size of the passed @a value. + + @throw std::bad_alloc if allocation for string value fails (thrown by + the constructor of @ref json_value) + + @liveexample{The following code shows the construction of a string value + from a compatible type.,basic_json__CompatibleStringType} + + @sa basic_json(const string_t&) + */ template ::value, int>::type @@ -628,7 +647,18 @@ class basic_json : basic_json(string_t(value)) {} - /// create a boolean (explicit) + /*! + @brief create a boolean (explicit) + + Creates a JSON boolean type from a given value. + + @param[in] value a boolean value to store + + @complexity Constant. + + @liveexample{The example below demonstrates boolean + values.,basic_json__boolean_t} + */ basic_json(boolean_t value) : m_type(value_t::boolean), m_value(value) {} @@ -649,7 +679,8 @@ class basic_json @complexity Constant. - @todo Add example. + @liveexample{The example below shows the construction of a JSON integer + number value.,basic_json__number_integer_t} @sa basic_json(const int) */ @@ -665,7 +696,7 @@ class basic_json /*! @brief create an integer number from an enum type (explicit) - Create an interger number JSON value with a given content. + Create an integer number JSON value with a given content. @param[in] value an integer to create a JSON number from @@ -678,7 +709,7 @@ class basic_json @complexity Constant. @liveexample{The example below shows the construction of a JSON integer - number value.,basic_json__number_integer_t} + number value from an anonymous enum.,basic_json__const_int} @sa basic_json(const number_integer_t) */ @@ -690,7 +721,7 @@ class basic_json /*! @brief create an integer number (implicit) - Create an inteher numnbr JSON value with a given content. This constructor + Create an integer number JSON value with a given content. This constructor allows any type that can be used to construct values of type @ref number_integer_t. Examples may include the types `int`, `int32_t`, or `short`. @@ -732,7 +763,7 @@ class basic_json In case the parameter @a value is not a number, a JSON null value is created instead. - @complexity Linear. + @complexity Constant. @liveexample{The following example creates several floating-point values.,basic_json__number_float_t} @@ -748,7 +779,33 @@ class basic_json } } - /// create a floating-point number (implicit) + /*! + @brief create an floating-point number (implicit) + + Create an floating-point number JSON value with a given content. This + constructor allows any type that can be used to construct values of type + @ref number_float_t. Examples may include the types `float`. + + @tparam CompatibleNumberFloatType a floating-point type which is compatible + to @ref number_float_t. + + @param[in] value a floating-point to create a JSON number from + + @note RFC 7159 , section 6 + disallows NaN values: + > Numeric values that cannot be represented in the grammar below (such + > as Infinity and NaN) are not permitted. + In case the parameter @a value is not a number, a JSON null value is + created instead. + + @complexity Constant. + + @liveexample{The example below shows the construction of several JSON + floating-point number values from compatible + types.,basic_json__CompatibleNumberFloatType} + + @sa basic_json(const number_float_t) + */ template::value and @@ -974,26 +1031,51 @@ class basic_json alloc.construct(m_value.array, count, value); } - /// construct a JSON container given an iterator range - template ::value or - std::is_same::value + std::is_same::value or + std::is_same::value , int>::type = 0> - basic_json(T first, T last) + basic_json(InputIT first, InputIT last) : m_type(first.m_object->m_type) { // make sure iterator fits the current value - if (first.m_object != last.m_object or - first.m_object->m_type != last.m_object->m_type) + if (first.m_object != last.m_object) { throw std::domain_error("iterators are not compatible"); } - // set the type - m_type = first.m_object->m_type; - - // check if iterator range is complete for non-compound values + // check if iterator range is complete for atomic values switch (m_type) { case value_t::number_integer: @@ -1080,7 +1162,7 @@ class basic_json - The complexity is linear. - As postcondition, it holds: `other == basic_json(other)`. - @exception std::bad_alloc if allocation for object, array, or string fails. + @throw std::bad_alloc if allocation for object, array, or string fails. @liveexample{The following code shows an example for the copy constructor.,basic_json__basic_json} @@ -1844,7 +1926,7 @@ class basic_json @note Calling `front` on an empty container is undefined. - @throw std::out_of_range when called on null value. + @throw std::out_of_range when called on null value @liveexample{The following code shows an example for @ref front.,front} */ @@ -2960,7 +3042,8 @@ class basic_json @complexity Linear. - @liveexample{,operator_serialize} + @liveexample{The example below shows the serialization with different + parameters to `width` to adjust the indentation level.,operator_serialize} */ friend std::ostream& operator<<(std::ostream& o, const basic_json& j) { @@ -2995,27 +3078,82 @@ class basic_json /// @name deserialization /// @{ - /// deserialize from string + /*! + @brief deserialize from string + + @param[in] s string to read a serialized JSON value from + @param[in] cb a parser callback function of type parser_callback_t which is + used to control the deserialization by filtering unwanted values (optional) + + @return result of the deserialization + + @complexity Linear in the length of the input. The parser is a predictive + LL(1) parser. The complexity can be higher if the parser callback function + @a cb has a super-linear complexity. + + @todo Add example. + + @sa parse(std::istream&, parser_callback_t) for a version that reads from + an input stream + */ static basic_json parse(const string_t& s, parser_callback_t cb = nullptr) { return parser(s, cb).parse(); } - /// deserialize from stream + /*! + @brief deserialize from stream + + @param[in,out] i stream to read a serialized JSON value from + @param[in] cb a parser callback function of type parser_callback_t which is + used to control the deserialization by filtering unwanted values (optional) + + @return result of the deserialization + + @complexity Linear in the length of the input. The parser is a predictive + LL(1) parser. The complexity can be higher if the parser callback function + @a cb has a super-linear complexity. + + @todo Add example. + + @sa parse(const string_t&, parser_callback_t) for a version that reads + from a string + */ static basic_json parse(std::istream& i, parser_callback_t cb = nullptr) { return parser(i, cb).parse(); } - /// deserialize from stream - friend std::istream& operator>>(std::istream& i, basic_json& 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 std::invalid_argument in case of parse errors + + @complexity Linear in the length of the input. The parser is a predictive + LL(1) parser. + + @liveexample{The example below shows how a JSON value is constructed by + reading a serialization from a stream.,operator_deserialize} + + @sa parse(std::istream&, parser_callback_t) for a variant with a parser + callback function to filter values while parsing + */ + friend std::istream& operator<<(basic_json& j, std::istream& i) { j = parser(i).parse(); return i; } - /// deserialize from stream - friend std::istream& operator<<(basic_json& j, std::istream& i) + /*! + @brief deserialize from stream + @copydoc operator<<(basic_json&, std::istream&) + */ + friend std::istream& operator>>(std::istream& i, basic_json& j) { j = parser(i).parse(); return i; @@ -4464,8 +4602,8 @@ class basic_json @param[in] codepoint1 the code point (can be high surrogate) @param[in] codepoint2 the code point (can be low surrogate or 0) @return string representation of the code point - @exception std::out_of_range if code point is >0x10ffff - @exception std::invalid_argument if the low surrogate is invalid + @throw std::out_of_range if code point is >0x10ffff + @throw std::invalid_argument if the low surrogate is invalid @see */ @@ -4699,7 +4837,7 @@ class basic_json 2. Unescaped characters are copied as is. @return string value of current token without opening and closing quotes - @exception std::out_of_range if to_unicode fails + @throw std::out_of_range if to_unicode fails */ string_t get_string() const { @@ -4819,7 +4957,7 @@ class basic_json read past the current token. The latter case needs to be treated by the caller function. - @exception std::range_error if passed value is out of range + @throw std::range_error if passed value is out of range */ long double get_number() const {