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/docset/docSet.sql

@@ -150,6 +150,7 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::cbegin', 'Me
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::cend', 'Method', 'api/basic_json_view/cend/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::contains', 'Method', 'api/basic_json_view/contains/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::count', 'Method', 'api/basic_json_view/count/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::dump', 'Method', 'api/basic_json_view/dump/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::empty', 'Method', 'api/basic_json_view/empty/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::end', 'Method', 'api/basic_json_view/end/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::find', 'Method', 'api/basic_json_view/find/index.html');
@@ -172,8 +173,10 @@ INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::is_string',
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::is_structured', 'Method', 'api/basic_json_view/is_structured/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::items', 'Method', 'api/basic_json_view/items/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::materialize', 'Method', 'api/basic_json_view/materialize/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::number_format', 'Enum', 'api/basic_json_view/number_format/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::number_token', 'Method', 'api/basic_json_view/number_token/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::operator bool', 'Method', 'api/basic_json_view/operator_bool/index.html');
+INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::operator<<', 'Operator', 'api/basic_json_view/operator_ltlt/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::operator[]', 'Operator', 'api/basic_json_view/operator[]/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::size', 'Method', 'api/basic_json_view/size/index.html');
 INSERT INTO searchIndex(name, type, path) VALUES ('basic_json_view::source_offset', 'Method', 'api/basic_json_view/source_offset/index.html');

docs/mkdocs/docs/api/basic_json/dump.md

@@ -86,6 +86,8 @@ Binary values are serialized as an object containing two keys:
 
 - [to_string](to_string.md) returns a string representation of a JSON value
 - [operator<<](../operator_ltlt.md) serialize to stream
+- [`basic_json_view::dump`](../basic_json_view/dump.md) the corresponding function of `basic_json_view`, serializing
+  directly from a flat index without building a `basic_json` value
 - [Serialization](../../features/serialization.md) - the serialization article
 
 ## Version history

docs/mkdocs/docs/api/basic_json_view/dump.md

