mirror of https://github.com/nlohmann/json.git synced 2025-06-09 05:12:50 +08:00

* 🔥 consolidate documentation
* ♻️ overwork std specializations
* 🚚 move images files to mkdocs
* ♻️ fix URLs
* 🔧 tweak MkDocs configuration
* 🔧 add namespaces
* 📝 document deprecations
* 📝 document documentation generation
* 🚸 improve search
* 🚸 add examples
* 🚧 start adding documentation for macros
* 📝 add note for https://github.com/nlohmann/json/issues/874#issuecomment-1001699139
* 📝 overwork example handling
* 📝 fix Markdown tables

2021-12-29 13:41:01 +01:00

2.5 KiB

Raw Blame History

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 three possible values (see error_handler_t: strict (throws and exception in case a decoding error occurs; default), replace (replace invalid UTF-8 sequences with U+FFFD), and ignore (ignore invalid UTF-8 sequences during serialization; all bytes are copied to the output unchanged)).

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

Complexity

Linear.

Notes

Binary values are serialized as 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"
```

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.

2.5 KiB Raw Blame History