improved documentation
diff --git a/doc/examples/basic_json__value_ptr.cpp b/doc/examples/basic_json__value_ptr.cpp
new file mode 100644
index 0000000..f45fb8b
--- /dev/null
+++ b/doc/examples/basic_json__value_ptr.cpp
@@ -0,0 +1,29 @@
+#include <json.hpp>
+
+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 0000000..2f8fc83
--- /dev/null
+++ b/doc/examples/basic_json__value_ptr.link
@@ -0,0 +1 @@
+<a target="_blank" href="http://melpon.org/wandbox/permlink/K4L4D6nibuGXbjfd"><b>online</b></a>
\ 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 0000000..dfc40e5
--- /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 a5bc864..fc99374 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -974,7 +974,9 @@
@since version 1.0.0
*/
- using parser_callback_t = std::function<bool(int depth, parse_event_t event, basic_json& parsed)>;
+ using parser_callback_t = std::function<bool(int depth,
+ parse_event_t event,
+ basic_json& parsed)>;
//////////////////
@@ -3716,6 +3718,21 @@
/*!
@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 @@
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 <class ValueType, typename
diff --git a/src/json.hpp.re2c b/src/json.hpp.re2c
index 2f5ecd2..1227f36 100644
--- a/src/json.hpp.re2c
+++ b/src/json.hpp.re2c
@@ -974,7 +974,9 @@
@since version 1.0.0
*/
- using parser_callback_t = std::function<bool(int depth, parse_event_t event, basic_json& parsed)>;
+ using parser_callback_t = std::function<bool(int depth,
+ parse_event_t event,
+ basic_json& parsed)>;
//////////////////
@@ -3716,6 +3718,21 @@
/*!
@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 @@
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 <class ValueType, typename
