Skip to content

API Reference

Jump to bottom Edit New page
Benoît Blanchon edited this page Sep 9, 2016 · 36 revisions

This is the detailed documentation of every class and function of the ArduinoJson library. Some parts have been simplified to be easier to understand, so if you look at the source code, you might see some differences.

JsonArray

Represents an array in a JSON object tree.

Constructor

The constructor is private, you cannot instantiate a JsonArray directly, you have to use a JsonBuffer.

Because the memory of a JsonArray is located a JsonBuffer, you always manipulate it through reference and you cannot copy it.

Example
StaticJsonBuffer<200> jsonBuffer;

// create an empty array
JsonArray& array1 = jsonBuffer.createArray();

// parse a JSON array
char json[] = "[1,2,3]";
JsonArray& array2 = jsonBuffer.parseArray(json);

JsonArray::add()

Description

Adds a value to the end of the array.

Signatures
bool add(bool value);
bool add(float value, uint8_t decimals = 2);
bool add(double value, uint8_t decimals = 2);
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);
bool add(const String &value); // see Remarks
bool add(JsonArray &array);
bool add(JsonObject &object);
bool add(const JsonVariant &variant);
Arguments

value: the value to add to the array.

decimals: the number of digits to print after the decimal point.

Return value

true if the value was successfully added.

false if there was not enough memory in the JsonBuffer.

Remarks

When you call JsonArray::add(const String&), a copy of the string is made, causing the JsonBuffer to grow. The memory allocated for the copy will only be freed when the whole JsonBuffer is discarded. To avoid this behavior, use JsonArray::add(const char*) instead.

Example
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add(3.14156, 4);
array.printTo(Serial);

will write

["hello",3.1416]

JsonArray::createNestedArray()

Description

Adds a new nested array to the end of the array.

Signature
JsonArray& createNestedArray();
Return value

A reference to the new JsonArray. You can check JsonArray::success() to verify that the allocation succeeded.

Example
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
JsonArray& nested = array.createNestedArray();
nested.add("world");
array.printTo(Serial);

will write

["hello",["world"]]

JsonArray::createNestedObject()

Description

Adds a new nested object to the end of the array.

Signature
JsonObject& createNestedObject();
Return value

A reference to the new JsonObject. You can check JsonObject::success() to verify that the allocation succeeded.

Example
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
JsonObject& nested = array.createNestedObject();
nested["hello"] = "world";
array.printTo(Serial);

will write

[{"hello":"world"}]

JsonArray::get()

Description

Gets the value at the specified index.

Signature
// Non template version
JsonVariant     get                 (size_t index) const;

// Template version
bool            get<bool>           (size_t index) const;
const char*     get<const char*>    (size_t index) const;
double          get<double>         (size_t index) const;
float           get<float>          (size_t index) const;
signed char     get<signed char>    (size_t index) const;
signed int      get<signed int>     (size_t index) const;
signed long     get<signed long>    (size_t index) const;
signed short    get<signed short>   (size_t index) const;
String          get<String>         (size_t index) const;
unsigned char   get<unsigned char>  (size_t index) const;
unsigned int    get<unsigned int>   (size_t index) const;
unsigned long   get<unsigned long>  (size_t index) const;
unsigned short  get<unsigned short> (size_t index) const;
Arguments

index: the index of the value in the array.

T: the type of the value

Return value

The value at the specified index. This can be a JsonVariant or a value of type T.

The template version of get() returns a value of the specified type. In the case of an error (index out of range or incompatible type), the default value of the type T is returned.

Example
char json[] = "[1,3.14]";
StaticJsonBuffer<256> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray(json);
int value0 = array.get(0); // implicit cast of the JsonVariant
float value1 = array.get<float>(1); // template version of get()
const char* value2 = array.get(2); // returns NULL

JsonArray::measureLength()

Description

Gets the length of string produced by JsonArray::printTo().

This can be very handy to fill the Content-Length of an HTTP request or response.

Return value

The number of characters in the JSON string that would be generated by JsonArray::printTo().

