From d94bcbf2499f2fcb44b10de0f6fde03ba9ae2721 Mon Sep 17 00:00:00 2001 From: Benoit Blanchon Date: Thu, 6 Nov 2014 16:58:24 +0100 Subject: [PATCH] Added comments --- include/ArduinoJson/JsonObject.hpp | 1 + include/ArduinoJson/JsonPair.hpp | 1 + include/ArduinoJson/JsonVariant.hpp | 120 +++++++++++++++++++++------- 3 files changed, 94 insertions(+), 28 deletions(-) diff --git a/include/ArduinoJson/JsonObject.hpp b/include/ArduinoJson/JsonObject.hpp index 7bc96059..a6a6d3d2 100644 --- a/include/ArduinoJson/JsonObject.hpp +++ b/include/ArduinoJson/JsonObject.hpp @@ -86,6 +86,7 @@ class JsonObject : public Internals::JsonPrintable, // This is used when memory allocation or JSON parsing fail. static JsonObject &invalid() { return _invalid; } + // Serialize the object to the specified JsonWriter template void writeTo(T &writer) const; diff --git a/include/ArduinoJson/JsonPair.hpp b/include/ArduinoJson/JsonPair.hpp index cf0b86fb..8da3f54b 100644 --- a/include/ArduinoJson/JsonPair.hpp +++ b/include/ArduinoJson/JsonPair.hpp @@ -10,6 +10,7 @@ namespace ArduinoJson { +// A key value pair for JsonObject. struct JsonPair { const char* key; JsonVariant value; diff --git a/include/ArduinoJson/JsonVariant.hpp b/include/ArduinoJson/JsonVariant.hpp index e06feedb..f59a3ab9 100644 --- a/include/ArduinoJson/JsonVariant.hpp +++ b/include/ArduinoJson/JsonVariant.hpp @@ -15,106 +15,170 @@ namespace ArduinoJson { +// Forward declarations. class JsonArray; class JsonObject; +// 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 class JsonVariant : public Internals::JsonPrintable { public: + // Creates an uninitialized JsonVariant JsonVariant() : _type(Internals::JSON_UNDEFINED) {} + // Initializes a JsonVariant with the specified value. template explicit JsonVariant(T value) { set(value); } + // Tells weither the variant is valid. + bool success() { + return _type != Internals::JSON_INVALID && + _type != Internals::JSON_UNDEFINED; + } + + // Sets the variant to a boolean value. + // It will be serialized as "true" or "false" in JSON. void set(bool value); + + // Sets the variant to a floating point value. + // The second argument specifies the number of decimal digits to write in + // the JSON string. void set(double value, uint8_t decimals = 2); + + // Sets the variant to be an integer value. + void set(signed long value); void set(signed char value) { set(static_cast(value)); } void set(signed int value) { set(static_cast(value)); } - void set(signed long value); void set(signed short value) { set(static_cast(value)); } void set(unsigned char value) { set(static_cast(value)); } void set(unsigned int value) { set(static_cast(value)); } void set(unsigned long value) { set(static_cast(value)); } void set(unsigned short value) { set(static_cast(value)); } + + // Sets the variant to be a string. void set(const char *value); + + // Sets the variant to be a reference to an array. void set(JsonArray &array); + + // Sets the variant to be a reference to an object. void set(JsonObject &object); + // Sets the variant to the specified value. template JsonVariant &operator=(T value) { set(value); return *this; } + // Sets the variant to be a reference to an array. JsonVariant &operator=(JsonArray &array) { set(array); return *this; } + // Sets the variant to be a reference to an object. JsonVariant &operator=(JsonObject &object) { set(object); return *this; } + // Gets the variant as a boolean value. + // Returns false if the variant is not a boolean value. operator bool() const; + + // Gets the variant as a floating-point value. + // Returns 0.0 if the variant is not a floating-point value operator double() const; operator float() const { return static_cast(as()); } - operator signed char() const { return static_cast(as()); } - operator signed int() const { return static_cast(as()); } + + // Gets the variant as an integer value. + // Returns 0 if the variant is not an integer value. operator signed long() const; - operator signed short() const { - return static_cast(as()); - } - operator unsigned char() const { - return static_cast(as()); - } - operator unsigned int() const { - return static_cast(as()); - } - operator unsigned long() const { - return static_cast(as()); - } - operator unsigned short() const { - return static_cast(as()); - } + operator signed char() const { return cast_long_to(); } + operator signed int() const { return cast_long_to(); } + operator signed short() const { return cast_long_to(); } + operator unsigned char() const { return cast_long_to(); } + operator unsigned int() const { return cast_long_to(); } + operator unsigned long() const { return cast_long_to(); } + operator unsigned short() const { return cast_long_to(); } + + // Gets the variant as a string. + // Returns NULL if variant is not a string. operator const char *() const; + const char *asString() const { return as(); } + + // Gets the variant as an array. + // Returns a reference to the JsonArray or JsonArray::invalid() if the variant + // is not an array. operator JsonArray &() const; + JsonArray &asArray() const { return as(); } + + // Gets the variant as an object. + // Returns a reference to the JsonObject or JsonObject::invalid() if the + // variant is not an object. operator JsonObject &() const; + JsonObject &asObject() const { return as(); } - const char *asString() const { return this->as(); } - JsonArray &asArray() const { return this->as(); } - JsonObject &asObject() const { return this->as(); } - + // Get the variant as the specified type. + // See cast operators for details. template T as() const { return static_cast(*this); } + // Tells weither the variant has the specified type. + // Returns true if the variant has type type T, false otherwise. template bool is() const { return false; } + // Returns an invalid variant. + // This is meant to replace a NULL pointer. static JsonVariant &invalid() { return _invalid; } - bool success() { - return _type != Internals::JSON_INVALID && - _type != Internals::JSON_UNDEFINED; - } - + // Serialize the variant to a JsonWriter template void writeTo(T &writer) const; + // Mimics an array or an object. + // Returns the size of the array or object if the variant has that type. + // Returns 0 if the variant is neither an array nor an object size_t size() const; + + // Mimics an array. + // Returns the element at specified index if the variant is an array. + // Returns JsonVariant::invalid() if the variant is not an array. JsonVariant &operator[](int index); + + // Mimics an object. + // Returns the value associated with the specified key if the variant is an + // object. + // Return JsonVariant::invalid() if the variant is not an object. JsonVariant &operator[](const char *key); private: - explicit JsonVariant(Internals::JsonVariantType type) : _type(type) {} + // Helper for interger cast operators + template + T cast_long_to() const { + return static_cast(as()); + } + // The current type of the variant Internals::JsonVariantType _type; + + // The various alternatives for the value of the variant. Internals::JsonVariantContent _content; + + // The instance returned by JsonVariant::invalid() static JsonVariant _invalid; };