1.前言
前面,部落客已經講解了ArduinoJson庫的V5版本。為了節省時間以及不讨論重複内容,部落客建議讀者先去閱讀一下 玩轉ArduinoJson庫 V5版本 。重點了解幾個東西:
JSON協定
JsonBuffer
JsonObject
JsonArray
接下來,我們直接進入V6版本的學習,盡量和V5版本類比。
2.ArduinoJson V6版本
假設讀者下載下傳的V6版本的,那麼可以參考 這裡 的API說明。讀者需要注意一下JsonDocument(可類比V5版本的JsonBuffer),因為V6版本的json操作都是在它上面。
對于開發者來說,使用JSON無非就是編碼或者解碼,是以部落客也會分出兩種情況來講解。
首先我們來看看V6版本常用的百度腦圖:
可以看出,方法主要分為三大類:
JsonDocument相關,這是整個json庫的入口,它負責高效管理記憶體以及調用json解析器;
JsonObject相關;
JsonArray相關;
解析、構造相關;
2.0 解析、構造相關
2.0.1 deserializeJson —— 解析json
函數說明:
詳細可以參考 wiki
/**
* 解析json
* @param doc jsondocument對象
* @param input 輸入内容
* @return DeserializationError 解析結果
*/
// writable input => zero-copy
DeserializationError deserializeJson(JsonDocument& doc, char* input);
DeserializationError deserializeJson(JsonDocument& doc, char* input, size_t inputSize);
// read-only input => duplication
DeserializationError deserializeJson(JsonDocument& doc, const char* input);
DeserializationError deserializeJson(JsonDocument& doc, const char* input, size_t inputSize);
DeserializationError deserializeJson(JsonDocument& doc, const __FlashStringHelper* input);
DeserializationError deserializeJson(JsonDocument& doc, const __FlashStringHelper* input, size_t inputSize);
DeserializationError deserializeJson(JsonDocument& doc, const String& input);
DeserializationError deserializeJson(JsonDocument& doc, const std::string& input);
DeserializationError deserializeJson(JsonDocument& doc, Stream& input);
DeserializationError deserializeJson(JsonDocument& doc, std::istream& input);
12345678910111213141516171819
DeserializationError具體内容請參考 wiki
例子說明:
//Read-only input
const char* json = "{"hello":"world"}";
StaticJsonDocument<200> doc;
deserializeJson(doc, json);
const char* world = doc["hello"];
//Zero-copy mode
char json[] = "{"hello":"world"}";
StaticJsonDocument<200> doc;
deserializeJson(doc, json);
const char* world = doc["hello"];
//Raise the nesting limit
char json[] = "[[[[[[[[[[[[[[[42]]]]]]]]]]]]]]]";
StaticJsonDocument<200> doc;
deserializeJson(doc, json, DeserializationOption::NestingLimit(15));;
int answer = doc[0][0][0][0][0][0][0][0][0][0][0][0][0][0][0];
1234567891011121314151617
2.0.2 serializeJson —— 構造序列化json
函數說明:
詳細可以參考 wiki
/**
* 構造序列化json
* @param doc jsondocument對象
* @param output 輸出内容
*/
serializeJson(const JsonDocument& doc, char* output, size_t outputSize);
serializeJson(const JsonDocument& doc, char output[size]);
serializeJson(const JsonDocument& doc, Print& output);
serializeJson(const JsonDocument& doc, String& output);
serializeJson(const JsonDocument& doc, std::string& output);
serializeJson(const JsonDocument& doc, std::ostream& output);
1234567891011
例子說明:
StaticJsonDocument<200> doc;
doc["hello"] = "world";
serializeJson(doc, Serial);
123
列印結果:
{"hello":"world"}
1
注意:
此方法屬于精簡壓縮化輸出;
2.0.3 serializeJsonPretty —— 構造序列化json,格式化輸出
函數說明:
詳細可以參考 wiki
/**
* 構造序列化json,格式化輸出
* @param doc jsondocument對象
* @param output 輸出内容
*/
size_t serializeJsonPretty(const JsonDocument& doc, char* output, size_t outputSize);
size_t serializeJsonPretty(const JsonDocument& doc, char output[size]);
size_t serializeJsonPretty(const JsonDocument& doc, Print& output);
size_t serializeJsonPretty(const JsonDocument& doc, String& output);
size_t serializeJsonPretty(const JsonDocument& doc, std::string& output);
12345678910
例子說明:
StaticJsonDocument<200> doc;
doc["hello"] = "world";
serializeJsonPretty(doc, Serial);
123
列印結果:
{
"hello": "world"
}
123
注意:
此方法屬于格式化輸出,需要考慮記憶體消耗;
2.0.4 measureJson —— 計算構造序列化json的長度
函數說明:
詳細可以參考 wiki
/**
* 計算構造序列化json的長度
* @param doc jsondocument對象
* @Note 關聯方法 serializeJson
*/
size_t measureJson(const JsonDocument& doc);
123456
例子說明:
// Send headers
client.println("Content-Type: application/json");
client.print("Content-Length: ");
client.println(measureJson(doc));
// Terminate headers
client.println();
// Send body
serializeJson(doc, client);
12345678910
2.0.5 measureJsonPretty —— 計算構造序列化格式化json的長度
函數說明:
詳細可以參考 wiki
/**
* 計算構造序列化格式化json的長度
* @param doc jsondocument對象
* @Note 關聯方法 serializeJsonPretty
*/
size_t measureJsonPretty(const JsonDocument& doc);
123456
例子說明:
// Send headers
client.println("Content-Type: application/json");
client.print("Content-Length: ");
client.println(measureJsonPretty(doc));
// Terminate headers
client.println();
// Send body
serializeJsonPretty(doc, client);
12345678910
2.1 JsonDocument
JsonDocument作為整個V6版本ArduinoJson庫的記憶體入口,負責處理整個json資料的記憶體管理,這是我們需要首先重點關注的内容。
它包括兩個實作類:
DynamicJsonDocument,記憶體配置設定在heap區,無固定大小,可以自動增長所需空間,方法調用完自動回收,建議記憶體大小大于1KB使用;
StaticJsonDocument<256> doc;
1
StaticJsonDocument,記憶體配置設定在stack區,有固定大小,大小值由開發者定義,方法調用完自動回收,建議記憶體大小小于1KB使用;
DynamicJsonDocument doc(2048);
1
使用JsonDocument
當你建立一個JsonDocument之後,預設初始化為空,調用 JsonDocument::isNull()會傳回true,這個時候既可以代表當做jsonObject,也可以當做jsonArray,這取決于你插入第一個value的類型。
以下會作為JsonObject使用:
DynamicJsonDocument doc(1024);
doc["answer"] = 42;
// the doc contains {"answer":42}
123
以下會作為JsonArray使用:
DynamicJsonDocument doc(1024);
doc.add(42);
// the doc contains [42]
123
接下來,看看JsonDocument的一些常用方法:
2.1.1 as —— 擷取頂節點,并把它轉成T類型
函數說明:
/**
* 擷取頂節點,并把它轉成T類型
* @return JsonArray/JsonObject/JsonVariant
*/
JsonArray as<JsonArray>();
JsonObject as<JsonObject>();
JsonVariant as<JsonVariant>();
1234567
例子說明:
DynamicJsonBuffer doc(1024);
deserializeJson(doc, "{"key":"value")");
// get the JsonObject in the JsonDocument
JsonObject root = doc.as<JsonObject>();
// get the value in the JsonObject
const char* value = root["key"];
12345678
注意:
此方法不會改變 JsonDocument的内容(JsonDocument::to()會改變)
此方法隻會傳回JsonDocument頂節點的引用。如果頂節點的類型和強轉的T類型不比對,此方法将會傳回空引用(比如,如果JsonDocument是一個jsonArray,當調用JsonDocument::as(),會傳回空JsonObject)。
2.1.2 add —— 往jsondocument添加元素
函數說明:
/**
* 往jsondocument添加元素
* @param value 元素
*/
// add the specified value to the array
bool add(bool value);
bool add(float value);
bool add(double value);
bool add(signed char value);
bool add(signed long value);
bool add(signed int value);
bool add(signed short value);
bool add(unsigned char value);
bool add(unsigned long value);
bool add(unsigned int value);
bool add(unsigned short value);
bool add(char *value); // see Remarks
bool add(const char *value);
bool add(const __FlashStringHelper *value); // see Remarks
bool add(const String &value); // see Remarks
bool add(const std::string &value); // see Remarks
bool add(JsonArray array);
bool add(JsonObject object);
bool add(JsonVariant variant);
1234567891011121314151617181920212223242526272829
例子說明:
StaticJsonDocument<200> doc;
array.add("hello"); // null -> ["hello"]
array.add(3.14156); // ["hello"] -> ["hello",3.14156]
serializeJson(doc, Serial);
1234
列印結果:
["hello",3.14156]
1
注意:
如果JsonDocument頂節點是一個JsonArray,add方法會追加一個value到數組;
如果JsonDocument頂節點是一個JsonObject,add無效;
如果JsonDocument是一個空對象,add方法會把JsonDocument變成一個包含一個元素的數組,這是一個建立數組的方式;
2.1.3 clear —— 清除JsonDocument并釋放記憶體空間
函數說明:
/**
* 清除JsonDocument并釋放記憶體空間
*/
void clear();
1234
注意:
這個方法和JsonBuffer的clear方法不一樣;
2.1.4 createNestedArray —— 建立空json數組,并為它配置設定記憶體空間
函數說明:
/**
* 建立空json數組,并為它配置設定記憶體空間
* @param key key名稱
* @return JsonArray
*/
// similar to JsonArray::createNestedArray()
JsonArray createNestedArray();
// similar to JsonObject::createNestedArray()
JsonArray createNestedArray(char* key);
JsonArray createNestedArray(const char* key);
JsonArray createNestedArray(const __FlashStringHelper* key);
JsonArray createNestedArray(const String& key);
JsonArray createNestedArray(const std::string& key);
1234567891011121314
例子說明:
DynamicJsonDocument doc(1024);
JsonArray ports = doc.createNestedArray("ports");
ports.add("80");
ports.add("443");
1234
列印結果:
{
"ports": [
80,
443
]
}
123456
注意:
對于無參數的createNestedArray()方法,會建立一個Json數組并把它追加到頂節點的數組中。如果document的頂節點不是數組,這個方法無效;如果document是空的,這個方法會初始化一個數組頂節點,參考以下代碼:
StaticJsonDocument<200> doc;
JsonArray arr = doc.createNestedArray();
arr.add("hello world");
serializeJson(doc, Serial);
123456
列印結果:
[["hello world"]]
1
對于有參數的createNestedArray()方法,會建立一個json數組并把它指向這個特定的key。如果document的頂節點不是對象,這個方法無效;如果document是空的,這個方法會初始化一個對象頂節點,參考以下代碼:
StaticJsonDocument<200> doc;
JsonArray array = doc.createNestedArray("hello");
array.add("world");
serializeJson(doc, Serial);
123456
列印結果:
{"hello":["world"]}
1
2.1.5 createNestedObject —— 建立空json對象,并為它配置設定記憶體空間
函數說明:
/**
* 建立空json對象,并為它配置設定記憶體空間
* @param key key名稱
* @return JsonObject
*/
// similar to JsonArray::createNestedArray()
// similar to JsonArray::createNestedObject()
JsonObject createNestedObject();
// similar to JsonObject::createNestedObject()
JsonObject createNestedObject(char* key);
JsonObject createNestedObject(const char* key);
JsonObject createNestedObject(const __FlashStringHelper* key);
JsonObject createNestedObject(const String& key);
JsonObject createNestedObject(const std::string& key);
123456789101112131415
例子說明:
DynamicJsonDocument doc(1024);
JsonArray wifi = doc.createNestedObject("wifi");
wifi["SSID"] = "TheBatCave";
123
列印結果:
{
"wifi": {
"SSID": "TheBatCave"
}
}
12345
注意:
對于無參數的createNestedObject()方法,會建立一個Json對象并把它追加到頂節點的數組中。如果document的頂節點不是數組,這個方法無效;如果document是空的,這個方法會初始化一個數組頂節點,參考以下代碼:
StaticJsonDocument<200> doc;
JsonObject obj = doc.createNestedObject();
obj["hello"] = "world";
serializeJson(doc, Serial);
123456
列印結果:
[{"hello":"world"}]
1
對于有參數的createNestedObject()方法,會建立一個json數組并把它指向這個特定的key。如果document的頂節點不是對象,這個方法無效;如果document是空的,這個方法會初始化一個對象頂節點,參考以下代碼:
StaticJsonDocument<200> doc;
JsonObject obj = doc.createNestedObject("nested");
obj["hello"] = "world";
serializeJson(doc, Serial);
123456
列印結果:
{"nested":{"hello":"world"}}
1
2.1.6 getElement —— 擷取index位置/key的元素
函數說明:
/**
* 擷取index位置/key的元素
* @param index 索引位置
* @return JsonVariant 如果找不到比對的傳回null
*/
JsonVariant getElement(size_t index);
123456
2.1.7 getMember —— 擷取key對應的value
函數說明:
/**
* 擷取key對應的value
* @param key 對應的key
* @param JsonVariant key對應的value,如果不比對傳回null
*/
JsonVariant getMember(const char* key);
JsonVariant getMember(String key);
JsonVariant getMember(std::string key);
JsonVariant getMember(const __FlashStringHelper* key);
123456789
2.1.8 getOrCreateMember —— 擷取或者建立key對應的value
函數說明:
/**
* 擷取或者建立key對應的value
* @param key 對應的key
* @param JsonVariant key對應的value,如果不比對傳回null
*/
JsonVariant getOrCreateMember(const char* key);
JsonVariant getOrCreateMember(String key);
JsonVariant getOrCreateMember(std::string key);
JsonVariant getOrCreateMember(const __FlashStringHelper* key);
123456789
注意:
如果JsonDocument包含一個對象,那麼getOrCreateMember方法會擷取指定key的值,如果對象不存在該key,這個方法會往對象添加一個新的key-value鍵值對;
如果JsonDocument是空,那麼getOrCreateMember方法将建立一個對象給到JsonDocument;
如果屬于以上兩種情況之外的,此方法無效;
2.1.9 operator[] —— 快捷操作符
函數說明:
/**
* 快捷操作符
* @param key 對象中對應的key
* @param index 數組中對應的索引
*/
// mimics a JsonArray
ElementProxy operator[](size_t index);
// mimics a JsonObject
MemberProxy operator[](const char* key);
MemberProxy operator[](char* key);
MemberProxy operator[](const String& key);
MemberProxy operator[](const std::string& key);
MemberProxy operator[](const __FlashStringHelper* key);
1234567891011121314
例子說明:
StaticJsonDocument<256> doc;
doc["wifi"]["SSID"] = "TheBatCave";
12
列印内容:
{
"wifi": {
"SSID": "TheBatCave"
}
}
12345
2.1.10 isNull —— 判斷jsondocument是否為空
函數說明:
/**
* 判斷jsondocument是否為空
*/
bool isNull() const;
1234
例子說明:
//Result is true
DynamicJsonDocument doc(1024);
doc.isNull(); // true
serializeJson(doc, Serial); // prints "null"
//Result is false
DynamicJsonDocument doc(1024);
doc.to<JsonArray>();
doc.isNull(); // false
serializeJson(doc, Serial); // prints "[]"
12345678910
2.1.11 memoryUsage —— jsondocument已使用記憶體位元組數
函數說明:
/**
* jsondocument已使用記憶體位元組數
*/
size_t memoryUsage() const;
1234
例子說明:
char json[] = "{"hello":"world"}";
StaticJsonDocument<200> doc;
deserializeJson(doc, json);
Serial.println(doc.memoryUage());
// prints 26 on AVR
123456
2.1.12 to —— jsondocument轉成T類型
函數說明:
/**
* jsondocument轉成T類型,T為JsonArray、JsonObject、JsonVariant
*/
JsonArray to<JsonArray>();
JsonObject to<JsonObject>();
JsonVariant to<JsonVariant>();
123456
例子說明:
// allocate the JsonDocument
StaticJsonDocument<200> doc;
// convert it to a JsonObject
JsonObject root = doc.to<JsonObject>();
// set values
root["hello"] = "world";
12345678
注意:
此方法是釋放jsondocument的記憶體空間,也就是說之前已經配置設定的引用無效,參考代碼:
DynamicJsonBuffer doc(1024);
JsonObject root1 = doc.to<JsonObject>();
JsonObject root2 = doc.to<JsonObject>();
// Don't use root1 here, because it's dangling!
1234567
2.2 JsonObject
在JsonDocument所構造出來的記憶體空間中,Json對象的入口就是JsonObject。
讓我們看看它的常用操作方法:
2.2.1 begin/end —— 傳回一個疊代器,可用于對象中的所有鍵值對
函數說明:
/**
* 傳回一個疊代器,可用于對象中的所有鍵值對
*/
JsonObject::iterator begin() const;
JsonObject::iterator end() const;
12345
例子說明:
char json[] = "{"first":"hello","second":"world"}";
DynamicJsonDocument doc(1024);
deserializeJson(doc, json);
JsonObject root = doc.as<JsonObject>();
// using C++11 syntax (preferred):
for (JsonPair kv : root) {
Serial.println(kv.key().c_str());
Serial.println(kv.value().as<char*>());
}
// using C++98 syntax (for older compilers):
for (JsonObject::iterator it=root.begin(); it!=root.end(); ++it) {
Serial.println(it->key().c_str());
Serial.println(it->value().as<char*>());
}
12345678910111213141516
列印結果:
first
hello
second
world
1234
2.2.2 containsKey —— 判斷對象是否包含某一個key
函數說明:
/**
* 判斷對象是否包含某一個key
* @param key key名字
* @return bool
*/
bool containsKey(const char* key) const;
bool containsKey(const String& key) const;
bool containsKey(const std::string& key) const;
bool containsKey(const __FlashStringHelper& key) const;
123456789
例子說明:
StaticJsonDocument<256> doc;
JsonObject root = doc.to<JsonObject>();
root["city"] = "Paris";
bool hasCity = root.containsKey("city"); // true
bool hasCountry = root.containsKey("country"); // false
}
1234567
注意:
json庫的開發者不建議使用該方法,因為就算沒有值也會傳回一個空值。庫開發者給了例子建議:
if (root.containsKey("error")) {
const char* error = root["error"]
Serial.println(error);
return;
}
12345
可以改成:
JsonVariant error = root["error"];
if (!error.isNull()) {
Serial.println(error.as<char*>());
return;
}
12345
或者更加簡單快速的方法:
const char* error = root["error"];
if (error) {
Serial.println(error);
return;
}
12345
2.2.3 createNestedArray —— 在目前對象中添加子key,子value為json數組
函數說明:
/**
* 在目前對象中添加子key,子value為json數組
* @param key key名字
* @return JsonArray
*/
JsonArray createNestedArray(char* key) const;
JsonArray createNestedArray(const char* key) const;
JsonArray createNestedArray(const __FlashStringHelper* key) const;
JsonArray createNestedArray(const String& key) const;
JsonArray createNestedArray(const std::string& key) const;
1234567891011
例子說明:
StaticJsonDocument<256> doc;
JsonObject root = doc.to<JsonObject>();
root["status"] = "on";
JsonArray levels = root.createNestedArray("levels");
levels.add(10);
levels.add(30);
serializeJsonPretty(root, Serial);
1234567
列印結果:
{
"status": "on",
"levels": [
10,
20
]
}
1234567
2.2.4 createNestedObject —— 在目前對象中添加子key,子value為json對象
函數說明:
/**
* 在目前對象中添加子key,子value為json對象
* @param key key名字
* @return JsonObject對象
*/
JsonObject createNestedObject(char* key) const;
JsonObject createNestedObject(const char* key) const;
JsonObject createNestedObject(const __FlashStringHelper* key) const;
JsonObject createNestedObject(const String& key) const; // see Remarks
JsonObject createNestedObject(const std::string& key) const; // see Remarks
1234567891011
例子說明:
StaticJsonDocument<256> doc;
JsonObject root = doc.to<JsonObject>();
root["city"] = "Paris";
JsonObject weather = root.createNestedObject("weather");
weather["temp"] = 14.2;
weather["cond"] = "cloudy";
serializeJsonPretty(root, Serial);
1234567
列印結果:
{
"city": "Paris",
"weather": {
"temp": 14.20,
"cond": "cloudy"
}
}
1234567
2.2.5 getMember —— 擷取對象中給到key的value
函數說明:
/**
* 擷取對象中給到key的value
* @param key key名字
* @return JsonVariant對象
*/
JsonVariant getMember(const char* key) const;
JsonVariant getMember(const __FlashStringHelper* key) const;
JsonVariant getMember(const String& key) const;
JsonVariant getMember(const std::string& key) const;
12345678910
例子說明:
例子1:
//The key is not found
char json[] = "{"username":"the_duke"}";
StaticJsonDocument<256> doc;
deserializeJson(doc, json);
JsonObject object = doc.as<JsonObject>();
JsonVariant password = object.getMember("password");
if (password.isNull()) {
Serial.println(F("Error: password is missing"));
}
123456789101112
列印結果:
Error: password is missing
1
例子2:
//The key is found
char json[] = "{"username":"the_duke"}";
StaticJsonDocument<256> doc;
deserializeJson(doc, json);
JsonObject object = doc.as<JsonObject>();
JsonVariant username = object.getMember("username");
Serial.println(F("Your name is: "));
Serial.println(username.as<const char*>());
1234567891011
列印結果:
Your name is: the_duke
1
2.2.6 getOrCreateMember —— 擷取對象中給到key的value,如果沒有就建立
函數說明:
/**
* 擷取對象中給到key的value,如果沒有就建立
* @param key key名字
* @return JsonVariant對象
*/
JsonVariant getOrCreateMember(char* key) const;
JsonVariant getOrCreateMember(const char* key) const;
JsonVariant getOrCreateMember(const __FlashStringHelper* key) const;
JsonVariant getOrCreateMember(const String& key) const;
JsonVariant getOrCreateMember(const std::string& key) const;
1234567891011
2.2.7 isNull —— 判斷對象是否為空
函數說明:
/**
* 判斷對象是否為空
* @Note You can use this function to:
* check if the object was successfully parsed, or
* check if the object was successfully allocated.
*/
bool isNull() const;
1234567
例子說明:
//Example 1: parsing success:
StaticJsonDocument<200> doc;
deserializeJson(doc, "{"hello":"world"}");
JsonObject object = doc.as<JsonObject>();
Serial.println(object.isNull()); // false
//Example 2: parsing failure:
StaticJsonDocument<200> doc;
deserializeJson(doc, "["hello","world"]");
JsonObject object = doc.as<JsonObject>();
Serial.println(object.isNull()); // true
//Example 3: allocation success:
StaticJsonDocument<200> doc;
JsonObject object = doc.to<JsonObject>();
Serial.println(object.isNull()); // false
//Example 4: allocation failure:
StaticJsonDocument<1> doc;
JsonObject object = doc.to<JsonObject>();
Serial.println(object.isNull()); // true
123456789101112131415161718192021
2.2.8 operator[] —— get/set快捷方式
函數說明:
/**
* get/set快捷方式
*/
MemberProxy operator[](char* key) const;
MemberProxy operator[](const char* key) const;
MemberProxy operator[](const __FlashStringHelper* key) const;
MemberProxy operator[](const String& key) const;
MemberProxy operator[](const std::string& key) const;
123456789
例子說明:
//以下兩行代碼效果等同
JsonVariant value = object["key"];
JsonVariant value = object.getMember("key");
//以下兩行代碼效果等同
object["key"] = "value";
object.getOrCreateMember("key").set("value");
StaticJsonDocument<256> doc;
JsonObject object = doc.to<JsonObject>();
object["hello"] = "world";
const char* world = object["hello"];
123456789101112
2.2.9 remove —— 移除特定key和value
函數說明:
/**
* 移除特定key和value
* @param key key名
*/
void remove(const char* key) const;
void remove(const __FlashStringHelper* key) const;
void remove(const String& key) const;
void remove(const std::string& key) const;
123456789
例子說明:
JsonObject object = doc.to<JsonObject>();
object["A"] = 1;
object["B"] = 2;
object["C"] = 3;
object.remove("B");
serializeJson(object, Serial);
123456
列印結果:
{"A":1,"C":3}
1
注意:
該方法隻會移除key-value,但是并不會釋放key-value對應的jsondocument空間,也不建議在循環中同時add和remove key-value;
2.2.10 set —— 把一個json對象的内容設定給目前json對象
函數說明:
/**
* 把一個json對象的内容設定給目前json對象
*/
bool set(JsonObjectConst obj) const;
1234
2.2.11 size —— 傳回對象鍵值對的個數
函數說明:
/**
* 傳回對象鍵值對的個數
* @return size_t 個數
*/
size_t size() const;
12345
例子說明:
JsonObject object = doc.to<JsonObject>();
object["hello"] = "world";
Serial.println(object.size()); // 1
123
2.3 JsonArray
在JsonDocument所構造出來的記憶體空間中,Json數組的入口就是JsonArray。
讓我們看看它的常用操作方法:
2.3.1 add —— 往數組中加入value
函數說明:
/**
* 往數組中加入value
* @param value 值
* @return bool 是否添加成功,如果傳回false一般都是jsonbuffer沒有足夠的空間
*/
bool add(bool value) const;
bool add(float value) const;
bool add(double value) const;
bool add(signed char value) const;
bool add(signed long value) const;
bool add(signed int value) const;
bool add(signed short value) const;
bool add(unsigned char value) const;
bool add(unsigned long value) const;
bool add(unsigned int value) const;
bool add(unsigned short value) const;
bool add(const char *value) const;
bool add(char *value) const;
bool add(const __FlashStringHelper *value) const;
bool add(const String &value) const;
bool add(const std::string &value) const;
bool add(JsonArray array) const;
bool add(JsonObject object) const;
bool add(JsonVariant variant) const;
1234567891011121314151617181920212223242526272829
例子說明:
StaticJsonDocument<200> doc;
JsonArray array = doc.to<JsonArray>();
array.add("hello");
array.add(3.14156);
serializeJson(doc, Serial);
12345
列印結果:
["hello",3.14156]
1
2.3.2 begin/end —— 傳回一個疊代器,可用于數組中的所有對象
函數說明:
/**
* 傳回一個疊代器,可用于數組中的所有對象
* @return iterator
*/
JsonArray::iterator begin() const;
JsonArray::iterator end() const;
123456
例子說明:
char json[] = "["one","two","three"]";
DynamicJsonDocument doc(1024);
deserializeJson(doc, json);
JsonArray arr = doc.as<JsonArray>();
// using C++11 syntax (preferred):
for (JsonVariant value : arr) {
Serial.println(value.as<char*>());
}
// using C++98 syntax (for older compilers):
for (JsonArray::iterator it=arr.begin(); it!=arr.end(); ++it) {
Serial.println(it->as<char*>());
}
1234567891011121314
列印結果:
one
two
three
123
2.3.3 createNestedArray —— 添加json數組
函數說明:
/**
* 添加json數組
* @return JsonArray json數組
*/
JsonArray createNestedArray() const;
12345
例子說明:
StaticJsonDocument<200> doc;
JsonArray array = doc.to<JsonArray>();
array.add("hello");
JsonArray nested = array.createNestedArray();
nested.add("world");
serializeJson(array, Serial);
123456
列印結果:
["hello",["world"]]
1
2.3.4 createNestedObject —— 添加json對象
函數說明:
/**
* 添加json對象
* @return JsonObject json對象
*/
JsonObject createNestedObject() const;
12345
例子說明:
StaticJsonDocument<200> doc;
JsonArray array = doc.to<JsonArray>();
JsonObject nested = array.createNestedObject();
nested["hello"] = "world";
serializeJson(array, Serial);
12345
列印結果:
[{"hello":"world"}]
1
2.3.5 getElement —— 擷取對應index的值
函數說明:
/**
* 擷取對應index的值
*/
JsonVariant getElement(size_t index) const;;
1234
2.3.6 isNull —— 判斷json數組是否為空
函數說明:
/**
* 判斷json數組是否為空
* @Note You can use this function to:
* check if the array was successfully parsed, or
* check if the array was successfully allocated.
*/
bool isNull() const;
1234567
例子說明:
//Example 1: parsing success:
StaticJsonDocument<200> doc;
deserializeJson(doc, "[1,2]");
JsonArray array = doc.as<JsonArray>();
Serial.println(array.isNull()); // false
//Example 2: parsing failure:
StaticJsonDocument<200> doc;
deserializeJson(doc, "{1,2}");
JsonArray array = doc.as<JsonArray>();
Serial.println(array.isNull()); // true
//Example 3: allocation success:
StaticJsonDocument<200> doc;
JsonArray array = doc.to<JsonArray>();
Serial.println(array.isNull()); // false
//Example 4: allocation failure:
StaticJsonDocument<1> doc;
JsonArray array = doc.to<JsonArray>();
Serial.println(array.isNull()); // true
123456789101112131415161718192021
2.3.7 operator[] —— set/get快捷方式
函數說明:
/**
* set/get快捷方式
*/
ElementProxy operator[](size_t index) const;
1234
例子說明:
//以下兩句代碼含義一樣
JsonVariant value = array[0];
JsonVariant value = array.getElement(0);
//以下兩句代碼含義一樣
array[0] = "value";
array.getElement(0).set("value");
JsonArray array = doc.to<JsonArray>();
array.add(42);
int value = array[0];
array[0] = 666;
12345678910111213
2.3.8 remove —— 移除某一個index位置的元素
函數說明:
/**
* 移除某一個index位置的元素
* @param index 索引
*/
void remove(size_t index) const;
12345
例子說明:
JsonArray array = doc.to<JsonArray>();
array.add("A");
array.add("B");
array.add("C");
array.remove(1);
serializeJson(array, Serial);
123456
列印結果:
["A","C"]
1
注意:
該方法隻會移除索引對應的value,但是并不會釋放對應的jsonDocument空間,也不建議在循環中同時add和remove;
2.3.9 set —— 用另一個jsonArray代替目前jsonArray
函數說明:
/**
*用另一個jsonArray代替目前jsonArray
*/
bool set(JsonArrayConst src) const;
1234
2.3.10 size —— 傳回json數組元素的個數
函數說明:
/**
* 傳回json數組元素的個數
* @return size_t 個數
*/
size_t size() const;
12345
例子說明:
JsonArray array = doc.to<JsonArray>();
array.add("hello");
array.add("world");
Serial.println(array.size()); // 2
————————————————
版權聲明:本文為CSDN部落客「單片機菜鳥哥」的原創文章,遵循CC 4.0 BY-SA 版權協定,轉載請附上原文出處連結及本聲明。
原文連結:https://blog.csdn.net/dpjcn1990/article/details/92831648