From 61cc07ff384e92c09cbe288c8c1861d355658d35 Mon Sep 17 00:00:00 2001
From: Niels Lohmann <mail@nlohmann.me>
Date: Fri, 27 Oct 2017 16:07:04 +0200
Subject: [PATCH] :memo: some documentation
---
doc/Doxyfile | 2 +-
doc/faq.md | 87 ++++++++++++++++++++++++++++++++++++++++++++++++++++
src/json.hpp | 17 +++++-----
3 files changed, 96 insertions(+), 10 deletions(-)
create mode 100644 doc/faq.md
diff --git a/doc/Doxyfile b/doc/Doxyfile
index 757a0103..bb38b979 100644
--- a/doc/Doxyfile
+++ b/doc/Doxyfile
@@ -107,7 +107,7 @@ WARN_LOGFILE =
# Configuration options related to the input files
#---------------------------------------------------------------------------
INPUT = ../src/json.hpp \
- index.md
+ index.md faq.md
INPUT_ENCODING = UTF-8
FILE_PATTERNS =
RECURSIVE = NO
diff --git a/doc/faq.md b/doc/faq.md
new file mode 100644
index 00000000..14125ee3
--- /dev/null
+++ b/doc/faq.md
@@ -0,0 +1,87 @@
+# FAQ
+
+## Parsing
+
+### How can I parse from a string?
+
+```cpp
+json j = json::parse("[1,2,3,4]");
+```
+
+You can pass string literals (as above), `std::string`, `const char*` or byte containers such as `std::vector<uint8_t>`.
+
+### How can I parse from a file?
+
+```cpp
+std::ifstream i("your_file.json");
+json j = json::parse(i);
+```
+
+## Serialization
+
+### How can I serialize a JSON value
+
+```cpp
+std::cout << j << std::endl;
+```
+
+This is equivalent to
+
+```cpp
+std::string s = j.dump();
+std::cout << s << std::endl;
+```
+
+### How can I pretty-print a JSON value
+
+```cpp
+std::cout << std::setw(4) << j << std::endl;
+```
+
+This is equivalent to
+
+```cpp
+std::string s = j.dump(4);
+std::cout << s << std::endl;
+```
+
+The number `4` denotes the number of spaces used for indentation.
+
+## Iterating
+
+### How can I iterate over a JSON value?
+
+```cpp
+for (json& val : j)
+{
+ // val is a reference for the current value
+}
+```
+
+This works with any JSON value, also primitive values like numbers.
+
+### How can I access the keys when iterating over a JSON object?
+
+```cpp
+for (auto it = j.begin(); it != j.end(); ++it)
+{
+ // the value
+ json &val = it.value();
+
+ // the key (for objects)
+ const std::string &key = it.key();
+}
+```
+
+You can also use an iteration wrapper and use range for:
+
+```cpp
+for (auto it : json::iteration_wrapper(j))
+{
+ // the value
+ json &val = it.value();
+
+ // the key (for objects)
+ const std::string &key = it.key();
+}
+```
diff --git a/src/json.hpp b/src/json.hpp
index d23d85b3..ccd43014 100644
--- a/src/json.hpp
+++ b/src/json.hpp
@@ -8160,13 +8160,11 @@ class basic_json
@brief per-element parser callback type
With a parser callback function, the result of parsing a JSON text can be
- influenced. When passed to @ref parse(std::istream&, const
- parser_callback_t) or @ref parse(const CharT, const parser_callback_t),
- it is called on certain events (passed as @ref parse_event_t via parameter
- @a event) with a set recursion depth @a depth and context JSON value
- @a parsed. The return value of the callback function is a boolean
- indicating whether the element that emitted the callback shall be kept or
- not.
+ influenced. When passed to @ref parse, it is called on certain events
+ (passed as @ref parse_event_t via parameter @a event) with a set recursion
+ depth @a depth and context JSON value @a parsed. The return value of the
+ callback function is a boolean indicating whether the element that emitted
+ the callback shall be kept or not.
We distinguish six scenarios (determined by the event type) in which the
callback function can be called. The following table describes the values
@@ -8203,8 +8201,7 @@ class basic_json
should be kept (`true`) or not (`false`). In the latter case, it is either
skipped completely or replaced by an empty discarded object.
- @sa @ref parse(std::istream&, parser_callback_t) or
- @ref parse(const CharT, const parser_callback_t) for examples
+ @sa @ref parse for examples
@since version 1.0.0
*/
@@ -12948,6 +12945,8 @@ class basic_json
@param[in] cb a parser callback function of type @ref parser_callback_t
which is used to control the deserialization by filtering unwanted values
(optional)
+ @param[in] allow_exceptions whether to throw exceptions in case of a
+ parse error (optional, true by default)
@return result of the deserialization