It doesn't include the zero-terminator.

Signature
size_t measureLength() const

JsonArray::measurePrettyLength()

Description

Gets the length of string produced by JsonArray::prettyPrintTo().

Signature
size_t measurePrettyLength() const
Return value

The number of characters in the JSON string that would be generated by JsonArray::prettyPrintTo().

It doesn't include the zero-terminator.

JsonArray::operator[]

Description

A shortcut for JsonArray::get() and JsonArray::set(), with an array-like syntax.

Signatures
JsonVariant& operator[](size_t index);
const JsonVariant& operator[](size_t index) const;
Arguments

index: the zero-based position of the value in the array.

Return value

A reference to the JsonVariant in the array.

Example
JsonArray& array = jsonBuffer::createArray();
array.add(42);
int value = array[0];
array[0] = 666;

JsonArray::prettyPrintTo()

Description

Serialize the array to an indented JSON string.

This will create a "prettified" JSON, if you want a compact JSON without space or line break, use JsonArray::print()

Signatures
size_t prettyPrintTo(char* buffer, size_t size) const;
size_t prettyPrintTo(Print &) const;
size_t prettyPrintTo(String &) const;
Arguments

The destination of the JSON string.

Can be either:

  • a buffer with specified size (this includes the zero-terminator)
  • an implementation of Print (like Serial, EthernetClient...)
  • a String
Return value

The number of bytes written

Example
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add("world");
array.prettyPrintTo(Serial);

will write the following string to the serial output:

[
  "hello",
  "world"
]

JsonArray::printTo()

Description

Serialize the array to a JSON string.

This will create a compact JSON, if you want a pretty JSON with spaces and line breaks, use JsonArray::prettyPrint()

Signatures
size_t printTo(char* buffer, size_t size) const;
size_t printTo(Print &) const;
size_t printTo(String &) const;
Arguments

The destination of the JSON string.

Can be either:

  • a buffer with specified size (this includes the zero-terminator)
  • an implementation of Print (like Serial, EthernetClient...)
  • a String
Return value

The number of bytes written

Example
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add("world");
array.printTo(Serial);

will write the following string to the serial output:

["hello","world"]

JsonArray::removeAt()

Description

Removes the element at the specified index.

IMPORTANT: This function doesn't free the memory allocated to the element in the JsonBuffer. This behavior has been prefered to keep the JsonBuffer fast and small, which is a foundational principle of the library.

Signature
void removeAt(size_t index);
Arguments

index: the zero-based position of the element in the array.

Example
JsonArray& array = jsonBuffer.createArray();
array.add("A");
array.add("B");
array.add("C");
array.removeAt(1);
array.printTo(Serial);

will print the following string to the serial output:

["A","C"]

JsonArray::set()

Description

Sets the value at specified index.

Signatures
bool set(size_t index, bool value);
bool set(size_t index, float value, uint8_t decimals = 2);
bool set(size_t index, double value, uint8_t decimals = 2);
bool set(size_t index, signed char value);
bool set(size_t index, signed long value);
bool set(size_t index, signed int value);
bool set(size_t index, signed short value);
bool set(size_t index, unsigned char value);
bool set(size_t index, unsigned long value);
bool set(size_t index, unsigned int value);
bool set(size_t index, unsigned short value);
bool set(size_t index, const char *value);
bool set(size_t index, const String &value); // see Remarks
bool set(size_t index, JsonArray &array);
bool set(size_t index, JsonObject &object);
bool set(size_t index, const JsonVariant &value);
Arguments

index: position to set value in array.

value: the value to set in index of array.

Return value

true if allocation succeeded.

false if there was not enough space left in the JsonBuffer, this can only happen when value is a String.

Remarks

When you call JsonArray::set(size_t, const String&), a copy of the string is made, causing the JsonBuffer to grow. The memory allocated for the copy will only be freed when the whole JsonBuffer is discarded. To avoid this behavior, use JsonArray::set(size_t, const char*) instead.

Example
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.set(0,"hello");
array.add(1,3.14156, 4);
array.printTo(Serial); // [3.1416]

