bblanchon/ArduinoJson
1
0
Fork 1
mirror of https://github.com/bblanchon/ArduinoJson.git synced 2025-08-17 03:21:14 +02:00
Code Issues Packages Projects Releases Wiki Activity

Updated Avoiding pitfalls (markdown)

bblanchon
2014-11-29 07:47:54 -08:00
parent 3aa433c9a0
commit 368ba01cf5
1 changed files with 7 additions and 8 deletions
Download Patch File Download Diff File Expand all files Collapse all files

15
Avoiding pitfalls.md

@@ -1,11 +1,10 @@
Avoiding common pitfalls in Arduino JSON *This page contains precious information on how to avoid common pitfalls in Arduino JSON.*
========================================
As `StaticJsonBuffer` is the corner stone of this library, you'll see that every pitfall listed here are related to a wrong understanding of the memory model. As `StaticJsonBuffer` is the corner stone of this library, you'll see that every pitfall listed here are related to a wrong understanding of the memory model.
Make sure you read [Arduino JSON memory model](Memory model) before going further. Make sure you read [Arduino JSON memory model](Memory model) before going further.
## 1. Make `StaticJsonBuffer` big enough #### 1. Make `StaticJsonBuffer` big enough
By design, the library has no way to tell you why `parseArray()` or `parseObject()` failed. By design, the library has no way to tell you why `parseArray()` or `parseObject()` failed.
@@ -16,7 +15,7 @@ There are basically two reasons why they may fail:
So, if you are sure the JSON string is correct and you still can't parse it, you should try to increase the size of the `StaticJsonBuffer`. So, if you are sure the JSON string is correct and you still can't parse it, you should try to increase the size of the `StaticJsonBuffer`.
## 2. Make sure everything fits in memory #### 2. Make sure everything fits in memory
You may go into unpredictable trouble if you allocate more memory than your processor really has. You may go into unpredictable trouble if you allocate more memory than your processor really has.
It's a very common issue in embedded development. It's a very common issue in embedded development.
@@ -32,7 +31,7 @@ because it may be too big for a processor with only 2 KB: you need free memory t
That is why an 8-bit processor is not able to parse long and complex JSON strings. That is why an 8-bit processor is not able to parse long and complex JSON strings.
## 3. Keep the `StaticJsonBuffer` in memory long enough #### 3. Keep the `StaticJsonBuffer` in memory long enough
Remember that `StaticJsonBuffer`'s function return references. Remember that `StaticJsonBuffer`'s function return references.
References don't contain data, they are just pointer to the actual. References don't contain data, they are just pointer to the actual.
@@ -48,7 +47,7 @@ For example, don't do this:
because the local variable `buffer` will be *removed* from memory when the function `parseArray()` returns, and the `JsonArray&` will point to an invalid location. because the local variable `buffer` will be *removed* from memory when the function `parseArray()` returns, and the `JsonArray&` will point to an invalid location.
## 4. Don't reuse the same `StaticJsonBuffer` #### 4. Don't reuse the same `StaticJsonBuffer`
During is lifetime a `StaticJsonBuffer` growth until it's discarded. If you try to reuse the same instance several time, it will rapidly get full. During is lifetime a `StaticJsonBuffer` growth until it's discarded. If you try to reuse the same instance several time, it will rapidly get full.
@@ -56,7 +55,7 @@ For this reason, you should not use a global variable for your `StaticJsonBuffer
The best practice is to declare it in a local scope, so that it's discarded as soon as possible. My advice it to declare it in a function which unique role is to handle the JSON serialization. The best practice is to declare it in a local scope, so that it's discarded as soon as possible. My advice it to declare it in a function which unique role is to handle the JSON serialization.
## 5. Keep the JSON string in memory long enough #### 5. Keep the JSON string in memory long enough
The library never make memory duplication. The library never make memory duplication.
This has an important implication on string values, it means that the library will return pointer to chunks of the string. This has an important implication on string values, it means that the library will return pointer to chunks of the string.
@@ -73,7 +72,7 @@ For instance, let's imagine that you parse `["hello","world"]`, like this:
In that case, both `first` and `second` are pointers to the content of the original string `json`. In that case, both `first` and `second` are pointers to the content of the original string `json`.
So this will only work if `json` is still in memory. So this will only work if `json` is still in memory.
## 6. JSON string is altered #### 6. Make sure the string isn't read-only
If you read carefully the previous section, you may have come to the conclusion that the JSON parser modifies the JSON string. If you read carefully the previous section, you may have come to the conclusion that the JSON parser modifies the JSON string.