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.
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)).
string containing the serialization of the JSON value
Strong guarantee: if an exception is thrown, there are no changes to any JSON value.
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.
Linear.
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:
#!json null if the binary has no subtype??? example
The following example shows the effect of different `indent`, `indent_char`, and `ensure_ascii` parameters to the
result of the serialization.
```cpp
#include <iostream>
#include <nlohmann/json.hpp>
using json = nlohmann::json;
int main()
{
// create JSON values
json j_object = {{"one", 1}, {"two", 2}};
json j_array = {1, 2, 4, 8, 16};
json j_string = "Hellö 😀!";
// call dump()
std::cout << "objects:" << '\n'
<< j_object.dump() << "\n\n"
<< j_object.dump(-1) << "\n\n"
<< j_object.dump(0) << "\n\n"
<< j_object.dump(4) << "\n\n"
<< j_object.dump(1, '\t') << "\n\n";
std::cout << "arrays:" << '\n'
<< j_array.dump() << "\n\n"
<< j_array.dump(-1) << "\n\n"
<< j_array.dump(0) << "\n\n"
<< j_array.dump(4) << "\n\n"
<< j_array.dump(1, '\t') << "\n\n";
std::cout << "strings:" << '\n'
<< j_string.dump() << '\n'
<< j_string.dump(-1, ' ', true) << '\n';
// create JSON value with invalid UTF-8 byte sequence
json j_invalid = "ä\xA9ü";
try
{
std::cout << j_invalid.dump() << std::endl;
}
catch (const json::type_error& e)
{
std::cout << e.what() << std::endl;
}
std::cout << "string with replaced invalid characters: "
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
<< "\nstring with ignored invalid characters: "
<< j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
<< '\n';
}
```
Output:
```json
objects:
{"one":1,"two":2}
{"one":1,"two":2}
{
"one": 1,
"two": 2
}
{
"one": 1,
"two": 2
}
{
"one": 1,
"two": 2
}
arrays:
[1,2,4,8,16]
[1,2,4,8,16]
[
1,
2,
4,
8,
16
]
[
1,
2,
4,
8,
16
]
[
1,
2,
4,
8,
16
]
strings:
"Hellö 😀!"
"Hell\u00f6 \ud83d\ude00!"
[json.exception.type_error.316] invalid UTF-8 byte at index 2: 0xA9
string with replaced invalid characters: "ä�ü"
string with ignored invalid characters: "äü"
```
basic_json_view::dump the corresponding function of basic_json_view, serializing directly from a flat index without building a basic_json valueindent_char, option ensure_ascii and exceptions added in version 3.0.0.keep added in version 3.13.0.