From 314e4e7699087b96c6fbdc4d8d3458ef11a2a16c Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Sat, 16 Dec 2017 23:58:10 +0100 Subject: [PATCH] :memo: improved documentation for dump and iterator_wrapper --- doc/examples/dump.cpp | 11 +++++++++ doc/examples/dump.link | 2 +- doc/examples/dump.output | 1 + src/json.hpp | 48 ++++++++++++++++++++++++++++++++++++---- 4 files changed, 57 insertions(+), 5 deletions(-) diff --git a/doc/examples/dump.cpp b/doc/examples/dump.cpp index 4440f91c..1c485972 100644 --- a/doc/examples/dump.cpp +++ b/doc/examples/dump.cpp @@ -28,4 +28,15 @@ int main() 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 c02a4126..4de70343 100644 --- a/doc/examples/dump.link +++ b/doc/examples/dump.link @@ -1 +1 @@ -online \ No newline at end of file +online \ No newline at end of file diff --git a/doc/examples/dump.output b/doc/examples/dump.output index 8c6998bb..c94eeb02 100644 --- a/doc/examples/dump.output +++ b/doc/examples/dump.output @@ -50,3 +50,4 @@ arrays: 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 8cc3c4a5..31429f81 100644 --- a/src/json.hpp +++ b/src/json.hpp @@ -11297,22 +11297,62 @@ class basic_json 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_wrapper(reference cont) + static iteration_proxy iterator_wrapper(reference ref) { - return iteration_proxy(cont); + return iteration_proxy(ref); } /*! @copydoc iterator_wrapper(reference) */ - static iteration_proxy iterator_wrapper(const_reference cont) + static iteration_proxy iterator_wrapper(const_reference ref) { - return iteration_proxy(cont); + return iteration_proxy(ref); } /// @}