From 6fa4f319eb90648958b504783a47f007f884fe31 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Beno=C3=AEt=20Blanchon?= Date: Tue, 23 Feb 2016 13:11:48 +0100 Subject: [PATCH] Updated API Reference (markdown) --- API-Reference.md | 199 +++++++++++++++++++++++++++++++++++++++++------ 1 file changed, 174 insertions(+), 25 deletions(-) diff --git a/API-Reference.md b/API-Reference.md index c669566..675ee9e 100644 --- a/API-Reference.md +++ b/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.