JsonVariant::as<T>()

Description

JsonVariant::as<T>() casts the value pointed by the JsonVariant to the specified type.

Unlike JsonVariant::to<T>(), this function doesn’t modify the value pointed by the JsonVariant.

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

const char*        as<const char*>() const;
String             as<String>() const;               // ⚠️ behavior differs slightly (see below)
std::string        as<std::string>() const;          // ⚠️ behavior differs slightly (see below)

JsonArray          as<JsonArray>() const;
JsonObject         as<JsonObject>() const;
JsonVariant        as<JsonVariant>() const;

JsonArrayConst     as<JsonArrayConst>() const;
JsonObjectConst    as<JsonObjectConst>() const;
JsonVariantConst   as<JsonVariantConst>() const;

TEnum              as<TEnum>() const;  // alias of as<int>()
T                  as<T>() const;      // calls user-defined converter

Return value

JsonVariant::as<T>() returns the value pointed by the JsonVariant cast to the specified type.

This function returns a default value if the cast is not possible. The default value is:

0 for numerical types
NULL for const char*
A null reference for JsonArray and JsonObject.

To change the default value, you need to use JsonVariant::operator| instead.

`as<String>()` and `as<std::string>()`

JsonVariant::as<T>() behaves slightly differently when T is a string object:

if the value is a string, it returns this string (nothing special here);
otherwise, it returns the JSON representation.

Here are a few examples:

Value	`as<String>()`
`"hello world"`	`"hello world"`
`true`	`"true"`
`false`	`"false"`
`42`	`"42"`
`[1,2,3]`	`"[1,2,3]"`
`{"key":"value"}`	`"{\"key\":\"value\"}"`
`null`	`"null"`

If you don’t want this behavior, use as<const char*>() instead.

Integer overflows

JsonVariant::as<T>() is aware of integer overflows and only returns a value if it can fit in the specified type.

For example, if the value contains 512, as<char>() returns 0, but as<int>() returns 512.

User-defined types

JsonVariant::as<T>() supports user-defined types by calling convertFromJson(). For example, to support tm, you must define the following function:

void convertFromJson(JsonVariantConst src, tm& dst) {
  strptime(src.as<const char*>(), "%FT%TZ", &dst);
}

For more information about custom converters, please read the article dedicated to ArduinoJson 6.18.0.

`as<T>()` vs `to<T>()`

JsonVariant::as<T>() and JsonVariant::to<T>() look similar but are very different: the former reads the value, whereas the latter changes the reference.

Suppose the JsonVariant refers to an object:

JsonVariant::as<JsonObject>() returns a JsonObject pointing to this object.
JsonVariant::to<JsonObject>():
1. creates a new object in the JsonDocument,
2. makes the JsonVariant point to the new object,
3. returns a JsonObject pointing to it.

JsonVariant::to<T>() allows creating an empty object or an empty array, and it’s probably its only legitimate use. Calling JsonVariant::to<T>() with a T other than JsonArray or JsonObject works but has no practical use.

JsonVariant::as<T>(), on the other hand, allows solving situations where implicit casts don’t work; for example, when you call a function with several matching overloads (like Serial::print()) or when you use type deduction with the auto keyword (see example below).

Remark that JsonVariantConst, which is a read-only version of JsonVariant, supports as<T>() but not to<T>().

Example

JsonDocument doc;
deserializeJson(doc, "{\"answer\":42}");

JsonVariant answer = doc["answer"];
auto i = answer.as<int>();         // i == 42
auto d = answer.as<double>();      // d == 42.0
auto s = answer.as<const char*>(); // s == NULL