Updated API Reference (markdown)

API-Reference.md

@@ -11,7 +11,7 @@ Represents an array in a JSON object tree.
 
 ### Constructor
 
-The constructor is private, you cannot instanciate a `JsonArray` directly, you have to use a `JsonBuffer`.
+The constructor is private, you cannot instantiate a `JsonArray` directly, you have to use a `JsonBuffer`.
 
 Because the memory of a `JsonArray` is located a `JsonBuffer`, you always manipulate it through reference and you cannot copy it.
 
@@ -51,7 +51,7 @@ bool add(unsigned long value);
 bool add(unsigned int value);
 bool add(unsigned short value);
 bool add(const char *value);
-bool add(const String &value);
+bool add(const String &value); // see Remarks
 bool add(JsonArray &array);
 bool add(JsonObject &object);
 bool add(const JsonVariant &variant);
@@ -69,6 +69,12 @@ bool add(const JsonVariant &variant);
 
 `false` if there was not enough memory in the `JsonBuffer`.
 
+##### Remarks
+
+When you call `JsonArray::add(const String&)`, a copy of the string is made, causing the `JsonBuffer` to grow.
+The memory allocated for the copy will only be freed when the whole `JsonBuffer` is discarded.
+To avoid this behavior, use `JsonArray::add(const char*)` instead.
+
 ##### Example
 
 ```c++
@@ -369,7 +375,7 @@ void set(size_t index, unsigned long value);
 void set(size_t index, unsigned int value);
 void set(size_t index, unsigned short value);
 void set(size_t index, const char *value);
-void set(size_t index, const String &value);
+void set(size_t index, const String &value); // see Remarks
 void set(size_t index, JsonArray &array);
 void set(size_t index, JsonObject &object);
 void set(size_t index, const JsonVariant &value);
@@ -380,6 +386,12 @@ void set(size_t index, const JsonVariant &value);
 `index`: position to set value in array.
 `value`: the value to set in index of array.
 
+##### Remarks
+
+When you call `JsonArray::set(size_t, const String&)`, a copy of the string is made, causing the `JsonBuffer` to grow.
+The memory allocated for the copy will only be freed when the whole `JsonBuffer` is discarded.
+To avoid this behavior, use `JsonArray::set(size_t, const char*)` instead.
+
 ##### Example
 
 ```c++
@@ -445,7 +457,7 @@ Example 1: parsing success:
 
 ```c++
 StaticJsonBuffer<200> jsonBuffer;
-JsonArray& array = jsonBuffer.parse("[1,2]");
+JsonArray& array = jsonBuffer.parseArray("[1,2]");
 Serial.println(array.success()); // true
 ```
 
@@ -453,7 +465,7 @@ Example 2: parsing failure:
 
 ```c++
 StaticJsonBuffer<200> jsonBuffer;
-JsonArray& array = jsonBuffer.parse("{1,2}");
+JsonArray& array = jsonBuffer.parseArray("{1,2}");
 Serial.println(array.success()); // false
 ```
 
@@ -730,6 +742,12 @@ const JsonVariant& operator[](const String& key) const;
 
 A reference to the `JsonVariant` in the object.
 
+##### Remarks
+
+When you add a value using a `String` for key, a copy of the string is made, causing the `JsonBuffer` to grow.
+The memory allocated for the copy will only be freed when the whole `JsonBuffer` is discarded.
+To avoid this behavior, use a `const char*` key instead.
+
 ##### Example
 
 ```c++
@@ -871,32 +889,163 @@ will print the following string to the serial output:
 ```
 
 
