diff --git a/API-Reference.md b/API-Reference.md index ea89a76..f085e77 100644 --- a/API-Reference.md +++ b/API-Reference.md @@ -4,6 +4,12 @@ Some parts have been simplified to be easier to understand, so if you look at th +- [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 +## 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 (size_t index) const; const char* get (size_t index) const; double get (size_t index) const; float get (size_t index) const; +JsonVariant get (size_t index) const; signed char get (size_t index) const; signed int get (size_t index) const; signed long get (size_t index) const; signed short get (size_t index) const; +std::string get (size_t index) const; String get (size_t index) const; unsigned char get (size_t index) const; unsigned int get (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 (JsonObjectKey key) const; -const char* get (JsonObjectKey key) const; -double get (JsonObjectKey key) const; -float get (JsonObjectKey key) const; -signed char get (JsonObjectKey key) const; -signed int get (JsonObjectKey key) const; -signed long get (JsonObjectKey key) const; -signed short get (JsonObjectKey key) const; -String get (JsonObjectKey key) const; -unsigned char get (JsonObjectKey key) const; -unsigned int get (JsonObjectKey key) const; -unsigned long get (JsonObjectKey key) const; -unsigned short get (JsonObjectKey key) const; +bool get (TString key) const; +const char* get (TString key) const; +double get (TString key) const; +float get (TString key) const; +JsonVariant get (TString key) const; +signed char get (TString key) const; +signed int get (TString key) const; +signed long get (TString key) const; +signed short get (TString key) const; +std::string get (TString key) const; +String get (TString key) const; +unsigned char get (TString key) const; +unsigned int get (TString key) const; +unsigned long get (TString key) const; +unsigned short get (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() const; // <- may require ARDUINOJS const char* as() const; const char* as() const; String as() const; // <- causes duplication of the string +std::string as() const; // <- causes duplication of the string JsonArray& as() const; JsonArray& as() const;