JsonVariant

Description

JsonVariant is a reference to a value in a JsonDocument. It supports all types allowed by JSON:

boolean
integer
floating point
string
array
object

JsonVariant doesn’t own the value: it only points to it. The value belongs to the JsonDocument.

Reference semantics

JsonVariant points to a value in a JsonDocument, giving it reference semantics. Every modification you make through the JsonVariant is reflected in the JsonDocument. When you copy a JsonVariant, you only copy the reference, not the value itself.

Don’t pass a JsonVariant by reference or pointer because it would be a reference to a reference, which is very confusing and can lead to dangling references if you reassign the JsonVariant.

- void setHostname(JsonVariant& hostname) {
+ void setHostname(JsonArray hostname) {
    JsonDocument doc;
    deserializeJson(doc, configFile);
-   hostname = doc["hostname"];
+   hostname.set(doc["hostname"]);
  }

Avoid returning a JsonArray from a function, because it will likely point to a destructed JsonDocument. Consider returning a JsonDocument instead.

- JsonObject getWifiConfig() {
+ JsonDocument getWifiConfig() {
    JsonDocument doc;
    deserializeJson(doc, configFile);
    return doc["wifi"];
  }

Constness

You’ll see that most member functions of JsonVariant are const. These methods do not modify the instance, but they may alter the value pointed by the JsonVariant.

As we said, a JsonVariant is a reference; the const-ness of the member functions refers to the reference object, not to the value.

ArduinoJson also supports a read-only reference type named JsonVariantConst. It’s similar to JsonVariant, except it doesn’t allow modifying the value.

Example

Create a variant and serialize it

// create the JsonDocument
JsonDocument doc;

// create a variant
JsonVariant variant = doc.to<JsonVariant>();
variant.set(42);

// serialize the object and send the result to Serial
serializeJson(doc, Serial);

Deserialize a variant

// deserialize the value
JsonDocument doc;
deserializeJson(doc, "42");

// extract the data
JsonVariant variant = doc.as<JsonVariant>();
int value = variant.as<int>();

Member functions

JsonVariant also supports the comparison operators ==, !=, <, <=, >, and >=.