JsonArray::size()

Description

Returns the number of element in the array.

Signature
size_t size() const;
Return value

An unsigned integer containing the number of elements in the array.

Example
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add("world");
Serial.println(array.size()); // 2

JsonArray::success()

Description

Tells if the array is valid, which can be used:

  1. to check if the array was successfully parsed, or
  2. to check if the array was successfully allocated.
Signatures
bool success() const;
Return value

true if the array was successfully parsed/allocated. false if the parsing/allocation failed.

Examples

Example 1: parsing success:

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray("[1,2]");
Serial.println(array.success()); // true

Example 2: parsing failure:

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray("{1,2}");
Serial.println(array.success()); // false

Example 3: allocation success:

StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
Serial.println(array.success()); // true

Example 4: allocation failure:

StaticJsonBuffer<1> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
Serial.println(array.success()); // false

JsonBuffer (DynamicJsonBuffer and StaticJsonBuffer)

JsonBuffer is the entry point for using the library: it handle the memory management and calls the parser.

It implements a speed efficient memory pool and comes in two flavors:

  1. DynamicJsonBuffer which is allocated on the heap and grows automatically
  2. StaticJsonBuffer which is (most likely) allocated on the stack and has a fixed size.

JsonBuffer is optimized of fast allocation, but doesn't allow to free the allocated memory block. To free a JsonBuffer, you must discard the entire object.

This is the source of a lot of question, please read the FAQ in the wiki for clarifications.

JsonBuffer::createArray()

Description

Allocates an empty JsonArray.

Signature
JsonArray& createArray();
Return value

Returns a reference to the new JsonArray or JsonArray::invalid() if the allocation fails.

Example
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.createArray();
array.add("hello");
array.add("world");

JsonBuffer::createObject()

Description

Allocates an empty JsonObject.

Signature
JsonObject createObject();
Return value

Returns a reference to the new JsonObject or JsonObject::invalid() if the allocation fails.

Example
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";

JsonBuffer::parseArray()

Description

Allocates and populate a JsonArray from a JSON string.

By design, the parser needs to alter the string to insert null-terminators and replace escaped chars. If the JSON string is read-only, it will have to duplicate the input string, this consume more space in the JsonBuffer. Therefore, it's recommended to have a JSON input in a char[] or a char*.

Signatures
JsonArray& parseArray(char* json, uint8_t nestingLimit=10); // <- recommended
JsonArray& parseArray(const char* json, uint8_t nestingLimit=10);
JsonArray& parseArray(const String& json, uint8_t nestingLimit=10);
Arguments

json is the input string to be parsed.

nestingLimit specifies the maximum level of nesting allowed in the JSON string. If set to 0, only a flat array can be parsed. If set to 1, the object can contain nested arrays or objects but only 1 level deep. And bigger values will allow more level of nesting. The purpose of this feature is to prevent stack overflow that could lead to a security risk.

Return value

Returns a reference to the new JsonArray or JsonArray::invalid() if the allocation fails.

Example
char json[] = "[\"hello\",\"world\"]";
StaticJsonBuffer<200> jsonBuffer;
JsonArray& array = jsonBuffer.parseArray(json);
const char* hello = array[0];
const char* world = array[1];

JsonBuffer::parseObject()

Description

Allocates and populate a JsonObject from a JSON string.

By design, the parser needs to alter the string to insert null-terminators and replace escaped chars. If the JSON string is read-only, it will have to duplicate the input string, this consume more space in the JsonBuffer. Therefore, it's recommended to have a JSON input in a char[] or a char*.

Signatures
JsonObject& parseObject(char* json, uint8_t nestingLimit=10); // <- recommended
JsonObject& parseObject(const char* json, uint8_t nestingLimit=10);
JsonObject& parseObject(const String& json, uint8_t nestingLimit=10);
Arguments

json is the input string to be parsed.

nestingLimit specifies the maximum level of nesting allowed in the JSON string. If set to 0, only a flat object can be parsed. If set to 1, the object can contain nested objects or objects but only 1 level deep. And bigger values will allow more level of nesting. The purpose of this feature is to prevent stack overflow that could lead to a security risk.

