From d08e013dd01cc00e2d3e5097ca603310ff4722d0 Mon Sep 17 00:00:00 2001 From: Niels Date: Mon, 25 Jul 2016 16:06:13 +0200 Subject: [PATCH] improved documentation --- doc/examples/basic_json__value_ptr.cpp | 29 ++++++++++++++++++++ doc/examples/basic_json__value_ptr.link | 1 + doc/examples/basic_json__value_ptr.output | 1 + src/json.hpp | 32 ++++++++++++++++++++++- src/json.hpp.re2c | 32 ++++++++++++++++++++++- 5 files changed, 93 insertions(+), 2 deletions(-) create mode 100644 doc/examples/basic_json__value_ptr.cpp create mode 100644 doc/examples/basic_json__value_ptr.link create mode 100644 doc/examples/basic_json__value_ptr.output diff --git a/doc/examples/basic_json__value_ptr.cpp b/doc/examples/basic_json__value_ptr.cpp new file mode 100644 index 00000000..f45fb8b0 --- /dev/null +++ b/doc/examples/basic_json__value_ptr.cpp @@ -0,0 +1,29 @@ +#include + +using json = nlohmann::json; + +int main() +{ + // create a JSON object with different entry types + json j = + { + {"integer", 1}, + {"floating", 42.23}, + {"string", "hello world"}, + {"boolean", true}, + {"object", {{"key1", 1}, {"key2", 2}}}, + {"array", {1, 2, 3}} + }; + + // access existing values + int v_integer = j.value("/integer"_json_pointer, 0); + double v_floating = j.value("/floating"_json_pointer, 47.11); + + // access nonexisting values and rely on default value + std::string v_string = j.value("/nonexisting"_json_pointer, "oops"); + bool v_boolean = j.value("/nonexisting"_json_pointer, false); + + // output values + std::cout << std::boolalpha << v_integer << " " << v_floating + << " " << v_string << " " << v_boolean << "\n"; +} diff --git a/doc/examples/basic_json__value_ptr.link b/doc/examples/basic_json__value_ptr.link new file mode 100644 index 00000000..2f8fc83c --- /dev/null +++ b/doc/examples/basic_json__value_ptr.link @@ -0,0 +1 @@ +online \ No newline at end of file diff --git a/doc/examples/basic_json__value_ptr.output b/doc/examples/basic_json__value_ptr.output new file mode 100644 index 00000000..dfc40e58 --- /dev/null +++ b/doc/examples/basic_json__value_ptr.output @@ -0,0 +1 @@ +1 42.23 oops false diff --git a/src/json.hpp b/src/json.hpp index a5bc864e..fc99374b 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -974,7 +974,9 @@ class basic_json @since version 1.0.0 */ - using parser_callback_t = std::function; + using parser_callback_t = std::function; ////////////////// @@ -3716,6 +3718,21 @@ class basic_json /*! @brief access specified object element via JSON Pointer with default value + Returns either a copy of an object's element at the specified key @a key + or a given default value if no element with key @a key exists. + + The function is basically equivalent to executing + @code {.cpp} + try { + return at(ptr); + } catch(std::out_of_range) { + return default_value; + } + @endcode + + @note Unlike @ref at(const json_pointer&), this function does not throw + if the given key @a key was not found. + @param[in] ptr a JSON pointer to the element to access @param[in] default_value the value to return if @a ptr found no value @@ -3724,6 +3741,19 @@ class basic_json JSON arrays. Note the type of the expected value at @a key and the default value @a default_value must be compatible. + @return copy of the element at key @a key or @a default_value if @a key + is not found + + @throw std::domain_error if JSON is not an object; example: `"cannot use + value() with null"` + + @complexity Logarithmic in the size of the container. + + @liveexample{The example below shows how object elements can be queried + with a default value.,basic_json__value_ptr} + + @sa @ref operator[](const json_ptr&) for unchecked access by reference + @since version 2.0.2 */ template ; + using parser_callback_t = std::function; ////////////////// @@ -3716,6 +3718,21 @@ class basic_json /*! @brief access specified object element via JSON Pointer with default value + Returns either a copy of an object's element at the specified key @a key + or a given default value if no element with key @a key exists. + + The function is basically equivalent to executing + @code {.cpp} + try { + return at(ptr); + } catch(std::out_of_range) { + return default_value; + } + @endcode + + @note Unlike @ref at(const json_pointer&), this function does not throw + if the given key @a key was not found. + @param[in] ptr a JSON pointer to the element to access @param[in] default_value the value to return if @a ptr found no value @@ -3724,6 +3741,19 @@ class basic_json JSON arrays. Note the type of the expected value at @a key and the default value @a default_value must be compatible. + @return copy of the element at key @a key or @a default_value if @a key + is not found + + @throw std::domain_error if JSON is not an object; example: `"cannot use + value() with null"` + + @complexity Logarithmic in the size of the container. + + @liveexample{The example below shows how object elements can be queried + with a default value.,basic_json__value_ptr} + + @sa @ref operator[](const json_ptr&) for unchecked access by reference + @since version 2.0.2 */ template