From f1edbabd3ec6b76ef1ff96a015c2e415781a4859 Mon Sep 17 00:00:00 2001 From: Niels Lohmann Date: Mon, 28 Sep 2026 23:27:04 +0200 Subject: [PATCH] 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 --- docs/docset/docSet.sql | 3 + docs/mkdocs/docs/api/basic_json/dump.md | 2 + docs/mkdocs/docs/api/basic_json_view/dump.md | 102 ++++++++++++++++++ docs/mkdocs/docs/api/basic_json_view/index.md | 8 +- .../docs/api/basic_json_view/number_format.md | 51 +++++++++ .../docs/api/basic_json_view/operator_ltlt.md | 74 +++++++++++++ docs/mkdocs/docs/api/operator_ltlt.md | 2 + .../docs/examples/basic_json_view__dump.cpp | 25 +++++ .../examples/basic_json_view__dump.output | 14 +++ .../basic_json_view__number_format.cpp | 28 +++++ .../basic_json_view__number_format.output | 2 + .../basic_json_view__operator_ltlt.cpp | 26 +++++ .../basic_json_view__operator_ltlt.output | 10 ++ docs/mkdocs/docs/features/json_view.md | 21 +++- docs/mkdocs/mkdocs.yml | 3 + 15 files changed, 368 insertions(+), 3 deletions(-) create mode 100644 docs/mkdocs/docs/api/basic_json_view/dump.md create mode 100644 docs/mkdocs/docs/api/basic_json_view/number_format.md create mode 100644 docs/mkdocs/docs/api/basic_json_view/operator_ltlt.md create mode 100644 docs/mkdocs/docs/examples/basic_json_view__dump.cpp create mode 100644 docs/mkdocs/docs/examples/basic_json_view__dump.output create mode 100644 docs/mkdocs/docs/examples/basic_json_view__number_format.cpp create mode 100644 docs/mkdocs/docs/examples/basic_json_view__number_format.output create mode 100644 docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.cpp create mode 100644 docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.output diff --git a/docs/docset/docSet.sql b/docs/docset/docSet.sql index a663c8726..e0281f893 100644 --- a/docs/docset/docSet.sql +++ b/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'); diff --git a/docs/mkdocs/docs/api/basic_json/dump.md b/docs/mkdocs/docs/api/basic_json/dump.md index a3c9db3a8..f2a493f25 100644 --- a/docs/mkdocs/docs/api/basic_json/dump.md +++ b/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 diff --git a/docs/mkdocs/docs/api/basic_json_view/dump.md b/docs/mkdocs/docs/api/basic_json_view/dump.md new file mode 100644 index 000000000..7cc0b6b38 --- /dev/null +++ b/docs/mkdocs/docs/api/basic_json_view/dump.md @@ -0,0 +1,102 @@ +# nlohmann::basic_json_view::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 ""` 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. diff --git a/docs/mkdocs/docs/api/basic_json_view/index.md b/docs/mkdocs/docs/api/basic_json_view/index.md index 50bcaa24b..da50a61e2 100644 --- a/docs/mkdocs/docs/api/basic_json_view/index.md +++ b/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()`](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 diff --git a/docs/mkdocs/docs/api/basic_json_view/number_format.md b/docs/mkdocs/docs/api/basic_json_view/number_format.md new file mode 100644 index 000000000..6b8c6805d --- /dev/null +++ b/docs/mkdocs/docs/api/basic_json_view/number_format.md @@ -0,0 +1,51 @@ +# nlohmann::basic_json_view::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. diff --git a/docs/mkdocs/docs/api/basic_json_view/operator_ltlt.md b/docs/mkdocs/docs/api/basic_json_view/operator_ltlt.md new file mode 100644 index 000000000..c2735b360 --- /dev/null +++ b/docs/mkdocs/docs/api/basic_json_view/operator_ltlt.md @@ -0,0 +1,74 @@ +# nlohmann::basic_json_view::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. diff --git a/docs/mkdocs/docs/api/operator_ltlt.md b/docs/mkdocs/docs/api/operator_ltlt.md index 1f99493d9..2bf9a7fc1 100644 --- a/docs/mkdocs/docs/api/operator_ltlt.md +++ b/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 diff --git a/docs/mkdocs/docs/examples/basic_json_view__dump.cpp b/docs/mkdocs/docs/examples/basic_json_view__dump.cpp new file mode 100644 index 000000000..7a00c06d2 --- /dev/null +++ b/docs/mkdocs/docs/examples/basic_json_view__dump.cpp @@ -0,0 +1,25 @@ +#include +#include + +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'; +} diff --git a/docs/mkdocs/docs/examples/basic_json_view__dump.output b/docs/mkdocs/docs/examples/basic_json_view__dump.output new file mode 100644 index 000000000..e6e03522c --- /dev/null +++ b/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 +} diff --git a/docs/mkdocs/docs/examples/basic_json_view__number_format.cpp b/docs/mkdocs/docs/examples/basic_json_view__number_format.cpp new file mode 100644 index 000000000..f67ea4e84 --- /dev/null +++ b/docs/mkdocs/docs/examples/basic_json_view__number_format.cpp @@ -0,0 +1,28 @@ +#include +#include + +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'; +} diff --git a/docs/mkdocs/docs/examples/basic_json_view__number_format.output b/docs/mkdocs/docs/examples/basic_json_view__number_format.output new file mode 100644 index 000000000..b4ab72d54 --- /dev/null +++ b/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}] diff --git a/docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.cpp b/docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.cpp new file mode 100644 index 000000000..97100d536 --- /dev/null +++ b/docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.cpp @@ -0,0 +1,26 @@ +#include +#include +#include + +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'; +} diff --git a/docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.output b/docs/mkdocs/docs/examples/basic_json_view__operator_ltlt.output new file mode 100644 index 000000000..d791fc312 --- /dev/null +++ b/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" +} diff --git a/docs/mkdocs/docs/features/json_view.md b/docs/mkdocs/docs/features/json_view.md index 7dbea9241..5d992a945 100644 --- a/docs/mkdocs/docs/features/json_view.md +++ b/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) | diff --git a/docs/mkdocs/mkdocs.yml b/docs/mkdocs/mkdocs.yml index 0ff0f9fc3..8b6b6ced8 100644 --- a/docs/mkdocs/mkdocs.yml +++ b/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