Return value

Returns a reference to the new JsonObject or JsonObject::invalid() if the allocation fails.

Example
char json[] = "{\"hello\":\"world\"}";
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.parseObject(json);
const char* world = object["hello"];

JsonBuffer::strdup()

Description

Make a copy of the specified string.

Signatures
char* strdup(const char* str);
char* strdup(const String& str);
Arguments

str, the string to duplicate.

Return value

A newly allocate string, filled with a copy of str.

Example
StaticJsonBuffer<200> jsonBuffer;
char orig[16] = "hello";
char* dupl = jsonBuffer.strdup(orig);
strcpy(orig, "world");
Serial.println(dupl); // world
Serial.println(orig); // hello

JsonObject

Represents an object (ie an unordered set of name/value pairs) in a JSON object tree.

Constructor

The constructor is private, you cannot instanciate a JsonObject directly, you have to use a JsonBuffer.

Because the memory of a JsonObject is located a JsonBuffer, you always manipulate it through reference and you cannot copy it.

Example
StaticJsonBuffer<200> jsonBuffer;

// create an empty object
JsonObject& object1 = jsonBuffer.createObject();

// parse a JSON object
char json[] = "[1,2,3]";
JsonObject& object2 = jsonBuffer.parseObject(json);

JsonObject::begin() / JsonObject::end()

Description

Returns an iterator that can be use to get all key-value pairs in the object.

Signatures
JsonObject::iterator begin();
JsonObject::iterator end();
JsonObject::const_iterator begin() const;
JsonObject::const_iterator end() const;
Return value

A forward iterator pointing to a JsonPair, which itself contains two members key and value.

Example
char json[] = "{\"first\":\"hello\",\"second\":\"world\"}";
DynamicJsonBuffer jsonBuffer;
JsonObject& root = jsonBuffer.parseObject(json);

// using C++98 syntax:
for (JsonObject::iterator it=root.begin(); it!=root.end(); ++it) {
    Serial.println(it->key);
    Serial.println(it->value);
}

// using C++11 syntax:
for (auto kv : root) {
    Serial.println(kv.key);
    Serial.println(kv.value);
}

The code above would print:

first
hello
second
world

JsonObject::createNestedArray()

Description

Creates a JsonArray as a child of the current object.

Signatures
JsonArray& createNestedArray(const char* key) const;
JsonArray& createNestedArray(const String& key) const; // <- duplicates key
Arguments

key: the key of the array in the object, can be a const char* or a const String&

Remarks

When you add a value using a String for key, a copy of the string is made, causing the JsonBuffer to grow. The memory allocated for the copy will only be freed when the whole JsonBuffer is discarded. To avoid this behavior, use a const char* key instead.

Return value

A reference to the new JsonArray. You can check JsonArray::success() to verify that the allocatio succeeded.

Example
StaticJsonBuffer<256> jsonBuffer;
JsonObject& root = jsonBuffer.createObject();
root["status"] = "on";
JsonArray& levels = root.createNestedArray("levels");
levels.add(10);
levels.add(30);
root.prettyPrintTo(Serial);

will print

{
  "status": "on",
  "levels": [
    10,
    20
  ]
}

JsonObject::createNestedObject()

Description

Creates a JsonObject as a child of the current object.

Signature
JsonObject& createNestedObject(const char* key) const;
JsonObject& createNestedObject(const String& key) const; // <- duplicates key
Arguments

key: the key of the object in the object, can be a const char* or a const String&

Remarks

When you add a value using a String for key, a copy of the string is made, causing the JsonBuffer to grow. The memory allocated for the copy will only be freed when the whole JsonBuffer is discarded. To avoid this behavior, use a const char* key instead.

Return value

A reference to the new JsonObject. You can check JsonObject::success() to verify that the allocatio succeeded.

