From 086e99efb4896108dcab6b94dd3619549dd75a4d Mon Sep 17 00:00:00 2001 From: Benoit Blanchon Date: Thu, 6 Nov 2014 16:29:29 +0100 Subject: [PATCH] Added comment --- include/ArduinoJson/JsonArray.hpp | 27 +++++++++------- include/ArduinoJson/JsonObject.hpp | 50 +++++++++++++++++++++++++++--- src/Internals/JsonParser.cpp | 2 +- 3 files changed, 62 insertions(+), 17 deletions(-) diff --git a/include/ArduinoJson/JsonArray.hpp b/include/ArduinoJson/JsonArray.hpp index 7765d9c5..e10b9649 100644 --- a/include/ArduinoJson/JsonArray.hpp +++ b/include/ArduinoJson/JsonArray.hpp @@ -18,29 +18,32 @@ namespace ArduinoJson { -// Forward declaration +// Forward declarations class JsonObject; class JsonBuffer; // An array of JsonVariant. -// Can be converted to a JSON string via JsonArray::printTo(). -// Can be extracted from a JSON string JsonBuffer::parseArray(). +// +// The constructor is private, instances must be created via +// JsonBuffer::createArray() or JsonBuffer::parseArray(). +// A JsonArray can be serialized to a JSON string via JsonArray::printTo(). +// It can also be deserialized from a JSON string via JsonBuffer::parseArray(). class JsonArray : public Internals::JsonPrintable, public Internals::ReferenceType, public Internals::List { - // JsonBuffer is a friend because it needs to call the private constructor of - // JsonArray from createArray() and parseArray(). + // JsonBuffer is a friend because it needs to call the private constructor. friend class JsonBuffer; public: - // Returns the JsonVariant at the specified index (synonym for at()) - value_type &operator[](int index) const { return at(index); } - // Returns the JsonVariant at the specified index (synonym for operator[]) - value_type &at(int index) const; + JsonVariant &at(int index) const; + + // Returns the JsonVariant at the specified index (synonym for at()) + JsonVariant &operator[](int index) const { return at(index); } // Adds an uninitialized JsonVariant at the end of the array. - value_type &add(); + // Return a reference or JsonVariant::invalid() if allocation fails. + JsonVariant &add(); // Adds the specified value at the end of the array. template @@ -67,16 +70,16 @@ class JsonArray : public Internals::JsonPrintable, JsonObject &createNestedObject(); // Returns a reference an invalid JsonArray. + // This object is meant to replace a NULL pointer. // This is used when memory allocation or JSON parsing fail. static JsonArray &invalid() { return _invalid; } - // Writes the array to a JsonWriter. + // Serialize the array to the specified JsonWriter. template void writeTo(T &writer) const; private: // Create an empty JsonArray attached to the specified JsonBuffer. - // Constructor is private: instance must be created via a JsonBuffer explicit JsonArray(JsonBuffer *buffer) : List(buffer) {} // The instance returned by JsonArray::invalid() diff --git a/include/ArduinoJson/JsonObject.hpp b/include/ArduinoJson/JsonObject.hpp index a374d3a5..7bc96059 100644 --- a/include/ArduinoJson/JsonObject.hpp +++ b/include/ArduinoJson/JsonObject.hpp @@ -11,54 +11,96 @@ #include "Internals/ReferenceType.hpp" #include "JsonPair.hpp" +// Returns the size (in bytes) of an object with n elements. +// Can be very handy to determine the size of a StaticJsonBuffer. #define JSON_OBJECT_SIZE(NUMBER_OF_ELEMENTS) \ (sizeof(JsonObject) + (NUMBER_OF_ELEMENTS) * sizeof(JsonObject::node_type)) namespace ArduinoJson { +// Forward declarations class JsonArray; class JsonBuffer; +// A dictionary of JsonVariant indexed by string (char*) +// +// The constructor is private, instances must be created via +// JsonBuffer::createObject() or JsonBuffer::parseObject(). +// A JsonObject can be serialized to a JSON string via JsonObject::printTo(). +// It can also be deserialized from a JSON string via JsonBuffer::parseObject(). class JsonObject : public Internals::JsonPrintable, public Internals::ReferenceType, public Internals::List { + // JsonBuffer is a friend because it needs to call the private constructor. friend class JsonBuffer; public: typedef const char *key_type; typedef JsonPair value_type; + // Gets the JsonVariant associated with the specified key. + // Returns a reference or JsonVariant::invalid() if not found. JsonVariant &at(key_type key); + + // Gets the JsonVariant associated with the specified key. + // Returns a constant reference or JsonVariant::invalid() if not found. const JsonVariant &at(key_type key) const; + + // Gets or create the JsonVariant associated with the specified key. + // Returns a reference or JsonVariant::invalid() if allocation failed. JsonVariant &operator[](key_type key); + + // Gets the JsonVariant associated with the specified key. + // Returns a constant reference or JsonVariant::invalid() if not found. const JsonVariant &operator[](key_type key) const { return at(key); } - void remove(key_type key); + // Adds an uninitialized JsonVariant associated with the specified key. + // Return a reference or JsonVariant::invalid() if allocation fails. + JsonVariant &add(key_type key) { return (*this)[key]; } + // Adds the specified key with the specified value. template void add(key_type key, T value) { add(key).set(value); } + + // Adds the specified key with a reference to the specified JsonArray. void add(key_type key, JsonArray &array) { add(key).set(array); } + + // Adds the specified key with a reference to the specified JsonObject. void add(key_type key, JsonObject &object) { add(key).set(object); } + // Creates and adds a JsonArray. + // This is a shortcut for JsonBuffer::createArray() and JsonObject::add(). JsonArray &createNestedArray(key_type key); + + // Creates and adds a JsonObject. + // This is a shortcut for JsonBuffer::createObject() and JsonObject::add(). JsonObject &createNestedObject(key_type key); + // Removes the specified key and the associated value. + void remove(key_type key); + + // Returns a reference an invalid JsonObject. + // This object is meant to replace a NULL pointer. + // This is used when memory allocation or JSON parsing fail. static JsonObject &invalid() { return _invalid; } template void writeTo(T &writer) const; private: - // constructor is private, instance must be created via JsonBuffer + // Create an empty JsonArray attached to the specified JsonBuffer. explicit JsonObject(JsonBuffer *buffer) : List(buffer) {} - JsonVariant &add(key_type key) { return (*this)[key]; } - + // Returns the list node that matches the specified key. node_type *getNodeAt(key_type key) const; + + // Returns the list node that matches the specified key, creating it if + // needed. node_type *getOrCreateNodeAt(key_type key); + // The instance returned by JsonObject::invalid() static JsonObject _invalid; }; } diff --git a/src/Internals/JsonParser.cpp b/src/Internals/JsonParser.cpp index 9085d83c..26b5541f 100644 --- a/src/Internals/JsonParser.cpp +++ b/src/Internals/JsonParser.cpp @@ -152,7 +152,7 @@ JsonObject &JsonParser::parseObject() { if (!skip(':')) break; // colon is missing - JsonVariant &value = object[key]; + JsonVariant &value = object.add(key); parseAnythingTo(value); if (!value.success()) break; // value parsing failed