:memo: improved documentation for dump and iterator_wrapper
diff --git a/doc/examples/dump.cpp b/doc/examples/dump.cpp
index 4440f91..1c48597 100644
--- a/doc/examples/dump.cpp
+++ b/doc/examples/dump.cpp
@@ -28,4 +28,15 @@
std::cout << "strings:" << '\n'
<< j_string.dump() << '\n'
<< j_string.dump(-1, ' ', true) << '\n';
+
+ // create JSON value with invalid UTF-8 byte sequence
+ json j_invalid = "\xF0\xA4\xAD\xC0";
+ try
+ {
+ std::cout << j_invalid.dump() << std::endl;
+ }
+ catch (json::type_error& e)
+ {
+ std::cout << e.what() << std::endl;
+ }
}
diff --git a/doc/examples/dump.link b/doc/examples/dump.link
index c02a412..4de7034 100644
--- a/doc/examples/dump.link
+++ b/doc/examples/dump.link
@@ -1 +1 @@
-<a target="_blank" href="https://wandbox.org/permlink/UnV6etCOZZRZpYyB"><b>online</b></a>
\ No newline at end of file
+<a target="_blank" href="https://wandbox.org/permlink/mHH9TibITCYPpLwy"><b>online</b></a>
\ No newline at end of file
diff --git a/doc/examples/dump.output b/doc/examples/dump.output
index 8c6998b..c94eeb0 100644
--- a/doc/examples/dump.output
+++ b/doc/examples/dump.output
@@ -50,3 +50,4 @@
strings:
"Hellö 😀!"
"Hell\u00f6 \ud83d\ude00!"
+[json.exception.type_error.316] invalid UTF-8 byte at index 3: 0xC0
diff --git a/src/json.hpp b/src/json.hpp
index 8cc3c4a..31429f8 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -11297,22 +11297,62 @@
reference to the JSON values is returned, so there is no access to the
underlying iterator.
+ For loop without iterator_wrapper:
+
+ @code{cpp}
+ for (auto it = j_object.begin(); it != j_object.end(); ++it)
+ {
+ std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
+ }
+ @endcode
+
+ Range-based for loop without iterator proxy:
+
+ @code{cpp}
+ for (auto it : j_object)
+ {
+ // "it" is of type json::reference and has no key() member
+ std::cout << "value: " << it << '\n';
+ }
+ @endcode
+
+ Range-based for loop with iterator proxy:
+
+ @code{cpp}
+ for (auto it : json::iterator_wrapper(j_object))
+ {
+ std::cout << "key: " << it.key() << ", value:" << it.value() << '\n';
+ }
+ @endcode
+
+ @note When iterating over an array, `key()` will return the index of the
+ element as string (see example).
+
+ @param[in] ref reference to a JSON value
+ @return iteration proxy object wrapping @a ref with an interface to use in
+ range-based for loops
+
@liveexample{The following code shows how the wrapper is used,iterator_wrapper}
+ @exceptionsafety Strong guarantee: if an exception is thrown, there are no
+ changes in the JSON value.
+
+ @complexity Constant.
+
@note The name of this function is not yet final and may change in the
future.
*/
- static iteration_proxy<iterator> iterator_wrapper(reference cont)
+ static iteration_proxy<iterator> iterator_wrapper(reference ref)
{
- return iteration_proxy<iterator>(cont);
+ return iteration_proxy<iterator>(ref);
}
/*!
@copydoc iterator_wrapper(reference)
*/
- static iteration_proxy<const_iterator> iterator_wrapper(const_reference cont)
+ static iteration_proxy<const_iterator> iterator_wrapper(const_reference ref)
{
- return iteration_proxy<const_iterator>(cont);
+ return iteration_proxy<const_iterator>(ref);
}
/// @}