Example
StaticJsonBuffer<256> jsonBuffer;
JsonObject& root = jsonBuffer.createObject();
root["city"] = "Paris";
JsonObject& weather = root.createNestedObject("weather");
weather["temp"] = 14.2;
weather["cond"] = "cloudy";
root.prettyPrintTo(Serial);

will print

{
  "city": "Paris",
  "weather": {
    "temp": 14.20,
    "cond": "cloudy"
  }
}

JsonObject::get()

Description

Gets the value at the specified index.

Signature
// Non template version
JsonVariant     get                 (JsonObjectKey key) const;

// Template version
bool            get<bool>           (JsonObjectKey key) const;
const char*     get<const char*>    (JsonObjectKey key) const;
double          get<double>         (JsonObjectKey key) const;
float           get<float>          (JsonObjectKey key) const;
signed char     get<signed char>    (JsonObjectKey key) const;
signed int      get<signed int>     (JsonObjectKey key) const;
signed long     get<signed long>    (JsonObjectKey key) const;
signed short    get<signed short>   (JsonObjectKey key) const;
String          get<String>         (JsonObjectKey key) const;
unsigned char   get<unsigned char>  (JsonObjectKey key) const;
unsigned int    get<unsigned int>   (JsonObjectKey key) const;
unsigned long   get<unsigned long>  (JsonObjectKey key) const;
unsigned short  get<unsigned short> (JsonObjectKey key) const;
Arguments

key: the key of the value in the object, can be a const char* or a const String&

T: the type of the value

Return value

The value at the specified key. This can be a JsonVariant or a value of type T.

The template version of get() returns a value of the specified type. In case of an error (key out of range or incompatible type), the default value of the type T is returned.

Example
char json[] = "{\"pi\":3.14}";
StaticJsonBuffer<256> jsonBuffer;
JsonObject& object = jsonBuffer.parseObject(json);
float pi = object.get<float>("pi"); // template version of get()
const char* value2 = object.get<const char*>("toto"); // returns NULL

JsonObject::measureLength()

Description

Gets the length of string produced by JsonObject::printTo().

This can be very handy to fill the Content-Length of an HTTP request or response.

Return value

The number of characters in the JSON string that would be generated by JsonObject::printTo().

It doesn't include the zero-terminator.

Signature
size_t measureLength() const

JsonObject::measurePrettyLength()

Description

Gets the length of string produced by JsonObject::prettyPrintTo().

Return value

The number of characters in the JSON string that would be generated by JsonObject::prettyPrintTo().

It doesn't include the zero-terminator.

Signature
size_t measurePrettyLength() const

JsonObject::operator[]

Description

A shortcut for JsonObject::get() and JsonObject::set(), with a map-like syntax.

Signatures
JsonVariant& operator[](const char* key);
JsonVariant& operator[](const String& key);
const JsonVariant& operator[](const cahr* key) const;
const JsonVariant& operator[](const String& key) const;
Arguments

key: the key that the value will be associated to.

Return value

A reference to the JsonVariant in the object.

Remarks

When you add a value using a String for key, a copy of the string is made, causing the JsonBuffer to grow. The memory allocated for the copy will only be freed when the whole JsonBuffer is discarded. To avoid this behavior, use a const char* key instead.

Example
JsonObject& object = jsonBuffer::createObject();
object["hello"] = "world";
const char* world = object["hello"];

JsonObject::prettyPrintTo()

Description

Serialize the object to an indented JSON string.

This will create a "prettified" JSON, if you want a compact JSON without space or line break, use JsonObject::print()

Signatures
size_t prettyPrintTo(char* buffer, size_t size) const;
size_t prettyPrintTo(Print &) const;
size_t prettyPrintTo(String &) const;
Arguments

The destination of the JSON string.

Can be either:

  • a buffer with specified size (this includes the zero-terminator)
  • an implementation of Print (like Serial, EthernetClient...)
  • a String
Return value

The number of bytes written

Example
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";
object.prettyPrintTo(Serial);

will write the following string to the serial output:

{
  "hello": "world"
}

JsonObject::printTo()

Description

Serialize the object to a JSON string.

This will create a compact JSON, if you want a pretty JSON with spaces and line breaks, use JsonObject::prettyPrint()

