nlohmann::basic_json_view::dump¶

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 numbers == number_format::shortest, the result is the same string BasicJsonType::dump would produce for the value BasicJsonType::parse() 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). For a json_view (whose BasicJsonType is not ordered), this means dump() can print an object's members in a different order than materialize().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 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: shortest (the default) writes them the way BasicJsonType::dump would; source copies every number exactly as it appears in the source text.

Return value¶

string containing the serialization of this value, or "<discarded>" if the view is discarded.

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 std::bad_alloc if allocating the output string fails. Unlike BasicJsonType::dump, there is no error_handler parameter and no type_error.316: 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().

Strings are escaped by the same rules as BasicJsonType::dump.

With numbers == number_format::shortest, floats are written with the library's shortest round-trip conversion, exactly as BasicJsonType::dump would (e.g. 1.5, 100.0, 1e+100), and integers are copied from the source text -- already canonical in JSON, so this matches their shortest form too -- except that -0 is written as 0, the way BasicJsonType::parse() reads it.

number_format::source copies every number exactly as written in the source text instead, with no exception for -0 -- 1.50, 1E2, -0.0, -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) -- 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().dump() of the configuration sorts its keys, where dump() on the view keeps the order they appear in the source text.

#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';
}

Output:

{"id":2,"temp":87.3}
{
  "name": "cache",
  "host": "db1",
  "port": 6379,
  "timeout": 30
}

{
  "host": "db1",
  "name": "cache",
  "port": 6379,
  "timeout": 30
}

Version history¶

Added in version 3.13.0 unreleased.