diff --git a/doc/Memory model.md b/doc/Memory model.md index 8cfff483..45881744 100644 --- a/doc/Memory model.md +++ b/doc/Memory model.md @@ -5,11 +5,11 @@ Arduino JSON memory model ### Introducing `StaticJsonBuffer` -Arduino JSON uses a preallocated memory pool to store the object tree, this is done by the `StaticJsonBuffer`. +Arduino JSON uses a preallocated memory pool to store the object tree, this is done by the `StaticJsonBuffer` class. Before using any function of the library you need to create a `StaticJsonBuffer`. Then you can use this instance to create arrays and objects, or parse a JSON string. -`StaticJsonBuffer` has a template parameter that determines the number of bytes that it contains. For example, the following line create a `StaticJsonBuffer` containing 200 bytes on the stack: +`StaticJsonBuffer` has a template parameter that determines its capacity. For example, the following line create a `StaticJsonBuffer` with a capacity of 200 bytes: StaticJsonBuffer<200> jsonBuffer; @@ -28,27 +28,25 @@ In the first case, you know some constraints on the object tree. For instance, l {"sensor":"gps","time":1351824120,"data":[48.756080,2.302038]} -To determine the memory usage of this object tree, you use the two macros `JSON_ARRAY_SIZE(n)` `JSON_OBJECT_SIZE(n)`, both take the number of elements as a parameter. +To determine the memory usage of this object tree, you use the two macros `JSON_ARRAY_SIZE(n)` and `JSON_OBJECT_SIZE(n)`, both take the number of elements as an argument. For the example above, it would be: const int BUFFER_SIZE = JSON_OBJECT_SIZE(3) + JSON_ARRAY_SIZE(2); StaticJsonBuffer jsonBuffer; -In the second case, let's say you dynamically generate a JSON object tree of a random complexity so you can't put a limit base on that. But on the other hand, you don't want your program to crash because the object tree doesn't fit in memory. -The solution here is to determine how much memory is available, or in other words how much memory you can afford for the JSON generation. +In the second case, let's say you dynamically generate a JSON object tree of a random complexity so you can't put a limit based on that. But on the other hand, you don't want your program to crash because the object tree doesn't fit in memory. +The solution here is to determine how much memory is available, or in other words how much memory you can afford for the JSON object tree. ### Why choosing fixed allocation? -This fixed allocation approach may seem a bit strange, especially if your a desktop app developer used to dynamic allocation, but it make a lot of sense in an embedded context: +This fixed allocation approach may seem a bit strange, especially if your a desktop application developer used to dynamic allocation, but it make a lot of sense in an embedded context: 1. the code is smaller 2. it uses less memory 3. it doesn't create memory fragmentation 4. it predictable -Don't forget that, the memory is "freed" as soon as the `StaticJsonBuffer` is out of scope, like any other variable. It only hold the memory for a short amount of time. - -For that reason, you should never use a `StaticJsonBuffer` as a **global variable** because it would hold a lot of memory for the whole life of the program. +Don't forget that the memory is "freed" as soon as the `StaticJsonBuffer` is out of scope, like any other variable. It only hold the memory for a short amount of time. ## Memory usage diff --git a/doc/Migrating code to new API.md b/doc/Migrating code to new API.md index 71a96c48..f8e2721b 100644 --- a/doc/Migrating code to new API.md +++ b/doc/Migrating code to new API.md @@ -1,7 +1,7 @@ Migrating code written for Arduino JSON v3 to v4 ================================================ -Arduino JSON v4 was a major rewrite of the library, and the API change significantly. +Arduino JSON v4 was a major rewrite of the library, and the API changed significantly. ## Includes @@ -14,12 +14,6 @@ Arduino JSON v4 only has one: #include -Node: the header `src/ArduinoJson.h` is intended to be used within the Arduino IDE, if you're in another environment, you may need to include the following headers: - - #include - #include - #include - ## Namespaces Arduino JSON v3 had two namespaces: @@ -27,15 +21,12 @@ Arduino JSON v3 had two namespaces: using namespace ArduinoJson::Parser; using namespace ArduinoJson::Generator; -Arduino JSON v4 only has one: - - using namespace ArduinoJson; - -If you include the header `ArduinoJson.h` (recommended if in Arduino IDE), the `using` directivei is already done for you, so you don't have to write it. +Arduino JSON v4 doesn't require the `using namespace` statement. +It has a namespace but the `using namespace` is done in the header file. ## StaticJsonBuffer -Arduino JSON v3 had different memory allocation models for parser: +Arduino JSON v3 had different memory allocation models for the parser: JsonParser<16> parser; // 16 being the capacity in "tokens" @@ -44,18 +35,18 @@ and for the generator: JsonArray<4> array; // 4 being the number of element JsonObject<4> object; -Arduino JSON v4 only has one memory allocation mode: +Arduino JSON v4 only has one memory allocation model: StaticJsonBuffer<128> buffer; // 128 being the capacity in bytes ## Return values for the parser -Arduino JSON v3 returned `JsonArray` and `JsonObject`: +Arduino JSON v3 returned value types: JsonArray array = parser.parseArray(json); JsonObject object = parser.parseObject(json); -Arduino JSON v4 returns references: +Arduino JSON v4 returns references types: JsonArray& array = buffer.parseArray(json); JsonObject& object = buffer.parseObject(json); @@ -78,11 +69,11 @@ Note: you don't have to specify the capacity anymore. ## Printable interface -Arduino JSON v3 used to implement the Printable interface, that allowed that kind of statement: +Arduino JSON v3 used to implement the Printable interface, which allowed statements like: Serial.print(array); -Arduino JSON v4 doesn't, so you need to write this: +But Arduino JSON v4 doesn't, instead you need to write this: array.printTo(Serial);