bblanchon/ArduinoJson
1
0
Fork 1
mirror of https://github.com/bblanchon/ArduinoJson.git synced 2025-08-09 15:44:42 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updated API Reference (markdown)

Benoît Blanchon
2016-11-06 18:28:05 +01:00
parent 26307c97fa
commit 4edf4d82c0
1 changed files with 130 additions and 84 deletions
Download Patch File Download Diff File Expand all files Collapse all files

214
API-Reference.md

@@ -4,6 +4,12 @@ Some parts have been simplified to be easier to understand, so if you look at th
<!-- MarkdownTOC depth=3 autolink=true bracket=round lowercase_only_ascii=true -->
- [Configuration](#configuration)
- [ARDUINOJSON_USE_DOUBLE](#arduinojsonusedouble)
- [ARDUINOJSON_USE_LONG_LONG](#arduinojsonuselonglong)
- [ARDUINOJSON_ENABLE_ARDUINO_STRING](#arduinojsonenablearduinostring)
- [ARDUINOJSON_ENABLE_STD_STRING](#arduinojsonenablestdstring)
- [ARDUINOJSON_DEFAULT_NESTING_LIMIT](#arduinojsondefaultnestinglimit)
- [JsonArray](#jsonarray)
- [Constructor](#constructor)
- [JsonArray::add\(\)](#jsonarrayadd)
@@ -47,6 +53,45 @@ Some parts have been simplified to be easier to understand, so if you look at th
<!-- /MarkdownTOC -->
## Configuration
### ARDUINOJSON_USE_DOUBLE
Determine the type used to store floating point values in `JsonVariant`.
* If `ARDUINOJSON_USE_DOUBLE == 0`, then `JsonVariant` stores a `float`
* If `ARDUINOJSON_USE_DOUBLE == 1`, then `JsonVariant` stores a `double`
Default is `0` of `ARDUINO` is defined, `1` otherwise.
### ARDUINOJSON_USE_LONG_LONG
Determine the type used to store integer values in `JsonVariant`.
* If `ARDUINOJSON_USE_LONG_LONG == 0`, then `JsonVariant` stores a `long`
* If `ARDUINOJSON_USE_LONG_LONG == 1`, then `JsonVariant` stores a `long long`
Default is `0` of `ARDUINO` is defined, `1` otherwise.
### ARDUINOJSON_ENABLE_ARDUINO_STRING
Enable the support of the type `String` in the library.
Default is `1` of `ARDUINO` is defined, `0` otherwise.
### ARDUINOJSON_ENABLE_STD_STRING
Enable the support of the type `std::string` in the library.
Default is `0` of `ARDUINO` is defined, `1` otherwise.
### ARDUINOJSON_DEFAULT_NESTING_LIMIT
Defines the default value the second parameter of `parseObject()` and `parseArray()`, which limit the nesting in the JSON input. (the goal is to prevent stackoverflow).
Default is `10` of `ARDUINO` is defined, `50` otherwise.
## JsonArray
Represents an array in a JSON object tree.
@@ -96,6 +141,7 @@ bool add(unsigned int value);
bool add(unsigned short value);
bool add(const char *value);
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(const JsonVariant &variant);
@@ -115,9 +161,9 @@ bool add(const JsonVariant &variant);
##### Remarks
When you call `JsonArray::add(const String&)`, a copy of the string is made, causing the `JsonBuffer` to grow.
When you call `add(const String&)` or `add(const std::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.
To avoid this behavior, use `add(const char*)` instead.
##### Example
@@ -208,22 +254,22 @@ will write
### JsonArray::get()
##### Description
Gets the value at the specified index.
##### Signature
```c++
// Non template version
JsonVariant get (size_t index) const;
// Template version
```c++
bool get<bool> (size_t index) const;
const char* get<const char*> (size_t index) const;
double get<double> (size_t index) const;
float get<float> (size_t index) const;
JsonVariant get<Variant> (size_t index) const;
signed char get<signed char> (size_t index) const;
signed int get<signed int> (size_t index) const;
signed long get<signed long> (size_t index) const;
signed short get<signed short> (size_t index) const;
std::string get<std::string> (size_t index) const;
String get<String> (size_t index) const;
unsigned char get<unsigned char> (size_t index) const;
unsigned int get<unsigned int> (size_t index) const;
@@ -344,6 +390,7 @@ This will create a "prettified" JSON, if you want a compact JSON without space o
size_t prettyPrintTo(char* buffer, size_t size) const;
size_t prettyPrintTo(Print &) const;
size_t prettyPrintTo(String &) const;
size_t prettyPrintTo(std::string &) const;
```
##### Arguments
@@ -354,7 +401,7 @@ Can be either:
* a `buffer` with specified `size` (this includes the zero-terminator)
* an implementation of `Print` (like `Serial`, `EthernetClient`...)
* a `String`
* a `String` or `std::string`
##### Return value
@@ -395,6 +442,7 @@ This will create a compact JSON, if you want a pretty JSON with spaces and line
size_t printTo(char* buffer, size_t size) const;
size_t printTo(Print &) const;
size_t printTo(String &) const;
size_t printTo(std::string &) const;
```
##### Arguments
@@ -405,7 +453,7 @@ Can be either:
* a `buffer` with specified `size` (this includes the zero-terminator)
* an implementation of `Print` (like `Serial`, `EthernetClient`...)
* a `String`
* a `String` or `std::string`
##### Return value
@@ -476,21 +524,22 @@ Sets the value at specified index.
```c++
bool set(size_t index, bool value);
bool set(size_t index, float value, uint8_t decimals = 2);
bool set(size_t index, double value, uint8_t decimals = 2);
bool set(size_t index, signed char value);
bool set(size_t index, signed long value);
bool set(size_t index, signed int value);
bool set(size_t index, signed short value);
bool set(size_t index, unsigned char value);
bool set(size_t index, unsigned long value);
bool set(size_t index, unsigned int value);
bool set(size_t index, unsigned short value);
bool set(size_t index, const char *value);
bool set(size_t index, const JsonVariant &value);
bool set(size_t index, const std::string &value); // see Remarks
bool set(size_t index, const String &value); // see Remarks
bool set(size_t index, double value, uint8_t decimals = 2);
bool set(size_t index, float value, uint8_t decimals = 2);
bool set(size_t index, JsonArray &array);
bool set(size_t index, JsonObject &object);
bool set(size_t index, const JsonVariant &value);
bool set(size_t index, signed char value);
bool set(size_t index, signed int value);
bool set(size_t index, signed long value);
bool set(size_t index, signed short value);
bool set(size_t index, unsigned char value);
bool set(size_t index, unsigned int value);
bool set(size_t index, unsigned long value);
bool set(size_t index, unsigned short value);
```
##### Arguments
@@ -507,9 +556,9 @@ bool set(size_t index, const JsonVariant &value);
##### Remarks
When you call `JsonArray::set(size_t, const String&)`, a copy of the string is made, causing the `JsonBuffer` to grow.
When you call `set(size_t, const String&)` or `set(size_t, const std::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.
To avoid this behavior, use `set(size_t, const char*)` instead.
##### Example
@@ -740,18 +789,29 @@ const char* world = object["hello"];
### JsonBuffer::strdup()
##### Description
Make a copy of the specified string.
##### Signatures
```c++
char* strdup(const char* str);
char* strdup(const String& str);
char* strdup(const std::string& str);
```
##### Arguments
`str`, the string to duplicate.
##### Return value
A newly allocate string, filled with a copy of `str`.
##### Example
```c++
StaticJsonBuffer<200> jsonBuffer;
char orig[16] = "hello";
@@ -897,6 +957,7 @@ Creates a `JsonObject` as a child of the current object.
```c++
JsonObject& createNestedObject(const char* key) const;
JsonObject& createNestedObject(const String& key) const; // <- duplicates key
JsonObject& createNestedObject(const std::string& key) const; // <- duplicates key
```
##### Arguments
@@ -905,7 +966,7 @@ JsonObject& createNestedObject(const String& key) const; // <- duplicates key
##### Remarks
When you add a value using a `String` for key, a copy of the string is made, causing the `JsonBuffer` to grow.
When you add a value using a `String` or a `std::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.
@@ -946,37 +1007,31 @@ Gets the value at the specified index.
##### Signature
```c++
// Non template version
JsonVariant get (JsonObjectKey key) const;
// Template version
bool get<bool> (JsonObjectKey key) const;
const char* get<const char*> (JsonObjectKey key) const;
double get<double> (JsonObjectKey key) const;
float get<float> (JsonObjectKey key) const;
signed char get<signed char> (JsonObjectKey key) const;
signed int get<signed int> (JsonObjectKey key) const;
signed long get<signed long> (JsonObjectKey key) const;
signed short get<signed short> (JsonObjectKey key) const;
String get<String> (JsonObjectKey key) const;
unsigned char get<unsigned char> (JsonObjectKey key) const;
unsigned int get<unsigned int> (JsonObjectKey key) const;
unsigned long get<unsigned long> (JsonObjectKey key) const;
unsigned short get<unsigned short> (JsonObjectKey key) const;
bool get<bool> (TString key) const;
const char* get<const char*> (TString key) const;
double get<double> (TString key) const;
float get<float> (TString key) const;
JsonVariant get<JsonVariant> (TString key) const;
signed char get<signed char> (TString key) const;
signed int get<signed int> (TString key) const;
signed long get<signed long> (TString key) const;
signed short get<signed short> (TString key) const;
std::string get<std::string> (TString key) const;
String get<String> (TString key) const;
unsigned char get<unsigned char> (TString key) const;
unsigned int get<unsigned int> (TString key) const;
unsigned long get<unsigned long> (TString key) const;
unsigned short get<unsigned short> (TString key) const;
```
##### Arguments
`key`: the key of the value in the object, can be a `const char*` or a `const String&`
`T`: the type of the value
`key`: the key of the value in the object, can be a `const char*`, a `String` or an `std::string`.
##### Return value
The value at the specified key. This can be a `JsonVariant` or a value of type `T`.
The template version of `get()` returns a value of the specified type.
In case of an error (key out of range or incompatible type), the default value of the type `T` is returned.
The value at the specified key, converted to the specified type.
In case of an error (key not found or incompatible type), the default value of the specified type is returned.
##### Example
@@ -1041,8 +1096,10 @@ A shortcut for `JsonObject::get()` and `JsonObject::set()`, with a map-like synt
```c++
JsonVariant& operator[](const char* key);
JsonVariant& operator[](const String& key);
const JsonVariant& operator[](const cahr* key) const;
JsonVariant& operator[](const std::string& key);
const JsonVariant& operator[](const char* key) const;
const JsonVariant& operator[](const String& key) const;
const JsonVariant& operator[](const std::string& key) const;
```
##### Arguments
@@ -1055,7 +1112,7 @@ 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.
When you add a value using a `String` or an `std::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.
@@ -1082,6 +1139,7 @@ This will create a "prettified" JSON, if you want a compact JSON without space o
size_t prettyPrintTo(char* buffer, size_t size) const;
size_t prettyPrintTo(Print &) const;
size_t prettyPrintTo(String &) const;
size_t prettyPrintTo(std::string &) const;
```
##### Arguments
@@ -1092,7 +1150,7 @@ Can be either:
* a `buffer` with specified `size` (this includes the zero-terminator)
* an implementation of `Print` (like `Serial`, `EthernetClient`...)
* a `String`
* a `String` or an `std::string`
##### Return value
@@ -1131,6 +1189,7 @@ This will create a compact JSON, if you want a pretty JSON with spaces and line
size_t printTo(char* buffer, size_t size) const;
size_t printTo(Print &) const;
size_t printTo(String &) const;
size_t printTo(std::string &) const;
```
##### Arguments
@@ -1141,7 +1200,7 @@ Can be either:
* a `buffer` with specified `size` (this includes the zero-terminator)
* an implementation of `Print` (like `Serial`, `EthernetClient`...)
* a `String`
* a `String` or an `std::string`
##### Return value
@@ -1176,6 +1235,7 @@ Removes the element at the specified key.
```c++
void remove(const char* key);
void remove(const String& key);
void remove(const std::string& key);
```
##### Arguments
@@ -1209,43 +1269,27 @@ Sets the value at specified key.
##### Signatures
```c++
bool set(const char* key, bool value);
bool set(const char* key, float value, uint8_t decimals = 2);
bool set(const char* key, double value, uint8_t decimals = 2);
bool set(const char* key, signed char value);
bool set(const char* key, signed long value);
bool set(const char* key, signed int value);
bool set(const char* key, signed short value);
bool set(const char* key, unsigned char value);
bool set(const char* key, unsigned long value);
bool set(const char* key, unsigned int value);
bool set(const char* key, unsigned short value);
bool set(const char* key, const char *value);
bool set(const char* key, const String &value); // see Remarks
bool set(const char* key, JsonArray &array);
bool set(const char* key, JsonObject &object);
bool set(const char* key, const JsonVariant &value);
bool set(const String& key, bool value); // see Remarks
bool set(const String& key, float value, uint8_t decimals = 2); // see Remarks
bool set(const String& key, double value, uint8_t decimals = 2); // see Remarks
bool set(const String& key, signed char value); // see Remarks
bool set(const String& key, signed long value); // see Remarks
bool set(const String& key, signed int value); // see Remarks
bool set(const String& key, signed short value); // see Remarks
bool set(const String& key, unsigned char value); // see Remarks
bool set(const String& key, unsigned long value); // see Remarks
bool set(const String& key, unsigned int value); // see Remarks
bool set(const String& key, unsigned short value); // see Remarks
bool set(const String& key, const char *value); // see Remarks
bool set(const String& key, const String &value); // see Remarks twice
bool set(const String& key, JsonArray &array); // see Remarks
bool set(const String& key, JsonObject &object); // see Remarks
bool set(const String& key, const JsonVariant &value); // see Remarks
bool set(TString key, bool value);
bool set(TString key, float value, uint8_t decimals = 2);
bool set(TString key, double value, uint8_t decimals = 2);
bool set(TString key, signed char value);
bool set(TString key, signed long value);
bool set(TString key, signed int value);
bool set(TString key, signed short value);
bool set(TString key, unsigned char value);
bool set(TString key, unsigned long value);
bool set(TString key, unsigned int value);
bool set(TString key, unsigned short value);
bool set(TString key, const char *value);
bool set(TString key, const String &value); // see Remarks
bool set(TString key, JsonArray &array);
bool set(TString key, JsonObject &object);
bool set(TString key, const JsonVariant &value);
```
##### Arguments
`key`: the key to attach the value to.
`key`: the key to attach the value to, can be a `const char*`, a `String` or an `std::string`.
`value`: the value to attach to the key.
@@ -1257,8 +1301,9 @@ bool set(const String& key, const JsonVariant &value); // see Remarks
##### Remarks
When you use a `String`, a copy of the string is made, causing the `JsonBuffer` to grow.
When you use a `String` or an `std::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.
This is true for both `key` and `value`.
To avoid this behavior, use `const char*` keys and values instead.
##### Example
@@ -1403,6 +1448,7 @@ unsigned __int64 as<unsigned __int64>() const; // <- may require ARDUINOJS
const char* as<char*>() const;
const char* as<const char*>() const;
String as<String>() const; // <- causes duplication of the string
std::string as<std::string>() const; // <- causes duplication of the string
JsonArray& as<JsonArray>() const;
JsonArray& as<JsonArray&>() const;