JSON for Modern C++ 3.10.4

◆ dump()

template<template< typename U, typename V, typename... Args > class ObjectType = std::map, template< typename U, typename... Args > class ArrayType = std::vector, class StringType = std::string, class BooleanType = bool, class NumberIntegerType = std::int64_t, class NumberUnsignedType = std::uint64_t, class NumberFloatType = double, template< typename U > class AllocatorType = std::allocator, template< typename T, typename SFINAE=void > class JSONSerializer = adl_serializer, class BinaryType = std::vector<std::uint8_t>>
string_t nlohmann::basic_json< ObjectType, ArrayType, StringType, BooleanType, NumberIntegerType, NumberUnsignedType, NumberFloatType, AllocatorType, JSONSerializer, BinaryType >::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
inline

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
[in]indentIf 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.
[in]indent_charThe character to use for indentation if indent is greater than 0. The default is (space).
[in]ensure_asciiIf ensure_ascii is true, all non-ASCII characters in the output are escaped with \uXXXX sequences, and the result consists of ASCII characters only.
[in]error_handlerhow to react on decoding errors; there are three possible values: 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).
Returns
string containing the serialization of the JSON value
Exceptions
type_error.316if a string stored inside the JSON value is not UTF-8 encoded and error_handler is set to strict
Note
Binary values are serialized as object containing two keys:
  • "bytes": an array of bytes as integers
  • "subtype": the subtype as integer or "null" if the binary has no subtype
Complexity
Linear.
Exception safety
Strong guarantee: if an exception is thrown, there are no changes in the JSON value.
Example
The following example shows the effect of different indent, indent_char, and ensure_ascii parameters to the result of the serialization.
1#include <iostream>
2#include <nlohmann/json.hpp>
3
4using json = nlohmann::json;
5
6int main()
7{
8 // create JSON values
9 json j_object = {{"one", 1}, {"two", 2}};
10 json j_array = {1, 2, 4, 8, 16};
11 json j_string = "Hellö 😀!";
12
13 // call dump()
14 std::cout << "objects:" << '\n'
15 << j_object.dump() << "\n\n"
16 << j_object.dump(-1) << "\n\n"
17 << j_object.dump(0) << "\n\n"
18 << j_object.dump(4) << "\n\n"
19 << j_object.dump(1, '\t') << "\n\n";
20
21 std::cout << "arrays:" << '\n'
22 << j_array.dump() << "\n\n"
23 << j_array.dump(-1) << "\n\n"
24 << j_array.dump(0) << "\n\n"
25 << j_array.dump(4) << "\n\n"
26 << j_array.dump(1, '\t') << "\n\n";
27
28 std::cout << "strings:" << '\n'
29 << j_string.dump() << '\n'
30 << j_string.dump(-1, ' ', true) << '\n';
31
32 // create JSON value with invalid UTF-8 byte sequence
33 json j_invalid = "ä\xA9ü";
34 try
35 {
36 std::cout << j_invalid.dump() << std::endl;
37 }
38 catch (json::type_error& e)
39 {
40 std::cout << e.what() << std::endl;
41 }
42
43 std::cout << "string with replaced invalid characters: "
44 << j_invalid.dump(-1, ' ', false, json::error_handler_t::replace)
45 << "\nstring with ignored invalid characters: "
46 << j_invalid.dump(-1, ' ', false, json::error_handler_t::ignore)
47 << '\n';
48}
detail::type_error type_error
exception indicating executing a member function with a wrong type
Definition: json.hpp:17769
basic_json<> json
default JSON class
Definition: json.hpp:3472

Output (play with this example online):
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: "äü"
The example code above can be translated with
g++ -std=c++11 -Isingle_include doc/examples/dump.cpp -o dump 
See also
https://docs.python.org/2/library/json.html#json.dump
Since
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.

Definition at line 19919 of file json.hpp.