From 48c4f4d05d8ad019846b3e51e6e5d6732296e228 Mon Sep 17 00:00:00 2001 From: Niels Date: Sun, 28 Jun 2015 19:32:09 +0200 Subject: [PATCH] more documentation --- doc/examples/count.cpp | 18 ++++++++++++ doc/examples/count.output | 2 ++ doc/examples/find__key_type.cpp | 19 ++++++++++++ doc/examples/find__key_type.output | 3 ++ src/json.hpp | 38 ++++++++++++++++++++++-- src/json.hpp.re2c | 47 +++++++++++++++++++++++++----- 6 files changed, 117 insertions(+), 10 deletions(-) create mode 100644 doc/examples/count.cpp create mode 100644 doc/examples/count.output create mode 100644 doc/examples/find__key_type.cpp create mode 100644 doc/examples/find__key_type.output diff --git a/doc/examples/count.cpp b/doc/examples/count.cpp new file mode 100644 index 00000000..cf679644 --- /dev/null +++ b/doc/examples/count.cpp @@ -0,0 +1,18 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create a JSON object + json j_object = {{"one", 1}, {"two", 2}}; + + // call find + auto count_two = j_object.count("two"); + auto count_three = j_object.count("three"); + + // print values + std::cout << std::boolalpha; + std::cout << "number of elements with key \"two\": " << count_two << '\n'; + std::cout << "number of elements with key \"three\": " << count_three << '\n'; +} diff --git a/doc/examples/count.output b/doc/examples/count.output new file mode 100644 index 00000000..d816fcb2 --- /dev/null +++ b/doc/examples/count.output @@ -0,0 +1,2 @@ +number of elements with key "two": 1 +number of elements with key "three": 0 diff --git a/doc/examples/find__key_type.cpp b/doc/examples/find__key_type.cpp new file mode 100644 index 00000000..214fe53f --- /dev/null +++ b/doc/examples/find__key_type.cpp @@ -0,0 +1,19 @@ +#include + +using namespace nlohmann; + +int main() +{ + // create a JSON object + json j_object = {{"one", 1}, {"two", 2}}; + + // call find + auto it_two = j_object.find("two"); + auto it_three = j_object.find("three"); + + // print values + std::cout << std::boolalpha; + std::cout << "\"two\" was found: " << (it_two != j_object.end()) << '\n'; + std::cout << "value at key \"two\": " << *it_two << '\n'; + std::cout << "\"three\" was found: " << (it_three != j_object.end()) << '\n'; +} diff --git a/doc/examples/find__key_type.output b/doc/examples/find__key_type.output new file mode 100644 index 00000000..509bb42d --- /dev/null +++ b/doc/examples/find__key_type.output @@ -0,0 +1,3 @@ +"two" was found: true +value at key "two": 2 +"three" was found: false diff --git a/src/json.hpp b/src/json.hpp index 67678d04..8f6f50d4 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -2701,7 +2701,21 @@ class basic_json m_value.array->erase(m_value.array->begin() + static_cast(idx)); } - /// find an element in an object + /*! + @brief find an element in a JSON object + + Finds an element in a JSON object with key equivalent to @a key. If the + element is not found or the JSON value is not an object, end() is returned. + + @param[in] key key value of the element to search for + + @return Iterator to an element with key equivalent to @a key. If no such + element is found, past-the-end (see end()) iterator is returned. + + @complexity Logarithmic in the size of the JSON object. + + @liveexample{The example shows how find is used.,find__key_type} + */ iterator find(typename object_t::key_type key) { auto result = end(); @@ -2714,7 +2728,10 @@ class basic_json return result; } - /// find an element in an object + /*! + @brief find an element in a JSON object + @copydoc find(typename object_t::key_type) + */ const_iterator find(typename object_t::key_type key) const { auto result = cend(); @@ -2727,7 +2744,22 @@ class basic_json return result; } - /// returns the number of occurrences of a key in an object + /*! + @brief returns the number of occurrences of a key in a JSON object + + Returns the number of elements with key @a key. If ObjectType is the + default `std::map` type, the return value will always be `0` (@a key was + not found) or `1` (@a key was found). + + @param[in] key key value of the element to count + + @return Number of elements with key @a key. If the JSON value is not an + object, the return value will be `0`. + + @complexity Logarithmic in the size of the JSON object. + + @liveexample{The example shows how count is used.,count} + */ size_type count(typename object_t::key_type key) const { // return 0 for all nonobject types diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c index 107260ac..c96bc60e 100644 --- a/src/json.hpp.re2c +++ b/src/json.hpp.re2c @@ -2701,7 +2701,21 @@ class basic_json m_value.array->erase(m_value.array->begin() + static_cast(idx)); } - /// find an element in an object + /*! + @brief find an element in a JSON object + + Finds an element in a JSON object with key equivalent to @a key. If the + element is not found or the JSON value is not an object, end() is returned. + + @param[in] key key value of the element to search for + + @return Iterator to an element with key equivalent to @a key. If no such + element is found, past-the-end (see end()) iterator is returned. + + @complexity Logarithmic in the size of the JSON object. + + @liveexample{The example shows how find is used.,find__key_type} + */ iterator find(typename object_t::key_type key) { auto result = end(); @@ -2714,7 +2728,10 @@ class basic_json return result; } - /// find an element in an object + /*! + @brief find an element in a JSON object + @copydoc find(typename object_t::key_type) + */ const_iterator find(typename object_t::key_type key) const { auto result = cend(); @@ -2727,7 +2744,22 @@ class basic_json return result; } - /// returns the number of occurrences of a key in an object + /*! + @brief returns the number of occurrences of a key in a JSON object + + Returns the number of elements with key @a key. If ObjectType is the + default `std::map` type, the return value will always be `0` (@a key was + not found) or `1` (@a key was found). + + @param[in] key key value of the element to count + + @return Number of elements with key @a key. If the JSON value is not an + object, the return value will be `0`. + + @complexity Logarithmic in the size of the JSON object. + + @liveexample{The example shows how count is used.,count} + */ size_type count(typename object_t::key_type key) const { // return 0 for all nonobject types @@ -5600,15 +5632,16 @@ class basic_json { public: /// constructor for strings - parser(const string_t& s, parser_callback_t cb = nullptr) : callback(cb), m_lexer(s) + parser(const string_t& s, parser_callback_t cb = nullptr) + : callback(cb), m_lexer(s) { // read first token get_token(); } /// a parser reading from an input stream - parser(std::istream& _is, parser_callback_t cb = nullptr) : callback(cb), - m_lexer(&_is) + parser(std::istream& _is, parser_callback_t cb = nullptr) + : callback(cb), m_lexer(&_is) { // read first token get_token(); @@ -5875,7 +5908,7 @@ class basic_json } private: - /// levels of recursion + /// current level of recursion int depth = 0; /// callback function parser_callback_t callback;