+### JsonArray::set()
+
+##### Description
+
+Sets the value at specified key.
+
+##### Signatures
+
+```c++
+void set(const char* key, bool value);
+void set(const char* key, float value, uint8_t decimals = 2);
+void set(const char* key, double value, uint8_t decimals = 2);
+void set(const char* key, signed char value);
+void set(const char* key, signed long value);
+void set(const char* key, signed int value);
+void set(const char* key, signed short value);
+void set(const char* key, unsigned char value);
+void set(const char* key, unsigned long value);
+void set(const char* key, unsigned int value);
+void set(const char* key, unsigned short value);
+void set(const char* key, const char *value);
+void set(const char* key, const String &value);                  // see Remarks
+void set(const char* key, JsonArray &array);
+void set(const char* key, JsonObject &object);
+void set(const char* key, const JsonVariant &value);
+void set(const String& key, bool value);                         // see Remarks
+void set(const String& key, float value, uint8_t decimals = 2);  // see Remarks
+void set(const String& key, double value, uint8_t decimals = 2); // see Remarks
+void set(const String& key, signed char value);                  // see Remarks
+void set(const String& key, signed long value);                  // see Remarks
+void set(const String& key, signed int value);                   // see Remarks
+void set(const String& key, signed short value);                 // see Remarks
+void set(const String& key, unsigned char value);                // see Remarks
+void set(const String& key, unsigned long value);                // see Remarks
+void set(const String& key, unsigned int value);                 // see Remarks
+void set(const String& key, unsigned short value);               // see Remarks
+void set(const String& key, const char *value);                  // see Remarks
+void set(const String& key, const String &value);                // see Remarks twice
+void set(const String& key, JsonArray &array);                   // see Remarks
+void set(const String& key, JsonObject &object);                 // see Remarks
+void set(const String& key, const JsonVariant &value);           // see Remarks
+```
+
+##### Arguments
+
+`key`: the key to attach the value to.
+`value`: the value to attach to the key.
+
+##### Remarks
+
+When you use a `String`, a copy of the string is made, causing the `JsonBuffer` to grow.
+The memory allocated for the copy will only be freed when the whole `JsonBuffer` is discarded.
+To avoid this behavior, use `const char*` keys and values instead.
+
+##### Example
+
+```c++
+StaticJsonBuffer<200> jsonBuffer;
+JsonObject& object = jsonBuffer.createObject();
+object.set("hello","world");
+object.printTo(Serial);
+```
+
+will print the following string to the serial output:
+
+```json
+{"hello":"world"}
+```
+
+
+### JsonObject::size()
+
+##### Description
+
+Returns the number of key/value pairs in the object.
+
+##### Signature
+
+```c++
+size_t size() const;
+```
+
+##### Return value
+
+An unsigned integer containing the number of key/value pairs in the object.
+
+##### Example
+
+```c++
+JsonObject& object = jsonBuffer.createObject();
+object["hello"] = "world";
+Serial.println(object.size()); // 1
+```
+
+
+
+### JsonObject::success()
+
+##### Description
+
+Tells if the object is valid, which can be used:
+
+1. to check if the object was successfully parsed, or
+2. to check if the object was successfully allocated.
+
+##### Signatures
+
+```c++
+bool success() const;
+```
+
+##### Return value
+
+`true` if the object was successfully parsed/allocated.
+`false` if the parsing/allocation failed.
+
+##### Examples
+
+Example 1: parsing success:
+
+```c++
+StaticJsonBuffer<200> jsonBuffer;
+JsonObject& object = jsonBuffer.parseObject("{\"hello\":\"world\"}");
+Serial.println(object.success()); // true
+```
+
+Example 2: parsing failure:
+
+```c++
+StaticJsonBuffer<200> jsonBuffer;
+JsonObject& object = jsonBuffer.parseObject("[\"hello\",\"world\"]");
+Serial.println(object.success()); // false
+```
+
+Example 3: allocation success:
+
+```c++
+StaticJsonBuffer<200> jsonBuffer;
+JsonObject& object = jsonBuffer.createObject();
+Serial.println(object.success()); // true
+```
+
+Example 4: allocation failure:
+
+```c++
+StaticJsonBuffer<1> jsonBuffer;
+JsonObject& object = jsonBuffer.createObject();
+Serial.println(object.success()); // false
+```
+
+
 :construction:
 
 :construction: Below this line, the writing is still in progress...
 
 :construction:
 
-#### JsonArray::set()
-##### Description
-##### Signatures
-##### Arguments
-##### Return value
-##### Example
-
-#### JsonArray::size()
-##### Description
-##### Signatures
-##### Arguments
-##### Return value
-##### Example
-
-#### JsonArray::success()
-##### Description
-##### Signatures
-##### Arguments
-##### Return value
-##### Example
 
 ## JsonVariant
 A variant that can be a any value serializable to a JSON value.