@@ -0,0 +1,102 @@
+# <small>nlohmann::basic_json_view::</small>dump
+
+```cpp
+string_t dump(const int indent = -1,
+              const char indent_char = ' ',
+              const bool ensure_ascii = false,
+              const number_format numbers = number_format::shortest) const;
+```
+
+Serializes this value (and its subtree) directly from the flat index, without ever building a `BasicJsonType` value
+first. With the default `#!cpp numbers == number_format::shortest`, the result is the same string
+[`BasicJsonType::dump`](../basic_json/dump.md) would produce for the value
+[`BasicJsonType::parse()`](../basic_json/parse.md) builds from the same source text, called with the same `indent`,
+`indent_char`, and `ensure_ascii` -- except that members of an object appear in document order rather than sorted by
+key, and *every* occurrence of a repeated key is written rather than only the last one (see
+[Notes on duplicate keys](operator[].md#notes)). For a `json_view` (whose `BasicJsonType` is not ordered), this means
+`dump()` can print an object's members in a different order than [`materialize()`](materialize.md)`.dump()` of the
+same subtree.
+
+## Parameters
+
+`indent` (in)
+:   If `indent` is nonnegative, array elements and object members are pretty-printed with that indent level. An
+    indent level of `0` only inserts newlines. `-1` (the default) selects the most compact representation.
+
+`indent_char` (in)
+:   The character used for indentation if `indent` is greater than `0`. The default is ` ` (space).
+
+`ensure_ascii` (in)
+:   If `ensure_ascii` is `#!cpp true`, all non-ASCII characters in the output are escaped with `\uXXXX` sequences, and
+    the result consists of ASCII characters only.
+
+`numbers` (in)
+:   how to write numbers, see [`number_format`](number_format.md): `shortest` (the default) writes them the way
+    [`BasicJsonType::dump`](../basic_json/dump.md) would; `source` copies every number exactly as it appears in the
+    source text.
+
+## Return value
+
+string containing the serialization of this value, or `#!cpp "<discarded>"` if the view is
+[discarded](is_discarded.md).
+
+## Exception safety
+
+Strong exception safety: if an exception is thrown, there are no changes to the view or the document it refers to.
+
+## Exceptions
+
+May throw `#!cpp std::bad_alloc` if allocating the output string fails. Unlike
+[`BasicJsonType::dump`](../basic_json/dump.md), there is no `error_handler` parameter and no
+[`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316): the view only ever holds text the parser
+already validated as UTF-8, so there is nothing to replace or ignore.
+
+## Complexity
+
+Linear in the size of the output text.
+
+## Notes
+
+The walk over the subtree is iterative, so the nesting depth it can write is limited by available memory only, not by
+the call stack -- as for [`materialize()`](materialize.md).
+
+Strings are escaped by the same rules as [`BasicJsonType::dump`](../basic_json/dump.md). With
+`#!cpp numbers == number_format::shortest`, floats are written with the library's shortest round-trip conversion,
+exactly as [`BasicJsonType::dump`](../basic_json/dump.md) would (e.g. `#!cpp 1.5`, `#!cpp 100.0`, `#!cpp 1e+100`), and
+integers are copied from the source text -- already canonical in JSON, so this matches their shortest form too --
+except that `#!cpp -0` is written as `#!cpp 0`, the way [`BasicJsonType::parse()`](../basic_json/parse.md) reads it.
+`#!cpp number_format::source` copies every number exactly as written in the source text instead, with no exception
+for `#!cpp -0` -- `#!cpp 1.50`, `#!cpp 1E2`, `#!cpp -0.0`, `#!cpp -0`, or all digits of an integer literal with more
+digits than any number type holds (such a literal is itself classified as a float, see
+[What is different](../../features/json_view.md#what-is-different)) -- something `BasicJsonType` cannot do, since
+parsing already reduces every number to its parsed value.
+
+## Examples
+
+??? example
+
+    The example below forwards a single record out of a larger batch, and re-serializes a configuration file, both
+    without ever building a `BasicJsonType` value for the surrounding array or for the parts of it that were not
+    needed. It also shows that [`materialize()`](materialize.md)`.dump()` of the configuration sorts its keys, where
+    `dump()` on the view keeps the order they appear in the source text.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__dump.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__dump.output"
+    ```
+
+## See also
+
+- [`number_format`](number_format.md) - how `dump()` writes numbers
+- [operator<<](operator_ltlt.md) - serialize this value to a stream
+- [materialize](materialize.md) - build a `BasicJsonType` value, e.g. to use `BasicJsonType::dump`'s `error_handler`
+- [`BasicJsonType::dump`](../basic_json/dump.md) - the corresponding function of `basic_json`
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/index.md

@@ -23,7 +23,7 @@ Moving the document itself does not invalidate its views: the index is heap-allo
 access, lookup, iteration, and conversion -- [`get<T>()`](get.md), [`get_string()`](get_string.md),
 [`number_token()`](number_token.md), and [`materialize()`](materialize.md) to build the `BasicJsonType` value of a
 subtree on demand. [`operator[]`](operator%5B%5D.md), [`at`](at.md), [`contains`](contains.md), and
-[`value`](value.md) also accept a [`json_pointer`](../json_pointer/index.md). It does not (yet) provide `dump()` or
+[`value`](value.md) also accept a [`json_pointer`](../json_pointer/index.md). It does not (yet) provide
 comparison.
 
 ## Template parameters
@@ -47,6 +47,7 @@ comparison.
 - **iterator**, **const_iterator** - a forward iterator over the elements of an array or the member values of an
   object, in document order; both names refer to the same type, since a view is always read-only
 - **item** - a (key, value) pair produced by [`items()`](items.md)
+- [**number_format**](number_format.md) - how [`dump()`](dump.md) writes numbers
 
 ## Member functions
 
@@ -106,6 +107,11 @@ comparison.
 - [**number_token**](number_token.md) - get a number's token text without a copy
 - [**materialize**](materialize.md) - build the `BasicJsonType` value of this subtree
 
+### Serialization
+
+- [**dump**](dump.md) - serialize to a JSON-formatted string
+- [**operator<<**](operator_ltlt.md) - serialize to stream
+
 ### Source access
 
 - [**source_offset**](source_offset.md) - byte offset of this value in the document's source text

docs/mkdocs/docs/api/basic_json_view/number_format.md

@@ -0,0 +1,51 @@
+# <small>nlohmann::basic_json_view::</small>number_format
+
+```cpp
+enum class number_format {
+    shortest,
+    source
+};
+```
+
+This enumeration is used in [`dump`](dump.md) to choose how numbers are written. Two values are differentiated:
+
+shortest
+:   integers are copied from the source text -- already canonical in JSON -- except that `#!cpp -0` becomes
+    `#!cpp 0`, the way [`BasicJsonType::parse()`](../basic_json/parse.md) reads it; floats are written with the
+    library's shortest round-trip conversion, exactly as [`BasicJsonType::dump()`](../basic_json/dump.md) would (e.g.
+    `#!cpp 1.5`, `#!cpp 100.0`, `#!cpp 1e+100`)
+
+source
+:   every number is copied exactly as it appears in the source text -- `#!cpp 1.50`, `#!cpp 1E2`, `#!cpp -0`, all
+    digits of an integer literal with more digits than any number type holds -- something `BasicJsonType` cannot do,
+    since parsing already reduces every number to its parsed value
+
+## Examples
+
+??? example
+
+    The example below writes back a price list received from a supplier: with `number_format::shortest` (the
+    default), a trailing zero and scientific notation are normalized away and a long account number that overflows
+    every number type is rounded, the same way `#!cpp materialize().dump()` (or `basic_json::dump()`) would;
+    `number_format::source` keeps every number exactly as it was written in the source text instead.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__number_format.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__number_format.output"
+    ```
+
+## See also
+
+- [dump](dump.md) - serialize to a JSON-formatted string
+- [number_token](number_token.md) - get a single number's token text without dumping the whole value
+- [`BasicJsonType::error_handler_t`](../basic_json/error_handler_t.md) - the analogous enumeration for
+  `BasicJsonType::dump`'s decoding-error behavior
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/basic_json_view/operator_ltlt.md

@@ -0,0 +1,74 @@
+# <small>nlohmann::basic_json_view::</small>operator<<
+
+```cpp
+std::ostream& operator<<(std::ostream& o, const basic_json_view& v);
+```
+
+Not available when [`JSON_NO_IO`](../macros/json_no_io.md) is defined.
+
+Serializes the given view `v` to the output stream `o`, using [`dump`](dump.md) -- exactly as
+`#!cpp operator<<(std::ostream&, const basic_json&)` does for a `basic_json` value.
+
+- The indentation of the output can be controlled with the member variable `width` of the output stream `o`. For
+  instance, using the manipulator `std::setw(4)` on `o` sets the indentation level to `4`, and the serialization
+  result is the same as calling `#!cpp v.dump(4)`. A `width` of `0` or less (the default) selects the most compact
+  representation, as `#!cpp v.dump(-1)` does.
+- The indentation character can be controlled with the member variable `fill` of the output stream `o`. For instance,
+  the manipulator `std::setfill('\t')` sets indentation to use a tab character rather than the default space
+  character.
+- As for `basic_json`, `o`'s `width` is reset to `0` after this call, whether or not it was greater than `0` before.
+
+Numbers are always written as `#!cpp v.dump()` writes them by default, i.e. as with
+[`number_format::shortest`](number_format.md); there is no way to select `#!cpp number_format::source` through the
+stream.
+
+## Parameters
+
+`o` (in, out)
+:   stream to write to
+
+`v` (in)
+:   view to serialize
+
+## Return value
+
+the stream `o`
+
+## Exceptions
+
+May throw `#!cpp std::bad_alloc`, propagated from [`dump`](dump.md#exceptions). Unlike
+`#!cpp operator<<(std::ostream&, const basic_json&)`, there is no UTF-8 decoding step that could throw
+[`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316), and no `error_handler` to choose between --
+see the [Exceptions](dump.md#exceptions) of `dump`.
+
+## Complexity
+
+Linear, as [`dump`](dump.md#complexity).
+
+## Examples
+
+??? example
+
+    The example below writes one record out of a larger batch straight to a log stream -- compact for a one-line
+    entry, and pretty-printed with `std::setw`/`std::setfill` for a readable dump -- without ever building a
+    `BasicJsonType` value for the record, or for the rest of the batch.
+
+    ```cpp
+    --8<-- "examples/basic_json_view__operator_ltlt.cpp"
+    ```
+
+    Output:
+
+    ```json
+    --8<-- "examples/basic_json_view__operator_ltlt.output"
+    ```
+
+## See also
+
+- [dump](dump.md) - serialize to a JSON-formatted string
+- [`operator<<(std::ostream&)`](../operator_ltlt.md) - the corresponding operator for `basic_json`
+- [`JSON_NO_IO`](../macros/json_no_io.md) - switch off functions relying on certain C++ I/O headers
+
+## Version history
+
+- Added in version 3.13.0.

docs/mkdocs/docs/api/operator_ltlt.md

@@ -84,6 +84,8 @@ Linear.
 ## See also
 
 - [dump](basic_json/dump.md) - serialize to a JSON-formatted string
+- [`basic_json_view::operator<<`](basic_json_view/operator_ltlt.md) - the corresponding operator for
+  `basic_json_view`
 - [Serialization](../features/serialization.md) - the serialization article
 
 ## Version history

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"
+}

docs/mkdocs/docs/features/json_view.md

@@ -139,8 +139,8 @@ whenever any of the other conditions above was not met.
   element access and lookup functions never carry the JSON Pointer path `JSON_DIAGNOSTICS` would otherwise add: the
   view has no `basic_json` value to point at, so the exception is created without one, regardless of how
   `BasicJsonType` was built.
-- **`dump()` and comparison are not (yet) provided** by `basic_json_view`. For now,
-  [`materialize()`](../api/basic_json_view/materialize.md) is the way to get a value you can do those things with.
+- **Comparison is not (yet) provided** by `basic_json_view`. For now,
+  [`materialize()`](../api/basic_json_view/materialize.md) is the way to get a value you can compare.
 
 ## Getting values out without copying
 
@@ -166,6 +166,23 @@ Two conversions never copy at all:
 
 Both results are only valid as long as the view -- and, for a string with no escapes, the borrowed source text -- is.
 
+## Writing a view back
+
+[`dump()`](../api/basic_json_view/dump.md) serializes a view directly from the flat index, without ever building a
+`basic_json` value. An object's members are written in document order, not sorted by key, and *every* occurrence of a
+repeated key is written, not only the last one -- the same two ways [iteration](#what-is-different) already differs
+from a [`materialize()`](../api/basic_json_view/materialize.md)d value, see above. `#!cpp materialize().dump()` gives
+a different result in both respects for a `json_view`.
+
+By default, numbers are written the way [`basic_json::dump()`](../api/basic_json/dump.md) would.
+[`number_format::source`](../api/basic_json_view/number_format.md) instead copies every number exactly as it was
+written in the source text -- a price like `#!cpp 19.90`, a long order or account ID with more digits than any number
+type holds, or a high-precision coordinate -- something `basic_json` cannot do at all, since parsing already reduces
+a number to its parsed `#!cpp double`/`#!cpp int64_t` value.
+
+[`operator<<`](../api/basic_json_view/operator_ltlt.md) writes a view to a stream the way `basic_json`'s does, using
+the stream's `width`/`fill` for indentation.
+
 ## Choosing between `json`, `ordered_json`, the SAX interface, and `json_view`
 
 | | [`json`](../api/json.md) / [`ordered_json`](../api/ordered_json.md) | [SAX interface](parsing/sax_interface.md) | [`json_document`](../api/json_document.md) / [`json_view`](../api/json_view.md) |

docs/mkdocs/mkdocs.yml

@@ -253,6 +253,7 @@ nav:
           - 'cend': api/basic_json_view/cend.md
           - 'contains': api/basic_json_view/contains.md
           - 'count': api/basic_json_view/count.md
+          - 'dump': api/basic_json_view/dump.md
           - 'empty': api/basic_json_view/empty.md
           - 'end': api/basic_json_view/end.md
           - 'find': api/basic_json_view/find.md
@@ -275,8 +276,10 @@ nav:
           - 'is_structured': api/basic_json_view/is_structured.md
           - 'items': api/basic_json_view/items.md
           - 'materialize': api/basic_json_view/materialize.md
+          - 'number_format': api/basic_json_view/number_format.md
           - 'number_token': api/basic_json_view/number_token.md
           - 'operator bool': api/basic_json_view/operator_bool.md
+          - 'operator<<': api/basic_json_view/operator_ltlt.md
           - 'operator[]': api/basic_json_view/operator[].md
           - 'size': api/basic_json_view/size.md
           - 'source_offset': api/basic_json_view/source_offset.md