From 4bb5126502b20200011c4c20ef2cc0c8c2b30fc3 Mon Sep 17 00:00:00 2001 From: Niels Date: Sun, 21 Jun 2015 18:30:08 +0200 Subject: [PATCH] more documentation --- Makefile | 1 + docs/examples/basic_json__copyassignment.cpp | 17 +++++ .../basic_json__copyassignment.output | 2 + docs/examples/basic_json__moveconstructor.cpp | 16 +++++ .../basic_json__moveconstructor.output | 2 + docs/examples/dump.cpp | 20 ++++++ docs/examples/dump.output | 34 ++++++++++ src/json.hpp | 63 ++++++++++++++----- src/json.hpp.re2c | 63 ++++++++++++++----- 9 files changed, 186 insertions(+), 32 deletions(-) create mode 100644 docs/examples/basic_json__copyassignment.cpp create mode 100644 docs/examples/basic_json__copyassignment.output create mode 100644 docs/examples/basic_json__moveconstructor.cpp create mode 100644 docs/examples/basic_json__moveconstructor.output create mode 100644 docs/examples/dump.cpp create mode 100644 docs/examples/dump.output diff --git a/Makefile b/Makefile index 8d1fa0ab..39ffee92 100644 --- a/Makefile +++ b/Makefile @@ -50,6 +50,7 @@ update_doxygen_online: rm -fr html mv /tmp/github-html html -cd html ; git rm $(shell git ls-files --deleted) + git add html git commit -m "Doxygen update" git checkout master diff --git a/docs/examples/basic_json__copyassignment.cpp b/docs/examples/basic_json__copyassignment.cpp new file mode 100644 index 00000000..977bd79d --- /dev/null +++ b/docs/examples/basic_json__copyassignment.cpp @@ -0,0 +1,17 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create JSON values + json a = 23; + json b = 42; + + // copy-assign a to b + b = a; + + // serialize the JSON arrays + std::cout << a << '\n'; + std::cout << b << '\n'; +} diff --git a/docs/examples/basic_json__copyassignment.output b/docs/examples/basic_json__copyassignment.output new file mode 100644 index 00000000..c1eee210 --- /dev/null +++ b/docs/examples/basic_json__copyassignment.output @@ -0,0 +1,2 @@ +23 +23 diff --git a/docs/examples/basic_json__moveconstructor.cpp b/docs/examples/basic_json__moveconstructor.cpp new file mode 100644 index 00000000..f73f8a5a --- /dev/null +++ b/docs/examples/basic_json__moveconstructor.cpp @@ -0,0 +1,16 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create a JSON value + json a = 23; + + // move contents of a to b + json b(std::move(a)); + + // serialize the JSON arrays + std::cout << a << '\n'; + std::cout << b << '\n'; +} diff --git a/docs/examples/basic_json__moveconstructor.output b/docs/examples/basic_json__moveconstructor.output new file mode 100644 index 00000000..911b5b1a --- /dev/null +++ b/docs/examples/basic_json__moveconstructor.output @@ -0,0 +1,2 @@ +null +23 diff --git a/docs/examples/dump.cpp b/docs/examples/dump.cpp new file mode 100644 index 00000000..962e4008 --- /dev/null +++ b/docs/examples/dump.cpp @@ -0,0 +1,20 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create JSON values + json j_object = {{"one", 1}, {"two", 2}}; + json j_array = {1, 2, 4, 8, 16}; + + // call dump() + std::cout << j_object.dump() << "\n\n"; + std::cout << j_object.dump(-1) << "\n\n"; + std::cout << j_object.dump(0) << "\n\n"; + std::cout << j_object.dump(4) << "\n\n"; + std::cout << j_array.dump() << "\n\n"; + std::cout << j_array.dump(-1) << "\n\n"; + std::cout << j_array.dump(0) << "\n\n"; + std::cout << j_array.dump(4) << "\n\n"; +} diff --git a/docs/examples/dump.output b/docs/examples/dump.output new file mode 100644 index 00000000..9b462eab --- /dev/null +++ b/docs/examples/dump.output @@ -0,0 +1,34 @@ +{"one":1,"two":2} + +{"one":1,"two":2} + +{ +"one": 1, +"two": 2 +} + +{ + "one": 1, + "two": 2 +} + +[1,2,4,8,16] + +[1,2,4,8,16] + +[ +1, +2, +4, +8, +16 +] + +[ + 1, + 2, + 4, + 8, + 16 +] + diff --git a/src/json.hpp b/src/json.hpp index 895fdafb..a71ae28d 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -85,16 +85,16 @@ struct has_mapped_type (@c std::allocator by default) @requirement This class satisfies the Container requirements (see http://en.cppreference.com/w/cpp/concept/Container): -- @ref basic_json() -- @ref basic_json(const basic_json&) -- @ref reference& operator=(basic_json) -- @ref ~basic_json() -- @ref iterator begin(), @ref const_iterator begin(), @ref const_iterator cbegin() -- @ref iterator end(), @ref const_iterator end(), @ref const_iterator cend() -- @ref bool operator==(const_reference, const_reference), @ref bool operator!=(const_reference, const_reference) -- @ref void swap(reference other) -- @ref size_type size(), @ref size_type max_size() -- @ref bool empty() +- basic_json() +- basic_json(const basic_json&) +- reference& operator=(basic_json) +- ~basic_json() +- iterator begin(), const_iterator begin(), const_iterator cbegin() +- iterator end(), const_iterator end(), const_iterator cend() +- bool operator==(const_reference, const_reference), bool operator!=(const_reference, const_reference) +- void swap(reference other) +- size_type size(), size_type max_size() +- bool empty() @note ObjectType trick from http://stackoverflow.com/a/9860911 @@ -686,7 +686,8 @@ class basic_json 3. In all other cases, the initializer list could not be interpreted as JSON object type, so interpreting it as JSON array type is safe. - With the rules described above, the following JSON values cannot be expressed by an initializer list: + With the rules described above, the following JSON values cannot be + expressed by an initializer list: - the empty array (`[]`): use @ref array(list_init_t) with an empty initializer list in this case @@ -1037,7 +1038,22 @@ class basic_json } } - /// move constructor + /*! + @brief move constructor + + Move constructor. Constructs a JSON value with the contents of the given + value @a other using move semantics. It "steals" the resources from @a + other and leaves it as JSON null value. + + @param other value to move to this object + + @post @a other is a JSON null value + + @complexity Constant. + + @liveexample{The code below shows the move constructor explicitly called + via std::move.,basic_json__moveconstructor} + */ basic_json(basic_json&& other) noexcept : m_type(std::move(other.m_type)), m_value(std::move(other.m_value)) @@ -1050,14 +1066,22 @@ class basic_json /*! @brief copy assignment - The copy assignment operator is expressed in terms of the copy constructor, - destructor, and the swap() member function. + Copy assignment operator. Copies a JSON value via the "copy and swap" + strategy: It is expressed in terms of the copy constructor, destructor, and + the swap() member function. + + @param other value to copy from @complexity Linear. @requirement This function satisfies the Container requirements: - The complexity is linear. + @liveexample{The code below shows and example for the copy assignment. It + creates a copy of value `a` which is then swapped with `b`. Finally\, the + copy of `a` (which is the null value after the swap) is + destroyed.,basic_json__copyassignment} + @ingroup container */ reference& operator=(basic_json other) noexcept ( @@ -1076,7 +1100,7 @@ class basic_json /*! @brief destructor - Destroys the JSON value and frees all memory. + Destroys the JSON value and frees all allocated memory. @complexity Linear. @@ -1137,7 +1161,7 @@ class basic_json /*! @brief serialization - Serialization function for JSON objects. The function tries to mimick + Serialization function for JSON values. The function tries to mimick Python's @p json.dumps() function, and currently supports its @p indent parameter. @@ -1146,6 +1170,13 @@ class basic_json will only insert newlines. -1 (the default) selects the most compact representation + @return string containing the serialization of the JSON value + + @complexity Linear. + + @liveexample{The following example shows the effect of different @a indent + parameters to the result of the serializaion.,dump} + @see https://docs.python.org/2/library/json.html#json.dump */ string_t dump(const int indent = -1) const noexcept diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index 473c8e4e..6ba79267 100644 --- a/src/json.hpp.re2c +++ b/src/json.hpp.re2c @@ -85,16 +85,16 @@ struct has_mapped_type (@c std::allocator by default) @requirement This class satisfies the Container requirements (see http://en.cppreference.com/w/cpp/concept/Container): -- @ref basic_json() -- @ref basic_json(const basic_json&) -- @ref reference& operator=(basic_json) -- @ref ~basic_json() -- @ref iterator begin(), @ref const_iterator begin(), @ref const_iterator cbegin() -- @ref iterator end(), @ref const_iterator end(), @ref const_iterator cend() -- @ref bool operator==(const_reference, const_reference), @ref bool operator!=(const_reference, const_reference) -- @ref void swap(reference other) -- @ref size_type size(), @ref size_type max_size() -- @ref bool empty() +- basic_json() +- basic_json(const basic_json&) +- reference& operator=(basic_json) +- ~basic_json() +- iterator begin(), const_iterator begin(), const_iterator cbegin() +- iterator end(), const_iterator end(), const_iterator cend() +- bool operator==(const_reference, const_reference), bool operator!=(const_reference, const_reference) +- void swap(reference other) +- size_type size(), size_type max_size() +- bool empty() @note ObjectType trick from http://stackoverflow.com/a/9860911 @@ -686,7 +686,8 @@ class basic_json 3. In all other cases, the initializer list could not be interpreted as JSON object type, so interpreting it as JSON array type is safe. - With the rules described above, the following JSON values cannot be expressed by an initializer list: + With the rules described above, the following JSON values cannot be + expressed by an initializer list: - the empty array (`[]`): use @ref array(list_init_t) with an empty initializer list in this case @@ -1037,7 +1038,22 @@ class basic_json } } - /// move constructor + /*! + @brief move constructor + + Move constructor. Constructs a JSON value with the contents of the given + value @a other using move semantics. It "steals" the resources from @a + other and leaves it as JSON null value. + + @param other value to move to this object + + @post @a other is a JSON null value + + @complexity Constant. + + @liveexample{The code below shows the move constructor explicitly called + via std::move.,basic_json__moveconstructor} + */ basic_json(basic_json&& other) noexcept : m_type(std::move(other.m_type)), m_value(std::move(other.m_value)) @@ -1050,14 +1066,22 @@ class basic_json /*! @brief copy assignment - The copy assignment operator is expressed in terms of the copy constructor, - destructor, and the swap() member function. + Copy assignment operator. Copies a JSON value via the "copy and swap" + strategy: It is expressed in terms of the copy constructor, destructor, and + the swap() member function. + + @param other value to copy from @complexity Linear. @requirement This function satisfies the Container requirements: - The complexity is linear. + @liveexample{The code below shows and example for the copy assignment. It + creates a copy of value `a` which is then swapped with `b`. Finally\, the + copy of `a` (which is the null value after the swap) is + destroyed.,basic_json__copyassignment} + @ingroup container */ reference& operator=(basic_json other) noexcept ( @@ -1076,7 +1100,7 @@ class basic_json /*! @brief destructor - Destroys the JSON value and frees all memory. + Destroys the JSON value and frees all allocated memory. @complexity Linear. @@ -1137,7 +1161,7 @@ class basic_json /*! @brief serialization - Serialization function for JSON objects. The function tries to mimick + Serialization function for JSON values. The function tries to mimick Python's @p json.dumps() function, and currently supports its @p indent parameter. @@ -1146,6 +1170,13 @@ class basic_json will only insert newlines. -1 (the default) selects the most compact representation + @return string containing the serialization of the JSON value + + @complexity Linear. + + @liveexample{The following example shows the effect of different @a indent + parameters to the result of the serializaion.,dump} + @see https://docs.python.org/2/library/json.html#json.dump */ string_t dump(const int indent = -1) const noexcept