Added JsonVariant::as() and ::is()

API-Reference.md

@@ -34,7 +34,7 @@ JsonArray& array2 = jsonBuffer.parseArray(json);
 
 ##### Description
 
-Adds a value to end of the array.
+Adds a value to the end of the array.
 
 ##### Signatures
 
@@ -130,7 +130,7 @@ unsigned short  get<unsigned short> (size_t index) const;
 The value at the specified index. This can be a `JsonVariant` or a value of type T.
 
 The template version of `get()` returns a value of the specified type.
-In case of an error (index out of range or incompatible type), the default value of the type `T` is returned.
+In the case of an error (index out of range or incompatible type), the default value of the type `T` is returned.
 
 ##### Example
 
@@ -172,18 +172,18 @@ size_t measureLength() const
 
 Gets the length of string produced by `JsonArray::prettyPrintTo()`.
 
-##### Return value
-
-The number of characters in the JSON string that would be generated by `JsonArray::prettyPrintTo()`.
-
-It doesn't include the zero-terminator.
-
 ##### Signature
 
 ```c++
 size_t measurePrettyLength() const
 ```
 
+##### Return value
+
+The number of characters in the JSON string that would be generated by `JsonArray::prettyPrintTo()`.
+
+It doesn't include the zero-terminator.
+
 
 
 ### JsonArray::operator[]
@@ -1183,40 +1183,129 @@ Serial.println(object.success()); // false
 ```
 
 
-:construction:
-
-:construction: Below this line, the writing is still in progress...
-
-:construction:
 
 
 ## JsonVariant
-A variant that can be a any value serializable to a JSON value.
- It can be set to:
- - a boolean
- - a char, short, int or a long (signed or unsigned)
- - a string (const char*)
- - a reference to a JsonArray or JsonObject
 
-#### JsonVariant::get<T>()
+A variable that can hold different type of values:
+
+* a boolean
+* a char, short, int or a long (signed or unsigned)
+* a string (const char*)
+* a reference to a JsonArray or JsonObject
+
+A `JsonVariant` can be any of theses types at a time, but can only hold one value.
+Its type can change at run time.
+
+
+### JsonVariant::as()
+
 ##### Description
+
+Get the value of the specified type.
+
 ##### Signatures
-##### Arguments
+
+```c++
+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;
+const char*        as<const char*>() const;
+String             as<String>() const;               // <- causes duplication of the string
+
+JsonArray&         as<JsonArray>() const;
+JsonArray&         as<JsonArray&>() const;
+JsonArray&         as<const JsonArray&>() const;
+JsonObject&        as<JsonObject>() const;
+JsonObject&        as<JsonObject&>() const;
+JsonObject&        as<const JsonObject&>() const;
+```
+
 ##### Return value
+
+The value of the specified type or a default value if the `JsonVariant` is not compatible with the specified type.
+
+The default value is:
+
+* `0` for numerical types
+* `NULL` for `const char*`
+* `JsonArray::invalid()` for `JsonArray&`
+* `JsonObject::invalid()` for `JsonObject&`
+
 ##### Example
 
-#### JsonVariant::is<T>()
+```c++
+JsonVariant variant = 42;
+int i = variant.as<int>(); // <- i == 42
+double d = variant.as<double>(); // <- d == 42.0
+const char* s = variant.as<char*>(); // <- s == NULL
+```
+
+
+### JsonVariant::is()
+
 ##### Description
+
+Test if the variant is currently holding a value of the specified type.
+
 ##### Signatures
-##### Arguments
+
+```c++
+bool is<bool>() const;
+
+bool is<float>() const;
+bool is<double>() const;
+
+bool is<signed char>() const;
+bool is<unsigned char>() const;
+bool is<signed int>() const;
+bool is<unsigned int>() const;
+bool is<signed short>() const;
+bool is<unsigned short>() const;
+bool is<signed long>() const;
+bool is<unsigned long>() const;
+bool is<unsigned long long>() const;   // <- may require ARDUINOJSON_USE_LONG_LONG
+bool is<signed long long>() const;     // <- may require ARDUINOJSON_USE_LONG_LONG
+bool is<signed __int64>() const;       // <- may require ARDUINOJSON_USE_INT64
+bool is<unsigned __int64>() const;     // <- may require ARDUINOJSON_USE_INT64
+
+bool is<char*>() const;
+bool is<const char*>() const;
+
+bool is<JsonArray>() const;
+bool is<JsonArray&>() const;
+bool is<const JsonArray&>() const;
+bool is<JsonObject>() const;
+bool is<JsonObject&>() const;
+bool is<const JsonObject&>() const;
+```
+
 ##### Return value
+
+* `true` if the variant is currently holding a value of the specified type,
+* `false` if not
+
 ##### Example
 
-#### JsonVariant::set<T>()
+```c++
-##### Description
+JsonVariant variant = 42;
-##### Signatures
+bool i = variant.is<int>(); // <- i == true
-##### Arguments
+bool d = variant.is<double>(); // <- d == false
-##### Return value
+bool s = variant.is<char*>(); // <- s == false
-##### Example
+```
-
-#### Implicit conversions