JsonDocument::add()
Description
When the JsonDocument
contains an array, JsonDocument::add()
appends a value to the array.
When the JsonDocument
contains a value that is not an array, JsonDocument::add()
does nothing.
When the JsonDocument
is empty, JsonDocument::add()
converts the JsonDocument
to an array containing one element.
This feature allows creating an array without calling JsonDocument::to<JsonArray()
. For example the two following snippets are equivalent:
JsonArray arr = doc.to<JsonArray>();
arr.add(42);
doc.clear();
doc.add(42);
Signatures
bool add(bool value);
bool add(float value);
bool add(double value);
bool add(signed char value);
bool add(signed long value);
bool add(signed int value);
bool add(signed short value);
bool add(unsigned char value);
bool add(unsigned long value);
bool add(unsigned int value);
bool add(unsigned short value);
bool add(const char (&value)[N]); // stores a pointer
bool add(const char *value); // stores a copy
bool add(const __FlashStringHelper *value); // stores a copy
bool add(const String &value); // stores a copy
bool add(const std::string &value); // stores a copy
bool add(const Printable& value); // stores a copy
bool add(std::string_view value); // stores a copy
bool add(JsonArray array); // stores a deep copy
bool add(JsonObject object); // stores a deep copy
bool add(JsonVariant variant); // stores a deep copy
bool add(const JsonDocument& doc); // stores a deep copy
bool add(TEnum value); // alias of add(int)
bool add(T value); // calls user-defined function
JsonArray add<JsonArray>() const; // adds a new empty array
JsonObject add<JsonObject>() const; // adds a new empty object
JsonVariant add<JsonVariant>() const; // adds a new null variant
Arguments
value
: the value of to append to the array, it can be any type supported by ArduinoJson.
All values are stored by copy, except string literals which are stored by address.
The string copy policy has changed in ArduinoJson 7.3.
Return value
JsonDocument::add()
returns a bool
that tells whether the operation was successful or not:
true
if the value was successfully added.false
if there was not enough memory in theJsonDocument
.
Example
JsonDocument doc;
array.add("hello"); // null -> ["hello"]
array.add(3.14156); // ["hello"] -> ["hello",3.14156]
serializeJson(doc, Serial);
will write
["hello",3.14156]