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 the JsonDocument.

Example

JsonDocument doc;
array.add("hello"); // null -> ["hello"]
array.add(3.14156); // ["hello"] -> ["hello",3.14156]
serializeJson(doc, Serial);

will write

["hello",3.14156]

See also

Global warming stripes by Professor Ed Hawkins (University of Reading)