serializeJson()
Description
serializeJson()
serializes a JsonDocument
to create a minified JSON document, i.e. a document without spaces or line break between values.
If you want a prettified JSON document, use serializeJsonPretty()
Signatures
size_t serializeJson(const JsonDocument& doc, char* output, size_t outputSize); // see remark 1
size_t serializeJson(const JsonDocument& doc, char output[size]); // see remark 1
size_t serializeJson(const JsonDocument& doc, Print& output);
size_t serializeJson(const JsonDocument& doc, String& output); // see remark 2
size_t serializeJson(const JsonDocument& doc, std::string& output); // see remark 2
size_t serializeJson(const JsonDocument& doc, std::ostream& output);
template<typename Writer> // custom writer class (see below)
size_t serializeJson(const JsonDocument& doc, Writer& output);
➀ These overloads only add the zero-terminator if there is enough room in the buffer; this is the same caveat as strncpy()
.
Therefore, make sure that the buffer is large enough or check the return value.
➁ This function treats String
and std::string
as streams: it doesn’t replace the content but appends to the end.
The two first overloads support unsigned char
as well.
Arguments
doc
: theJsonDocument
to serialize (in fact, you can also use aJsonArray
, aJsonObject
, or aJsonVariant
)output
: the destination buffer where the result should be writtenoutputSize
: the capacity of the destination buffer
Because output
can be any implementation of Print
, you can uses instances like Serial
, EthernetClient
, WifiClient
…
Return value
The number of bytes written.
Configuration
You can configure serializeJson()
with the following settings:
ARDUINOJSON_ENABLE_NAN
writesNaN
instead ofnull
,ARDUINOJSON_ENABLE_INFINITY
writesInfinity
instead ofnull
.
How to view the JSON output?
When you pass a Stream
to serializeJson()
, it writes the JSON to the stream but doesn’t print anything to the serial port, which makes troubleshooting difficult.
If you want to see what serializeJson()
writes, use WriteLoggingStream
from the StreamUtils library. See the example below.
Performance
When you pass a Stream
to serializeJson()
, it sends the bytes one by one, which can be slow depending on the target stream. For example, if you send to a WiFiClient
on an ESP8266, it will send a packet over the air for each byte, which is terribly slow and inefficient. To improve speed and efficiency, we must send fewer, larger packets.
To write the JSON document in chunks, you can use WriteBufferingStream
from the StreamUtils library. See the example below.
Custom writer
If none of the supported output types is suitable for you, you can implement a custom writer class. This class must implement two member functions, as shown below:
struct CustomWriter {
// Writes one byte, returns the number of bytes written (0 or 1)
size_t write(uint8_t c);
// Writes several bytes, returns the number of bytes written
size_t write(const uint8_t *buffer, size_t length);
};
Then, pass a reference to an instance of this class as the second argument of serializeJson()
.
Example
Write the JSON document to the serial port
StaticJsonDocument<200> doc;
doc["hello"] = "world";
serializeJson(doc, Serial);
will write the following string to the serial port:
{"hello":"world"}
Write to a file
File file = SD.open(filename, FILE_WRITE);
StaticJsonDocument<256> doc;
doc["hello"] = "world";
serializeJson(doc, file);
file.close();
Write to a file and print to the serial port
This example requires the StreamUtils library; it uses the WriteLoggingStream
decorator that adds logging capability to an existing Stream
.
File file = SD.open(filename, FILE_WRITE);
WriteLoggingStream loggedFile(file, Serial);
doc["hello"] = "world";
serializeJson(doc, loggedFile);
file.close();
The second line create a new Stream
that forward every calls to file
and duplicate writes calls to Serial
.
Improve file write performance
This example requires the StreamUtils library; it uses the WriteBufferingStream
decorator that adds buffering capability to an existing Stream
.
File file = SD.open(filename, FILE_WRITE);
WriteBufferingStream bufferedFile(file, 64);
doc["hello"] = "world";
serializeJson(doc, bufferedFile);
bufferedFile.flush();
file.close();
The first line creates the file and the second line adds a 64 byte buffer in front of the file. The next to last line writes the remaining bytes in the file.