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

nlohmann::basic_json::dump

string_t dump(const int indent = -1,
              const char indent_char = ' ',
              const bool ensure_ascii = false,
              const error_handler_t error_handler = error_handler_t::strict) const;

Serialization function for JSON values. The function tries to mimic Python's json.dumps() function, and currently supports its indent and ensure_ascii parameters.

Parameters

indent (in)

If indent is nonnegative, then array elements and object members will be pretty-printed with that indent level. An indent level of 0 will only insert newlines. -1 (the default) selects the most compact representation.

indent_char (in)

The character to use 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.

error_handler (in)

how to react on decoding errors; there are four possible values (see error_handler_t: strict (throws an exception in case a decoding error occurs; default), replace (replace invalid UTF-8 sequences with U+FFFD), ignore (ignore invalid UTF-8 sequences during serialization; all valid bytes are copied to the output unchanged, and invalid bytes are dropped), and keep (write the ill-formed bytes to the output as is, without escaping them, even if ensure_ascii is #!cpp true; the result is then not valid UTF-8, but equals the input bytes exactly, and well-formed characters around the ill-formed bytes are still escaped as usual)).

Return value

string containing the serialization of the JSON value

Exception safety

Strong guarantee: if an exception is thrown, there are no changes to any JSON value.

Exceptions

Throws type_error.316 if a string stored inside the JSON value is not UTF-8 encoded and error_handler is set to strict

!!! warning "Serializing untrusted input"

When serializing values that may contain invalid or untrusted UTF-8 (e.g., bytes taken directly from network
input), `dump()` throws [`type_error.316`](../../home/exceptions.md#jsonexceptiontype_error316) in the default
`strict` mode. To serialize such data without throwing, pass
[`error_handler_t::replace`](error_handler_t.md) (substitutes U+FFFD) or
[`error_handler_t::ignore`](error_handler_t.md). Callers that serialize untrusted input on a crash-sensitive path
should either choose a non-strict error handler or wrap `dump()` in a `#!cpp try`/`#!cpp catch`.

See the [FAQ](../../home/faq.md#serializing-untrusted-or-invalid-utf-8) for details.

Complexity

Linear in the size of the result. With an indent, every line starts with up to indent characters per nesting level, so the result can be larger than the value by a factor of its nesting depth (see Parsing untrusted input).

Notes

Floating-point numbers are written with the fewest digits that read back as the same value (for #!cpp double; see number handling).

Binary values are serialized as an object containing two keys:

• "bytes": an array of bytes as integers
• "subtype": the subtype as integer or #!json null if the binary has no subtype

Examples

??? example

The following example shows the effect of different `indent`, `indent_char`, and `ensure_ascii` parameters to the
result of the serialization.

```cpp
--8<-- "examples/dump.cpp"
```

Output:

```json
--8<-- "examples/dump.output"
```

See also

• to_string - returns a string representation of a JSON value
• operator<< - serialize to stream
• basic_json_view::dump - the corresponding function of basic_json_view, serializing directly from a flat index without building a basic_json value
• Serialization - the serialization article

Version history

• Added in version 1.0.0.
• Indentation character indent_char, option ensure_ascii and exceptions added in version 3.0.0.
• Error handlers added in version 3.4.0.
• Serialization of binary values added in version 3.8.0.
• Error handler keep added in version 3.13.0.
• Doubles are written with the shortest digits (Żmij instead of Grisu2) since version 3.13.0; about 0.1% of doubles are written differently, most of them with fewer digits.