Document dump() of json_view

- API pages for dump, number_format, and operator<< of basic_json_view,
  linked both ways with the basic_json pages
- the feature page describes document order and number_format::source
- the examples show when the view helps: forwarding part of a message
  and writing numbers exactly as they were read

Signed-off-by: Niels Lohmann <mail@nlohmann.me>

docs/mkdocs/docs/examples/basic_json_view__dump.cpp

@@ -0,0 +1,25 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+using json_view = nlohmann::json_view;
+
+int main()
+{
+    // a large batch of sensor readings -- forward just the one that changed,
+    // without ever building a basic_json value for the batch or for the
+    // readings that are not needed
+    const json_document batch = json_document::parse(R"(
+      [{"id": 1, "temp": 21.5}, {"id": 2, "temp": 87.3}, {"id": 3, "temp": 21.7}]
+    )");
+    const json_view readings = batch.root();
+    std::cout << readings[1].dump() << '\n';
+
+    // a configuration file -- dump() on the view keeps the member order of
+    // the source text; a json value's object_t is std::map, so
+    // materialize().dump() of the very same view sorts the keys instead
+    const json_document config = json_document::parse(
+        R"({"name": "cache", "host": "db1", "port": 6379, "timeout": 30})");
+    std::cout << config.root().dump(2) << "\n\n";
+    std::cout << config.root().materialize().dump(2) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_view__dump.output

@@ -0,0 +1,14 @@
+{"id":2,"temp":87.3}
+{
+  "name": "cache",
+  "host": "db1",
+  "port": 6379,
+  "timeout": 30
+}
+
+{
+  "host": "db1",
+  "name": "cache",
+  "port": 6379,
+  "timeout": 30
+}

docs/mkdocs/docs/examples/basic_json_view__number_format.cpp

@@ -0,0 +1,28 @@
+#include <iostream>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+using json_view = nlohmann::json_view;
+
+int main()
+{
+    // a price list received from a supplier feed -- prices and account
+    // numbers must be forwarded exactly, e.g. into an invoice
+    const json_document doc = json_document::parse(R"(
+      [{"sku": "A1", "price": 19.90, "account_id": 12345678901234567890123456},
+       {"sku": "A2", "price": 1E2, "account_id": 98765432109876543210987654}]
+    )");
+    const json_view list = doc.root();
+
+    // number_format::shortest (the default) writes numbers the way
+    // basic_json::dump() would: "19.90" becomes "19.9", "1E2" becomes
+    // "100.0", and each account number -- far beyond any 64-bit integer --
+    // is rounded to the nearest double, exactly as materialize().dump()
+    // (or a plain nlohmann::json) would round it
+    std::cout << list.dump() << '\n';
+
+    // number_format::source copies every number exactly as it was written
+    // in the source text instead -- something basic_json cannot do at all,
+    // since parsing already reduces every number to its parsed value
+    std::cout << list.dump(-1, ' ', false, json_view::number_format::source) << '\n';
+}

docs/mkdocs/docs/examples/basic_json_view__number_format.output

@@ -0,0 +1,2 @@
+[{"sku":"A1","price":19.9,"account_id":1.2345678901234568e+25},{"sku":"A2","price":100.0,"account_id":9.876543210987655e+25}]
+[{"sku":"A1","price":19.90,"account_id":12345678901234567890123456},{"sku":"A2","price":1E2,"account_id":98765432109876543210987654}]

docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.cpp

@@ -0,0 +1,26 @@
+#include <iostream>
+#include <iomanip>
+#include <nlohmann/json_view.hpp>
+
+using json_document = nlohmann::json_document;
+using json_view = nlohmann::json_view;
+
+int main()
+{
+    // one order out of a large incoming batch -- write it straight to a log
+    // stream without ever building a basic_json value for it, or for the
+    // rest of the batch
+    const json_document doc = json_document::parse(R"(
+      [{"id": 1, "item": "cable"}, {"id": 2, "item": "adapter"}]
+    )");
+    const json_view orders = doc.root();
+
+    // compact, for a one-line log entry
+    std::cout << orders[1] << '\n';
+
+    // std::setw sets the indentation level, exactly as for basic_json
+    std::cout << std::setw(2) << orders[1] << "\n\n";
+
+    // std::setfill changes the indentation character
+    std::cout << std::setw(1) << std::setfill('\t') << orders[1] << '\n';
+}

docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.output

@@ -0,0 +1,10 @@
+{"id":2,"item":"adapter"}
+{
+  "id": 2,
+  "item": "adapter"
+}
+
+{
+	"id": 2,
+	"item": "adapter"
+}