Signatures
size_t printTo(char* buffer, size_t size) const;
size_t printTo(Print &) const;
size_t printTo(String &) const;
Arguments

The destination of the JSON string.

Can be either:

  • a buffer with specified size (this includes the zero-terminator)
  • an implementation of Print (like Serial, EthernetClient...)
  • a String
Return value

The number of bytes written

Example
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";
object.printTo(Serial);

will write the following string to the serial output:

{"hello":"world"}

JsonObject::remove()

Description

Removes the element at the specified key.

IMPORTANT: This function doesn't free the memory allocated to the element in the JsonBuffer. This behavior has been prefered to keep the JsonBuffer fast and small, which is a foundational principle of the library.

Signatures
void remove(const char* key);
void remove(const String& key);
Arguments

key: the key to remove from the object.

Example
JsonObject& object = jsonBuffer.createObject();
object["A"] = 1;
object["B"] = 2;
object["C"] = 3;
object.remove("B");
object.printTo(Serial);

will print the following string to the serial output:

{"A":1,"C":3}

JsonObject::set()

Description

Sets the value at specified key.

Signatures
bool set(const char* key, bool value);
bool set(const char* key, float value, uint8_t decimals = 2);
bool set(const char* key, double value, uint8_t decimals = 2);
bool set(const char* key, signed char value);
bool set(const char* key, signed long value);
bool set(const char* key, signed int value);
bool set(const char* key, signed short value);
bool set(const char* key, unsigned char value);
bool set(const char* key, unsigned long value);
bool set(const char* key, unsigned int value);
bool set(const char* key, unsigned short value);
bool set(const char* key, const char *value);
bool set(const char* key, const String &value);                  // see Remarks
bool set(const char* key, JsonArray &array);
bool set(const char* key, JsonObject &object);
bool set(const char* key, const JsonVariant &value);
bool set(const String& key, bool value);                         // see Remarks
bool set(const String& key, float value, uint8_t decimals = 2);  // see Remarks
bool set(const String& key, double value, uint8_t decimals = 2); // see Remarks
bool set(const String& key, signed char value);                  // see Remarks
bool set(const String& key, signed long value);                  // see Remarks
bool set(const String& key, signed int value);                   // see Remarks
bool set(const String& key, signed short value);                 // see Remarks
bool set(const String& key, unsigned char value);                // see Remarks
bool set(const String& key, unsigned long value);                // see Remarks
bool set(const String& key, unsigned int value);                 // see Remarks
bool set(const String& key, unsigned short value);               // see Remarks
bool set(const String& key, const char *value);                  // see Remarks
bool set(const String& key, const String &value);                // see Remarks twice
bool set(const String& key, JsonArray &array);                   // see Remarks
bool set(const String& key, JsonObject &object);                 // see Remarks
bool set(const String& key, const JsonVariant &value);           // see Remarks
Arguments

key: the key to attach the value to.

value: the value to attach to the key.

Return value

true if allocation succeeded.

false if there was not enough space left in the JsonBuffer.

Remarks

When you use a String, a copy of the string is made, causing the JsonBuffer to grow. The memory allocated for the copy will only be freed when the whole JsonBuffer is discarded. To avoid this behavior, use const char* keys and values instead.

Example
StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
object.set("hello","world");
object.printTo(Serial);

will print the following string to the serial output:

{"hello":"world"}

JsonObject::size()

Description

Returns the number of key/value pairs in the object.

Signature
size_t size() const;
Return value

An unsigned integer containing the number of key/value pairs in the object.

Example
JsonObject& object = jsonBuffer.createObject();
object["hello"] = "world";
Serial.println(object.size()); // 1

JsonObject::success()

Description

Tells if the object is valid, which can be used:

  1. to check if the object was successfully parsed, or
  2. to check if the object was successfully allocated.
Signatures
bool success() const;
Return value

true if the object was successfully parsed/allocated. false if the parsing/allocation failed.

Examples

Example 1: parsing success:

StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.parseObject("{\"hello\":\"world\"}");
Serial.println(object.success()); // true

Example 2: parsing failure:

StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.parseObject("[\"hello\",\"world\"]");
Serial.println(object.success()); // false

Example 3: allocation success:

StaticJsonBuffer<200> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
Serial.println(object.success()); // true

Example 4: allocation failure:

StaticJsonBuffer<1> jsonBuffer;
JsonObject& object = jsonBuffer.createObject();
Serial.println(object.success()); // false

JsonVariant

A variable that can hold different type of values:

  • a boolean
  • a char, short, int or a long (signed or unsigned)
  • a string (const char*)
  • a reference to a JsonArray or JsonObject

A JsonVariant can be any of theses types at a time, but can only hold one value. Its type can change at run time.

JsonVariant::as()

Description

Get the value of the specified type.

Signatures
bool               as<bool>() const;

float              as<float>() const;
double             as<double>() const;

signed char        as<signed char>() const;
unsigned char      as<unsigned char>() const;
signed int         as<signed int>() const;
unsigned int       as<unsigned int>() const;
signed short       as<signed short>() const;
unsigned short     as<unsigned short>() const;
signed long        as<signed long>() const;
unsigned long      as<unsigned long>() const;
unsigned long long as<unsigned long long>() const;   // <- may require ARDUINOJSON_USE_LONG_LONG
signed long long   as<signed long long>() const;     // <- may require ARDUINOJSON_USE_LONG_LONG
signed __int64     as<signed __int64>() const;       // <- may require ARDUINOJSON_USE_INT64
unsigned __int64   as<unsigned __int64>() const;     // <- may require ARDUINOJSON_USE_INT64

const char*        as<char*>() const;
const char*        as<const char*>() const;
String             as<String>() const;               // <- causes duplication of the string

JsonArray&         as<JsonArray>() const;
JsonArray&         as<JsonArray&>() const;
JsonArray&         as<const JsonArray&>() const;
JsonObject&        as<JsonObject>() const;
JsonObject&        as<JsonObject&>() const;
JsonObject&        as<const JsonObject&>() const;
Return value

The value of the specified type or a default value if the JsonVariant is not compatible with the specified type.

The default value is:

  • 0 for numerical types
  • NULL for const char*
  • JsonArray::invalid() for JsonArray&
  • JsonObject::invalid() for JsonObject&
Example
JsonVariant variant = 42;
int i = variant.as<int>(); // <- i == 42
double d = variant.as<double>(); // <- d == 42.0
const char* s = variant.as<char*>(); // <- s == NULL

JsonVariant::is()

Description

Test if the variant is currently holding a value of the specified type.

Signatures
bool is<bool>() const;

bool is<float>() const;
bool is<double>() const;

bool is<signed char>() const;
bool is<unsigned char>() const;
bool is<signed int>() const;
bool is<unsigned int>() const;
bool is<signed short>() const;
bool is<unsigned short>() const;
bool is<signed long>() const;
bool is<unsigned long>() const;
bool is<unsigned long long>() const;   // <- may require ARDUINOJSON_USE_LONG_LONG
bool is<signed long long>() const;     // <- may require ARDUINOJSON_USE_LONG_LONG
bool is<signed __int64>() const;       // <- may require ARDUINOJSON_USE_INT64
bool is<unsigned __int64>() const;     // <- may require ARDUINOJSON_USE_INT64

bool is<char*>() const;
bool is<const char*>() const;

bool is<JsonArray>() const;
bool is<JsonArray&>() const;
bool is<const JsonArray&>() const;
bool is<JsonObject>() const;
bool is<JsonObject&>() const;
bool is<const JsonObject&>() const;
Return value
  • true if the variant is currently holding a value of the specified type,
  • false if not
Example
JsonVariant variant = 42;
bool i = variant.is<int>(); // <- i == true
bool d = variant.is<double>(); // <- d == false
bool s = variant.is<char*>(); // <- s == false

This wiki probably contains a few mistakes, please help other users by fixing it 😙

Add a custom sidebar

Clone this wiki locally