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
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; // ⛔ removed in 6.20
const char* as<const char*>() const;
String as<String>() const;
std::string as<std::string>() const;
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>() (added in 6.15.2)
T as<T>() const; // 🆕 calls user-defined converter (added in 6.18.0)
Return value
JsonVariant::as<T>()
returns the value pointed by the JsonVariant
casted to the specified type.
This function returns a default value if the cast is not possible. The default value is:
0
for numerical typesNULL
forconst char*
- A null reference for
JsonArray
andJsonObject
.
If you want to change the default value, you need to use JsonVariant::operator|
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
.
This feature was added in ArduinoJson 6.10.0
User-defined types 🆕
JsonVariant::as<T>()
supports user-defined types by calling convertFromJson()
.
For example, to support tm
, you must define:
void convertFromJson(JsonVariantConst src, tm& dst) {
strptime(src.as<const char*>(), "%FT%TZ", &dst);
}
This feature was added in ArduinoJson 6.18.0, see article for details.
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 aJsonObject
pointing to this object.JsonVariant::to<JsonObject>()
:- creates a new object in the
JsonDocument
, - makes the
JsonVariant
point to the new object, - returns a
JsonObject
pointing to it.
- creates a new object in the
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
StaticJsonDocument<256> 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