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(char *value);
bool add(const char *value); // ⚠️ stores by pointer
bool add(const __FlashStringHelper *value);
bool add(const String &value);
bool add(const std::string &value);
bool add(const Printable& value);
bool add(std::string_view value);
bool add(JsonArray array);
bool add(JsonObject object);
bool add(JsonVariant variant);
bool add(const JsonDocument& doc);
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.
If you pass a JsonArray
, a JsonObject
, or a JsonVariant
, JsonDocument::add()
makes a complete clone of the argument. In other words, the value is stored by copy, not by reference.
As usual, ArduinoJson makes a copy of a string in the JsonDocument
, except if it’s a const char*
.
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
.
String duplication
ArduinoJson makes a copy of the string when you call this function with one of the following types:
char*
String
(orstd::string
)const __FlashStringHelper*
(i.e. Flash string)
Example
JsonDocument doc;
array.add("hello"); // null -> ["hello"]
array.add(3.14156); // ["hello"] -> ["hello",3.14156]
serializeJson(doc, Serial);
will write
["hello",3.14156]