JsonDocument::as<T>()

Description

Casts JsonDocument to the specified type.

Unlike JsonDocument::to<T>(), this function doesn’t change the content of the JsonDocument.

Signature

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<char*>() const;                // ⛔ removed in 6.20
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>();
JsonObject         as<JsonObject>();
JsonVariant        as<JsonVariant>();

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

This function returns a reference to the root of the JsonDocument.

If the actual type of the root doesn’t match the requested type, this function returns a null reference. For example, suppose the JsonDocument is an array, if you call JsonDocument::as<JsonObject>(), it will return a null JsonObject.

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

JsonDocument::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

JsonDocument::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

JsonDocument::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.

Example

DynamicJsonDocument doc(1024);
deserializeJson(doc, "{\"key\":\"value\")");

// get the JsonObject in the JsonDocument
JsonObject root = doc.as<JsonObject>();

// get the value in the JsonObject
const char* value = root["key"];

See also