Niels Lohmann
da1ca7f9d7
Add basic_json_view::dump() and the comparison operators, and read floats from the parser's digit layout instead of rescanning the token. dump(indent, indent_char, ensure_ascii, number_format) writes a value the way ordered_json::parse(text).dump() writes it for the same arguments: members in document order, all of them should a key occur more than once; strings escaped by the same rules, using the library's scanning kernels; floats written with the library's to_chars conversion, so the output equals basic_json's byte for byte; integers copied from the source, where they are already canonical, except -0, which parse() reads as 0. There is no error_handler argument, because the view only holds valid UTF-8. number_format::source copies numbers exactly as they appear in the source (e.g. "1.50", "1E2", "-0"), which basic_json cannot provide. operator<< takes the indentation from the stream width, as for basic_json. The writer walks iteratively, so nesting depth is limited by memory only. operator== and operator!= compare two views, or a view and a basic_json value in either order, by the rules basic_json's operator== uses: numbers compare by value across their types, objects compare by their members with duplicate keys resolved as parse() resolves them, member order matters only where the object type keeps one, and discarded views compare as discarded basic_json values do, including under JSON_USE_LEGACY_DISCARDED_VALUE_COMPARISON. Nothing is materialized except single scalars. While parsing, the view now records where the integer digits, the fraction digits, and the exponent of a float token are, so floats and doubles with at most 19 digits are read from that layout with the library's decimal_to_float() instead of rescanning the token. Both round correctly, so the values are those of parse(). get<double>(), materialize(), dump(), and the comparisons all use it. Signed-off-by: Niels Lohmann <mail@nlohmann.me>
107 lines
4.4 KiB
Markdown
107 lines
4.4 KiB
Markdown
# <small>nlohmann::basic_json::</small>dump
|
|
|
|
```cpp
|
|
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](https://docs.python.org/2/library/json.html#json.dump), 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`](error_handler_t.md):
|
|
`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`](../../home/exceptions.md#jsonexceptiontype_error316) 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.
|
|
|
|
## Notes
|
|
|
|
Floating-point numbers are written with the fewest digits that read back as the same value (for `#!cpp double`; see
|
|
[number handling](../../features/types/number_handling.md#number-serialization)).
|
|
|
|
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](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
|
|
|
|
- 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.
|