JSON

JSONValue

// EXAMPLE
SerialLogHandler logHandler;

void setup() {
    Particle.subscribe("jsonTest", subscriptionHandler);
}

void subscriptionHandler(const char *event, const char *data) {

    JSONValue outerObj = JSONValue::parseCopy(data);

    JSONObjectIterator iter(outerObj);
    while(iter.next()) {
        Log.info("key=%s value=%s", 
          (const char *) iter.name(), 
          (const char *) iter.value().toString());
    }
}

// TEST EVENT
$ particle publish jsonTest '{"a":123,"b":"testing"}'

// LOG
0000068831 [app] INFO: key=a value=123
0000068831 [app] INFO: key=b value=testing

The JSONValue object is a container that holds one of:

• A value (bool, int, double, string, etc.)
• A JSON object
• A JSON array

If you have a buffer of data containing a JSON object or array, you pass it to one of the static parse() methods.

In this example, parseCopy() is used because a subscription handler data must not be modified (it is const). It's a static method, so you always use it like JSONValue::parseCopy(data).

JSONValue::isNull()

// PROTOTYPE
bool isNull() const;

Returns true if the value is the JSON null value, like {"value":null}. This is different than just being 0 or false!

JSONValue::isBool()

// PROTOTYPE
bool isBool() const;

Returns true if the value is the JSON boolean value, like {"value":true} or {"value":false}. This is different than just being 0 or 1!

JSONValue::isNumber()

// PROTOTYPE
bool isNumber() const;

Returns true if the value is the JSON number value, either int or double, like {"value":123} or {"value":-10.5}.

JSONValue::isString()

// PROTOTYPE
bool isString() const;

Returns true if the value is the JSON string value, like {"value":"testing"}.

JSONValue::isArray()

// PROTOTYPE
bool isArray() const;

Returns true if the value is the JSON array value, like [1,2,3].

JSONValue::isObject()

// PROTOTYPE
bool isObject() const;

Returns true if the value is a JSON object, like {"a":123,"b":"testing"}.

JSONValue::type()

// PROTOTYPE
JSONType type() const;

// CONSTANTS
enum JSONType {
    JSON_TYPE_INVALID,
    JSON_TYPE_NULL,
    JSON_TYPE_BOOL,
    JSON_TYPE_NUMBER,
    JSON_TYPE_STRING,
    JSON_TYPE_ARRAY,
    JSON_TYPE_OBJECT
};

Instead of using isNumber() for example, you can use type() and check it against JSON_TYPE_NUMBER.

JSONValue::toBool()

// PROTOTYPE
bool toBool() const;

Converts the value to a boolean. Some type conversion is done if necessary:

JSONValue::toInt()

// PROTOTYPE
int toInt() const;

Converts the value to a signed integer (32-bit). Some type conversion is done if necessary:

strltol parses:

• An optional sign character (+ or -)
• An optional prefix indicating octal ("0") or hexadecimal ("0x" or "0X")
• A sequence of digits (octal, decimal, or hexadecimal)

Beware of passing decimal values with leading zeros as they will be interpreted as octal when using toInt()!

JSONValue::toDouble()

// PROTOTYPE
double toDouble() const;

Converts the value to a floating point double (64-bit). Some type conversion is done if necessary:

strtod supports decimal numbers, and also scientific notation (using e as in 1.5e4).

JSONValue::toString()

// PROTOTYPE
JSONString toString() const;

Converts a value to a JSONString object. This can only be used for primitive types (bool, int, number, string, null). It cannot be used to serialize an array or object.

Since the underlying JSON is always a string, this really just returns a reference to the underlying representation.

A JSONString is only a reference to the underlying data, and does not copy it.

JSONValue::isValid()

// PROTOTYPE
bool isValid() const;

Returns true if the JSONValue is valid. If you parse an invalid object, isValid() will be false.