JSON基礎：包括組包的概念等

Github：DaveGamble/cJSON

https://github.com/DaveGamble/cJSON

文章目錄

• Github：DaveGamble/cJSON
• License
• Usage
• • Welcome to cJSON.
  • Building
  • • copying the source 復制源
    • CMake
    • Makefile
    • Vcpkg
  • Including cJSON
  • Data Structure
  • Working with the data structure 使用數據結構
  • • Basic types
    • Arrays
    • Objects
  • Parsing JSON 解析JSON串
  • Printing JSON 打印（遍歷）JSON串
  • Example 示例
  • • Printing 打印（序列化）發送端
    • • vs上測試
    • Parsing 解析（反序列化）接收端
    • • VS上測試（略）
  • Caveats 注意事項
  • • Zero Character
    • Character Encoding
    • C Standard
    • Floating Point Numbers
    • Deep Nesting Of Arrays And Objects 數組和對象的深度嵌套
    • Thread Safety
    • Case Sensitivity
    • Duplicate Object Members 重復的對象成員

License

omitted

Usage

Welcome to cJSON.

cJSON aims to be the dumbest possible parser that you can get your job done with. It’s a single file of C, and a single header file.

JSON is described best here: http://www.json.org/ It’s like XML, but fat-free. You use it to move data around, store things, or just generally represent your program’s state.

As a library, cJSON exists to take away as much legwork as it can, but not get in your way. As a point of pragmatism (i.e. ignoring the truth), I’m going to say that you can use it in one of two modes: Auto and Manual. Let’s have a quick run-through.

I lifted some JSON from this page: http://www.json.org/fatfree.html That page inspired me to write cJSON, which is a parser that tries to share the same philosophy as JSON itself. Simple, dumb, out of the way.

cJSON 旨在成為您可以完成工作的最愚蠢的解析器。 它是 C 的單個文件和單個頭文件。

JSON 在這里描述得最好：http://www.json.org/ 它類似于 XML，但沒有脂肪（意指不含多余的東西）。 你用它來移動數據，存儲東西，或者只是一般地代表你的程序的狀態。

作為一個庫，cJSON 的存在是為了帶走盡可能多的跑腿工作，但不會妨礙您。 作為實用主義的一點（即忽略事實），我會說您可以在以下兩種模式之一中使用它：自動和手動。 讓我們快速瀏覽一下。

我從這個頁面中提取了一些 JSON：http://www.json.org/fatfree.html 該頁面啟發了我編寫 cJSON，它是一個嘗試與 JSON 本身共享相同理念的解析器。 簡單，愚蠢，不礙事。

Building

There are several ways to incorporate cJSON into your project.

有幾種方法可以將 cJSON 合并到您的項目中。

copying the source 復制源

Because the entire library is only one C file and one header file, you can just copy cJSON.h and cJSON.c to your projects source and start using it.

cJSON is written in ANSI C (C89) in order to support as many platforms and compilers as possible.

因為整個庫只有一個 C 文件和一個頭文件，您只需將 cJSON.h 和 cJSON.c 復制到您的項目源并開始使用它即可。

cJSON 是用 ANSI C (C89) 編寫的，以便支持盡可能多的平臺和編譯器。

CMake

With CMake, cJSON supports a full blown build system. This way you get the most features. CMake with an equal or higher version than 2.8.5 is supported. With CMake it is recommended to do an out of tree build, meaning the compiled files are put in a directory separate from the source files. So in order to build cJSON with CMake on a Unix platform, make a build directory and run CMake inside it.

使用 CMake，cJSON 支持完整的構建系統。 這樣您就可以獲得最多的功能。 支持版本等于或高于 2.8.5 的 CMake。 使用 CMake 建議進行樹外構建，這意味著編譯后的文件放在與源文件不同的目錄中。 因此，為了在 Unix 平臺上使用 CMake 構建 cJSON，創建一個構建目錄并在其中運行 CMake。

mkdir build cd build cmake ..

This will create a Makefile and a bunch of other files. You can then compile it:

這將創建一個 Makefile 和一堆其他文件。 然后你可以編譯它：

make

And install it with make install if you want. By default it installs the headers /usr/local/include/cjson and the libraries to /usr/local/lib. It also installs files for pkg-config to make it easier to detect and use an existing installation of CMake. And it installs CMake config files, that can be used by other CMake based projects to discover the library.

You can change the build process with a list of different options that you can pass to CMake. Turn them on with On and off with Off:

如果需要，可以使用 make install 安裝它。 默認情況下，它將頭文件 /usr/local/include/cjson 和庫安裝到 /usr/local/lib。 它還為 pkg-config 安裝文件，以便更容易檢測和使用現有的 CMake 安裝。 它會安裝 CMake 配置文件，其他基于 CMake 的項目可以使用這些文件來發現庫。

您可以使用可以傳遞給 CMake 的不同選項列表來更改構建過程。 用 On 打開它們，用 Off 關閉它們：

• DENABLE_CJSON_TEST=On: Enable building the tests. (on by default)
• DENABLE_CJSON_UTILS=On: Enable building cJSON_Utils. (off by default)
• DENABLE_TARGET_EXPORT=On: Enable the export of CMake targets. Turn off if it makes problems. (on by default)
• DENABLE_CUSTOM_COMPILER_FLAGS=On: Enable custom compiler flags (currently for Clang, GCC and MSVC). Turn off if it makes problems. (on by default)
• DENABLE_VALGRIND=On: Run tests with valgrind. (off by default)
• DENABLE_SANITIZERS=On: Compile cJSON with AddressSanitizer and UndefinedBehaviorSanitizer enabled (if possible). (off by default)
• DENABLE_SAFE_STACK: Enable the SafeStack instrumentation pass. Currently only works with the Clang compiler. (off by default)
• DBUILD_SHARED_LIBS=On: Build the shared libraries. (on by default)
• DBUILD_SHARED_AND_STATIC_LIBS=On: Build both shared and static libraries. (off by default)
• DCMAKE_INSTALL_PREFIX=/usr: Set a prefix for the installation.
• DENABLE_LOCALES=On: Enable the usage of localeconv method. ( on by default )
• DCJSON_OVERRIDE_BUILD_SHARED_LIBS=On: Enable overriding the value of BUILD_SHARED_LIBS with -DCJSON_BUILD_SHARED_LIBS.
• DENABLE_CJSON_VERSION_SO: Enable cJSON so version. ( on by default )
  If you are packaging cJSON for a distribution of Linux, you would probably take these steps for example:

mkdir build cd build cmake .. -DENABLE_CJSON_UTILS=On -DENABLE_CJSON_TEST=Off -DCMAKE_INSTALL_PREFIX=/usr make make DESTDIR=$pkgdir install

On Windows CMake is usually used to create a Visual Studio solution file by running it inside the Developer Command Prompt for Visual Studio, for exact steps follow the official documentation from CMake and Microsoft and use the online search engine of your choice. The descriptions of the the options above still generally apply, although not all of them work on Windows.

在 Windows 上，CMake 通常用于通過在 Visual Studio 的開發人員命令提示符中運行它來創建 Visual Studio 解決方案文件，具體步驟請遵循 CMake 和 Microsoft 的官方文檔并使用您選擇的在線搜索引擎。 上述選項的描述仍然普遍適用，盡管并非所有選項都適用于 Windows。

Makefile

NOTE: This Method is deprecated. Use CMake if at all possible. Makefile support is limited to fixing bugs.

If you don’t have CMake available, but still have GNU make. You can use the makefile to build cJSON:

Run this command in the directory with the source code and it will automatically compile static and shared libraries and a little test program (not the full test suite).

注意：此方法已棄用。 盡可能使用 CMake。 Makefile 支持僅限于修復錯誤。

如果您沒有可用的 CMake，但仍有 GNU make。 您可以使用 makefile 構建 cJSON：

在包含源代碼的目錄中運行此命令，它將自動編譯靜態和共享庫以及一個小測試程序（不是完整的測試套件）。

make all

If you want, you can install the compiled library to your system using make install. By default it will install the headers in /usr/local/include/cjson and the libraries in /usr/local/lib. But you can change this behavior by setting the PREFIX and DESTDIR variables: make PREFIX=/usr DESTDIR=temp install. And uninstall them with: make PREFIX=/usr DESTDIR=temp uninstall.

如果需要，可以使用 make install 將編譯后的庫安裝到系統中。 默認情況下，它會將頭文件安裝在 /usr/local/include/cjson 中，并將庫安裝在 /usr/local/lib 中。 但是您可以通過設置 PREFIX 和 DESTDIR 變量來更改此行為：make PREFIX=/usr DESTDIR=temp install。 并使用以下命令卸載它們：make PREFIX=/usr DESTDIR=temp uninstall。

Vcpkg

You can download and install cJSON using the vcpkg dependency manager:

您可以使用 vcpkg 依賴管理器下載并安裝 cJSON：

git clone https://github.com/Microsoft/vcpkg.git cd vcpkg ./bootstrap-vcpkg.sh ./vcpkg integrate install vcpkg install cjson

The cJSON port in vcpkg is kept up to date by Microsoft team members and community contributors. If the version is out of date, please create an issue or pull request on the vcpkg repository.

vcpkg 中的 cJSON 端口由 Microsoft 團隊成員和社區貢獻者保持最新。 如果版本過期，請在 vcpkg 存儲庫上創建問題或拉取請求。

Including cJSON

If you installed it via CMake or the Makefile, you can include cJSON like this:

如果你通過 CMake 或 Makefile 安裝它，你可以像這樣包含 cJSON：

#include <cjson/cJSON.h>

Data Structure

cJSON represents JSON data using the cJSON struct data type:

cJSON 使用 cJSON 結構體數據類型來表示 JSON 數據：

/* The cJSON structure: */ typedef struct cJSON {struct cJSON *next;struct cJSON *prev;struct cJSON *child;int type;char *valuestring;/* writing to valueint is DEPRECATED, use cJSON_SetNumberValue instead */int valueint;double valuedouble;char *string; } cJSON;

An item of this type represents a JSON value. The type is stored in type as a bit-flag (this means that you cannot find out the type by just comparing the value of type).

To check the type of an item, use the corresponding cJSON_Is… function. It does a NULL check followed by a type check and returns a boolean value if the item is of this type.

The type can be one of the following:

此類型的項目表示 JSON 值。 類型作為位標志存儲在類型中（這意味著您無法僅通過比較類型的值來找出類型）。

要檢查項目的類型，請使用相應的 cJSON_Is… 函數。 它先進行 NULL 檢查，然后進行類型檢查，如果項目屬于這種類型，則返回一個布爾值。

類型可以是以下之一：

• cJSON_Invalid (check with cJSON_IsInvalid): Represents an invalid item that doesn’t contain any value. You automatically have this type if you set the item to all zero bytes.
• cJSON_False (check with cJSON_IsFalse): Represents a false boolean value. You can also check for boolean values in general with cJSON_IsBool.
• cJSON_True (check with cJSON_IsTrue): Represents a true boolean value. You can also check for boolean values in general with cJSON_IsBool.
• cJSON_NULL (check with cJSON_IsNull): Represents a null value.
• cJSON_Number (check with cJSON_IsNumber): Represents a number value. The value is stored as a double in valuedouble and also in valueint. If the number is outside of the range of an integer, INT_MAX or INT_MIN are used for valueint.
• cJSON_String (check with cJSON_IsString): Represents a string value. It is stored in the form of a zero terminated string in valuestring.
• cJSON_Array (check with cJSON_IsArray): Represent an array value. This is implemented by pointing child to a linked list of cJSON items that represent the values in the array. The elements are linked together using next and prev, where the first element has prev.next == NULL and the last element next == NULL.
• cJSON_Object (check with cJSON_IsObject): Represents an object value. Objects are stored same way as an array, the only difference is that the items in the object store their keys in string.
• cJSON_Raw (check with cJSON_IsRaw): Represents any kind of JSON that is stored as a zero terminated array of characters in valuestring. This can be used, for example, to avoid printing the same static JSON over and over again to save performance. cJSON will never create this type when parsing. Also note that cJSON doesn’t check if it is valid JSON.

---

• cJSON_Invalid（使用 cJSON_IsInvalid 檢查）：表示不包含任何值的無效項。如果您將項目設置為全零字節，您將自動擁有此類型。
• cJSON_False（檢查 cJSON_IsFalse）：表示一個假布爾值。您還可以使用 cJSON_IsBool 通常檢查布爾值。
• cJSON_True（檢查 cJSON_IsTrue）：表示一個真正的布爾值。您還可以使用 cJSON_IsBool 通常檢查布爾值。
• cJSON_NULL（檢查 cJSON_IsNull）：表示空值。
• cJSON_Number（檢查 cJSON_IsNumber）：表示一個數字值。該值作為雙精度值存儲在 valuedouble 和 valueint 中。如果數字超出整數范圍，則將 INT_MAX 或 INT_MIN 用于 valueint。
• cJSON_String（檢查 cJSON_IsString）：表示一個字符串值。它以 valuestring 中以零結尾的字符串的形式存儲。
• cJSON_Array（檢查 cJSON_IsArray）：表示一個數組值。這是通過將 child 指向表示數組中的值的 cJSON 項的鏈接列表來實現的。元素使用 next 和 prev 鏈接在一起，其中第一個元素具有 prev.next == NULL，最后一個元素具有 next == NULL。
• cJSON_Object（檢查 cJSON_IsObject）：表示一個對象值。對象的存儲方式與數組相同，唯一的區別是對象中的項目將它們的鍵存儲在字符串中。
• cJSON_Raw（使用 cJSON_IsRaw 檢查）：表示任何類型的 JSON，存儲為 valuestring 中以零結尾的字符數組。例如，這可以用來避免一遍又一遍地打印相同的靜態 JSON 以節省性能。 cJSON 在解析時永遠不會創建這種類型。另請注意，cJSON 不會檢查它是否是有效的 JSON。

Additionally there are the following two flags:

此外，還有以下兩個標志：

• cJSON_IsReference: Specifies that the item that child points to and/or valuestring is not owned by this item, it is only a reference. So cJSON_Delete and other functions will only deallocate this item, not its child/valuestring.

• cJSON_StringIsConst: This means that string points to a constant string. This means that cJSON_Delete and other functions will not try to deallocate string.

• cJSON_IsReference：指定 child 指向的項目和/或 valuestring 不屬于該項目，它只是一個引用。 所以 cJSON_Delete 和其他函數只會釋放這個 item，而不是它的 child/valuestring。

• cJSON_StringIsConst：這意味著字符串指向一個常量字符串。 這意味著 cJSON_Delete 和其他函數不會嘗試釋放字符串。

Working with the data structure 使用數據結構

For every value type there is a cJSON_Create… function that can be used to create an item of that type. All of these will allocate a cJSON struct that can later be deleted with cJSON_Delete. Note that you have to delete them at some point, otherwise you will get a memory leak.
Important: If you have added an item to an array or an object already, you mustn’t delete it with cJSON_Delete. Adding it to an array or object transfers its ownership so that when that array or object is deleted, it gets deleted as well. You also could use cJSON_SetValuestring to change a cJSON_String’s valuestring, and you needn’t to free the previous valuestring manually.

對于每個值類型，都有一個 cJSON_Create… 函數可用于創建該類型的項目。 所有這些都將分配一個 cJSON 結構，以后可以使用 cJSON_Delete 刪除該結構。 請注意，您必須在某些時候刪除它們，否則您會出現內存泄漏。
重要提示：如果您已經將項目添加到數組或對象中，則不得使用 cJSON_Delete 將其刪除。 將其添加到數組或對象會轉移其所有權，因此當刪除該數組或對象時，它也會被刪除。 您也可以使用 cJSON_SetValuestring 來更改 cJSON_String 的 valuestring，并且您不需要手動釋放以前的 valuestring。

Basic types

• null is created with cJSON_CreateNull

• booleans are created with cJSON_CreateTrue, cJSON_CreateFalse or cJSON_CreateBool

• numbers are created with cJSON_CreateNumber. This will set both valuedouble and valueint. If the number is outside of the range of an integer, INT_MAX or INT_MIN are used for valueint

• strings are created with cJSON_CreateString (copies the string) or with cJSON_CreateStringReference (directly points to the string. This means that valuestring won’t be deleted by cJSON_Delete and you are responsible for its lifetime, useful for constants)

• 使用 cJSON_CreateNull 創建 null

• 使用 cJSON_CreateTrue、cJSON_CreateFalse 或 cJSON_CreateBool 創建布爾值

• 數字是用 cJSON_CreateNumber 創建的。 這將設置 valuedouble 和 valueint。 如果數字超出整數范圍，則使用 INT_MAX 或 INT_MIN 作為 valueint

• 使用 cJSON_CreateString（復制字符串）或使用 cJSON_CreateStringReference（直接指向字符串。這意味著 valuestring 不會被 cJSON_Delete 刪除，并且您負責它的生命周期，對常量有用）創建字符串

Arrays

You can create an empty array with cJSON_CreateArray. cJSON_CreateArrayReference can be used to create an array that doesn’t “own” its content, so its content doesn’t get deleted by cJSON_Delete.

To add items to an array, use cJSON_AddItemToArray to append items to the end. Using cJSON_AddItemReferenceToArray an element can be added as a reference to another item, array or string. This means that cJSON_Delete will not delete that items child or valuestring properties, so no double frees are occurring if they are already used elsewhere. To insert items in the middle, use cJSON_InsertItemInArray. It will insert an item at the given 0 based index and shift all the existing items to the right.

If you want to take an item out of an array at a given index and continue using it, use cJSON_DetachItemFromArray, it will return the detached item, so be sure to assign it to a pointer, otherwise you will have a memory leak.

Deleting items is done with cJSON_DeleteItemFromArray. It works like cJSON_DetachItemFromArray, but deletes the detached item via cJSON_Delete.

You can also replace an item in an array in place. Either with cJSON_ReplaceItemInArray using an index or with cJSON_ReplaceItemViaPointer given a pointer to an element. cJSON_ReplaceItemViaPointer will return 0 if it fails. What this does internally is to detach the old item, delete it and insert the new item in its place.

To get the size of an array, use cJSON_GetArraySize. Use cJSON_GetArrayItem to get an element at a given index.

Because an array is stored as a linked list, iterating it via index is inefficient (O(n2)), so you can iterate over an array using the cJSON_ArrayForEach macro in O(n) time complexity.

您可以使用 cJSON_CreateArray 創建一個空數組。 cJSON_CreateArrayReference 可用于創建不“擁有”其內容的數組，因此其內容不會被 cJSON_Delete 刪除。

要將項目添加到數組，請使用 cJSON_AddItemToArray 將項目附加到末尾。使用 cJSON_AddItemReferenceToArray 可以將元素添加為對另一個項目、數組或字符串的引用。這意味著 cJSON_Delete 不會刪除該項目的子屬性或 valuestring 屬性，因此如果它們已在其他地方使用，則不會發生雙重釋放。要在中間插入項目，請使用 cJSON_InsertItemInArray。它將在給定的基于 0 的索引處插入一個項目，并將所有現有項目向右移動。

如果要從給定索引處的數組中取出一個項目并繼續使用它，請使用 cJSON_DetachItemFromArray，它將返回分離的項目，因此請務必將其分配給指針，否則會出現內存泄漏。

使用 cJSON_DeleteItemFromArray 刪除項目。它的工作方式類似于 cJSON_DetachItemFromArray，但通過 cJSON_Delete 刪除分離的項目。

您還可以就地替換數組中的項目。使用 cJSON_ReplaceItemInArray 使用索引或使用 cJSON_ReplaceItemViaPointer 給定指向元素的指針。如果失敗，cJSON_ReplaceItemViaPointer 將返回 0。這在內部所做的是分離舊項目，將其刪除并在其位置插入新項目。

要獲取數組的大小，請使用 cJSON_GetArraySize。使用 cJSON_GetArrayItem 獲取給定索引處的元素。

因為數組存儲為鏈表，所以通過索引對其進行迭代是低效的 (O(n2))，因此您可以使用 cJSON_ArrayForEach 宏以 O(n) 的時間復雜度迭代數組。

Objects

You can create an empty object with cJSON_CreateObject. cJSON_CreateObjectReference can be used to create an object that doesn’t “own” its content, so its content doesn’t get deleted by cJSON_Delete.

To add items to an object, use cJSON_AddItemToObject. Use cJSON_AddItemToObjectCS to add an item to an object with a name that is a constant or reference (key of the item, string in the cJSON struct), so that it doesn’t get freed by cJSON_Delete. Using cJSON_AddItemReferenceToArray an element can be added as a reference to another object, array or string. This means that cJSON_Delete will not delete that items child or valuestring properties, so no double frees are occurring if they are already used elsewhere.

If you want to take an item out of an object, use cJSON_DetachItemFromObjectCaseSensitive, it will return the detached item, so be sure to assign it to a pointer, otherwise you will have a memory leak.

Deleting items is done with cJSON_DeleteItemFromObjectCaseSensitive. It works like cJSON_DetachItemFromObjectCaseSensitive followed by cJSON_Delete.

You can also replace an item in an object in place. Either with cJSON_ReplaceItemInObjectCaseSensitive using a key or with cJSON_ReplaceItemViaPointer given a pointer to an element. cJSON_ReplaceItemViaPointer will return 0 if it fails. What this does internally is to detach the old item, delete it and insert the new item in its place.

To get the size of an object, you can use cJSON_GetArraySize, this works because internally objects are stored as arrays.

If you want to access an item in an object, use cJSON_GetObjectItemCaseSensitive.

To iterate over an object, you can use the cJSON_ArrayForEach macro the same way as for arrays.

cJSON also provides convenient helper functions for quickly creating a new item and adding it to an object, like cJSON_AddNullToObject. They return a pointer to the new item or NULL if they failed.

您可以使用 cJSON_CreateObject 創建一個空對象。 cJSON_CreateObjectReference 可用于創建不“擁有”其內容的對象，因此其內容不會被 cJSON_Delete 刪除。

要將項目添加到對象，請使用 cJSON_AddItemToObject。使用 cJSON_AddItemToObjectCS 將項目添加到名稱為常量或引用的對象（項目的鍵，cJSON 結構中的字符串），這樣它就不會被 cJSON_Delete 釋放。使用 cJSON_AddItemReferenceToArray 可以將元素添加為對另一個對象、數組或字符串的引用。這意味著 cJSON_Delete 不會刪除該項目的子屬性或 valuestring 屬性，因此如果它們已在其他地方使用，則不會發生雙重釋放。

如果你想從一個對象中取出一個item，使用cJSON_DetachItemFromObjectCaseSensitive，它會返回分離后的item，所以一定要給它賦值給一個指針，否則會出現內存泄漏。

使用 cJSON_DeleteItemFromObjectCaseSensitive 刪除項目。它的工作方式類似于 cJSON_DetachItemFromObjectCaseSensitive 后跟 cJSON_Delete。

您還可以就地替換對象中的項目。使用 cJSON_ReplaceItemInObjectCaseSensitive 使用鍵或使用 cJSON_ReplaceItemViaPointer 給定指向元素的指針。如果失敗，cJSON_ReplaceItemViaPointer 將返回 0。這在內部所做的是分離舊項目，將其刪除并在其位置插入新項目。

要獲取對象的大小，可以使用 cJSON_GetArraySize，這是因為內部對象存儲為數組。

如果要訪問對象中的項目，請使用 cJSON_GetObjectItemCaseSensitive。

要迭代對象，您可以使用 cJSON_ArrayForEach 宏，方法與數組相同。

cJSON 還提供了方便的幫助函數，用于快速創建新項目并將其添加到對象中，例如 cJSON_AddNullToObject。它們返回指向新項目的指針，如果失敗則返回 NULL。

Parsing JSON 解析JSON串

Given some JSON in a zero terminated string, you can parse it with cJSON_Parse.

給定零終止字符串中的一些 JSON，您可以使用 cJSON_Parse 對其進行解析。

cJSON *json = cJSON_Parse(string);

Given some JSON in a string (whether zero terminated or not), you can parse it with cJSON_ParseWithLength.

給定字符串中的一些 JSON（無論是否以零結尾），您可以使用 cJSON_ParseWithLength 對其進行解析。

cJSON *json = cJSON_ParseWithLength(string, buffer_length);

It will parse the JSON and allocate a tree of cJSON items that represents it. Once it returns, you are fully responsible for deallocating it after use with cJSON_Delete.

The allocator used by cJSON_Parse is malloc and free by default but can be changed (globally) with cJSON_InitHooks.

If an error occurs a pointer to the position of the error in the input string can be accessed using cJSON_GetErrorPtr. Note though that this can produce race conditions in multithreading scenarios, in that case it is better to use cJSON_ParseWithOpts with return_parse_end. By default, characters in the input string that follow the parsed JSON will not be considered as an error.

If you want more options, use cJSON_ParseWithOpts(const char *value, const char **return_parse_end, cJSON_bool require_null_terminated). return_parse_end returns a pointer to the end of the JSON in the input string or the position that an error occurs at (thereby replacing cJSON_GetErrorPtr in a thread safe way). require_null_terminated, if set to 1 will make it an error if the input string contains data after the JSON.

If you want more options giving buffer length, use cJSON_ParseWithLengthOpts(const char *value, size_t buffer_length, const char **return_parse_end, cJSON_bool require_null_terminated).

它將解析 JSON 并分配代表它的 cJSON 項目樹。一旦它返回，您將完全負責在與 cJSON_Delete 一起使用后釋放它。

cJSON_Parse 使用的分配器是 malloc 并且默認情況下是釋放的，但可以使用 cJSON_InitHooks （全局）更改。

如果發生錯誤，則可以使用 cJSON_GetErrorPtr 訪問指向輸入字符串中錯誤位置的指針。請注意，盡管這可能會在多線程場景中產生競爭條件，但在這種情況下，最好將 cJSON_ParseWithOpts 與 return_parse_end 一起使用。默認情況下，解析后的 JSON 后面的輸入字符串中的字符不會被視為錯誤。

如果您需要更多選項，請使用 cJSON_ParseWithOpts(const char *value, const char **return_parse_end, cJSON_bool require_null_terminated)。 return_parse_end 返回一個指針，指向輸入字符串中 JSON 的結尾或發生錯誤的位置（從而以線程安全的方式替換 cJSON_GetErrorPtr）。 require_null_terminated，如果設置為 1，如果輸入字符串包含 JSON 之后的數據，則會出錯。

如果您想要更多選項來提供緩沖區長度，請使用 cJSON_ParseWithLengthOpts(const char *value, size_t buffer_length, const char **return_parse_end, cJSON_bool require_null_terminated)。

Printing JSON 打印（遍歷）JSON串

Given a tree of cJSON items, you can print them as a string using cJSON_Print.

char *string = cJSON_Print(json);

It will allocate a string and print a JSON representation of the tree into it. Once it returns, you are fully responsible for deallocating it after use with your allocator. (usually free, depends on what has been set with cJSON_InitHooks).

cJSON_Print will print with whitespace for formatting. If you want to print without formatting, use cJSON_PrintUnformatted.

If you have a rough idea of how big your resulting string will be, you can use cJSON_PrintBuffered(const cJSON *item, int prebuffer, cJSON_bool fmt). fmt is a boolean to turn formatting with whitespace on and off. prebuffer specifies the first buffer size to use for printing. cJSON_Print currently uses 256 bytes for its first buffer size. Once printing runs out of space, a new buffer is allocated and the old gets copied over before printing is continued.

These dynamic buffer allocations can be completely avoided by using cJSON_PrintPreallocated(cJSON *item, char *buffer, const int length, const cJSON_bool format). It takes a buffer to a pointer to print to and its length. If the length is reached, printing will fail and it returns 0. In case of success, 1 is returned. Note that you should provide 5 bytes more than is actually needed, because cJSON is not 100% accurate in estimating if the provided memory is enough.

它將分配一個字符串并將樹的 JSON 表示打印到其中。一旦它返回，您將完全負責在使用分配器后釋放它。 （通常是釋放的，取決于 cJSON_InitHooks 的設置）。

cJSON_Print 將打印帶有空格以進行格式化。如果要在不格式化的情況下打印，請使用 cJSON_PrintUnformatted。

如果您大致了解生成的字符串有多大，可以使用 cJSON_PrintBuffered(const cJSON *item, int prebuffer, cJSON_bool fmt)。 fmt 是一個布爾值，用于打開和關閉空格格式。 prebuffer 指定用于打印的第一個緩沖區大小。 cJSON_Print 當前使用 256 字節作為其第一個緩沖區大小。一旦打印空間用完，就會分配一個新的緩沖區，并在繼續打印之前復制舊的緩沖區。

使用 cJSON_PrintPreallocated(cJSON *item, char *buffer, const int length, const cJSON_bool format) 可以完全避免這些動態緩沖區分配。它需要一個緩沖區指向要打印到的指針及其長度。如果達到長度，則打印失敗并返回 0。如果成功，則返回 1。請注意，您應該比實際需要多提供 5 個字節，因為 cJSON 在估計提供的內存是否足夠時并不是 100% 準確的。

Example 示例

In this example we want to build and parse the following JSON:

在此示例中，我們要構建和解析以下 JSON：

{"name": "Awesome 4K","resolutions": [{"width": 1280,"height": 720},{"width": 1920,"height": 1080},{"width": 3840,"height": 2160}] }

Printing 打印（序列化）發送端

Let’s build the above JSON and print it to a string:

讓我們構建上面的 JSON 并將其打印為字符串：

//create a monitor with a list of supported resolutions 使用支持的分辨率列表創建監視器 //NOTE: Returns a heap allocated string, you are required to free it after use. 注意：返回一個堆分配的字符串，您需要在使用后釋放它。 char *create_monitor(void) {const unsigned int resolution_numbers[3][2] = {{1280, 720},{1920, 1080},{3840, 2160}};char *string = NULL;cJSON *name = NULL;cJSON *resolutions = NULL;cJSON *resolution = NULL;cJSON *width = NULL;cJSON *height = NULL;size_t index = 0;cJSON *monitor = cJSON_CreateObject();if (monitor == NULL){goto end;}name = cJSON_CreateString("Awesome 4K");if (name == NULL){goto end;}/* after creation was successful, immediately add it to the monitor,* thereby transferring ownership of the pointer to it 創建成功后，立即將其添加到監視器中，從而將指針的所有權轉移給它*/cJSON_AddItemToObject(monitor, "name", name);resolutions = cJSON_CreateArray();if (resolutions == NULL){goto end;}cJSON_AddItemToObject(monitor, "resolutions", resolutions);for (index = 0; index < (sizeof(resolution_numbers) / (2 * sizeof(int))); ++index){resolution = cJSON_CreateObject();if (resolution == NULL){goto end;}cJSON_AddItemToArray(resolutions, resolution);width = cJSON_CreateNumber(resolution_numbers[index][0]);if (width == NULL){goto end;}cJSON_AddItemToObject(resolution, "width", width);height = cJSON_CreateNumber(resolution_numbers[index][1]);if (height == NULL){goto end;}cJSON_AddItemToObject(resolution, "height", height);}string = cJSON_Print(monitor);if (string == NULL){fprintf(stderr, "Failed to print monitor.\n");}end:cJSON_Delete(monitor);return string; }

Alternatively we can use the cJSON_Add…ToObject helper functions to make our lives a little easier:

或者，我們可以使用 cJSON_Add…ToObject 輔助函數讓我們的生活更輕松一些：（簡化代碼）

//NOTE: Returns a heap allocated string, you are required to free it after use. 注意：返回一個堆分配的字符串，您需要在使用后釋放它。 char *create_monitor_with_helpers(void) {const unsigned int resolution_numbers[3][2] = {{1280, 720},{1920, 1080},{3840, 2160}};char *string = NULL;cJSON *resolutions = NULL;size_t index = 0;cJSON *monitor = cJSON_CreateObject();if (cJSON_AddStringToObject(monitor, "name", "Awesome 4K") == NULL){goto end;}resolutions = cJSON_AddArrayToObject(monitor, "resolutions");if (resolutions == NULL){goto end;}for (index = 0; index < (sizeof(resolution_numbers) / (2 * sizeof(int))); ++index){cJSON *resolution = cJSON_CreateObject();if (cJSON_AddNumberToObject(resolution, "width", resolution_numbers[index][0]) == NULL){goto end;}if (cJSON_AddNumberToObject(resolution, "height", resolution_numbers[index][1]) == NULL){goto end;}cJSON_AddItemToArray(resolutions, resolution);}string = cJSON_Print(monitor);if (string == NULL){fprintf(stderr, "Failed to print monitor.\n");}end:cJSON_Delete(monitor);return string; }

vs上測試

#pragma warning(disable : 4996) #include <stdio.h> //#include <string.h> #include "cJSON.h"//create a monitor with a list of supported resolutions //NOTE: Returns a heap allocated string, you are required to free it after use. char* create_monitor(void) {const unsigned int resolution_numbers[3][2] = {{1280, 720},{1920, 1080},{3840, 2160}};char* string = NULL;cJSON* name = NULL;cJSON* resolutions = NULL;cJSON* resolution = NULL;cJSON* width = NULL;cJSON* height = NULL;size_t index = 0;cJSON* monitor = cJSON_CreateObject();if (monitor == NULL){goto end;}name = cJSON_CreateString("Awesome 4K");if (name == NULL){goto end;}/* after creation was successful, immediately add it to the monitor,* thereby transferring ownership of the pointer to it */cJSON_AddItemToObject(monitor, "name", name);resolutions = cJSON_CreateArray();if (resolutions == NULL){goto end;}cJSON_AddItemToObject(monitor, "resolutions", resolutions);for (index = 0; index < (sizeof(resolution_numbers) / (2 * sizeof(int))); ++index){resolution = cJSON_CreateObject();if (resolution == NULL){goto end;}cJSON_AddItemToArray(resolutions, resolution);width = cJSON_CreateNumber(resolution_numbers[index][0]);if (width == NULL){goto end;}cJSON_AddItemToObject(resolution, "width", width);height = cJSON_CreateNumber(resolution_numbers[index][1]);if (height == NULL){goto end;}cJSON_AddItemToObject(resolution, "height", height);}string = cJSON_Print(monitor);if (string == NULL){fprintf(stderr, "Failed to print monitor.\n");}end:cJSON_Delete(monitor);return string; }char cameraID_[64] = "DS-2XA7247F-IZS20211230AACHJ33724864"; char algorithmName_[64] = "安全帽算法"; int algorithmCategory_ = 0; char alarmMessage_[1024] = "NULL"; char alarmImage_[1024] = "/capture_picture/DS-2XA7247F-IZS20211230AACHJ33724864_202203290910102233.jpg"; char alarmTime_[64] = "2022-02-01 10:12:01";char* create_alarm_info(void) {char* string = NULL;cJSON* cameraID = NULL;cJSON* algorithmName = NULL;cJSON* algorithmCategory = NULL;cJSON* alarmMessage = NULL;cJSON* alarmImage = NULL;cJSON* alarmTime = NULL;cJSON* alarm_info = cJSON_CreateObject();if (alarm_info == NULL){goto end;}//1 cameraIDcameraID = cJSON_CreateString(cameraID_);if (cameraID == NULL){goto end;}cJSON_AddItemToObject(alarm_info, "cameraID", cameraID);//2 algorithmNamealgorithmName = cJSON_CreateString(algorithmName_);if (algorithmName == NULL){goto end;}cJSON_AddItemToObject(alarm_info, "algorithmName", algorithmName);//3 algorithmCategoryalgorithmCategory = cJSON_CreateNumber(algorithmCategory_);if (algorithmCategory == NULL){goto end;}cJSON_AddItemToObject(alarm_info, "algorithmCategory", algorithmCategory);//4 alarmMessagealarmMessage = cJSON_CreateString(alarmMessage_);if (alarmMessage == NULL){goto end;}cJSON_AddItemToObject(alarm_info, "alarmMessage", alarmMessage);//5 alarmImagealarmImage = cJSON_CreateString(alarmImage_);if (alarmImage == NULL){goto end;}cJSON_AddItemToObject(alarm_info, "alarmImage", alarmImage);//6 alarmTimealarmTime = cJSON_CreateString(alarmTime_);if (alarmTime == NULL){goto end;}cJSON_AddItemToObject(alarm_info, "alarmTime", alarmTime);string = cJSON_Print(alarm_info);if (string == NULL){fprintf(stderr, "Failed to print alarm_info.\n");}end:cJSON_Delete(alarm_info);return string; }int main() {char* s = create_monitor();printf("%s\n", s);free(s);printf("%s\n", s); //亂碼，說明函數返回的指針是malloc開辟的空間，用完指針必須free，否則可能導致內存溢出char* y = create_alarm_info();printf("%s\n", y);free(y);printf("%s\n", y);printf("%s\n", cameraID_);return 0; }

運行結果：

{"name": "Awesome 4K","resolutions": [{"width": 1280,"height": 720}, {"width": 1920,"height": 1080}, {"width": 3840,"height": 2160}] } 葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺€ {"cameraID": "DS-2XA7247F-IZS20211230AACHJ33724864","algorithmName": "安全帽算法","algorithmCategory": 0,"alarmMessage": "NULL","alarmImage": "/capture_picture/DS-2XA7247F-IZS20211230AACHJ33724864_202203290910102233.jpg","alarmTime": "2022-02-01 10:12:01" } 葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺葺屯屯屯? DS-2XA7247F-IZS20211230AACHJ33724864

Parsing 解析（反序列化）接收端

In this example we will parse a JSON in the above format and check if the monitor supports a Full HD resolution while printing some diagnostic output:

在此示例中，我們將解析上述格式的 JSON，并在打印一些診斷輸出時檢查顯示器是否支持全高清分辨率：

/* return 1 if the monitor supports full hd, 0 otherwise 如果顯示器支持全高清則返回 1，否則返回 0 */ int supports_full_hd(const char * const monitor) {const cJSON *resolution = NULL;const cJSON *resolutions = NULL;const cJSON *name = NULL;int status = 0;cJSON *monitor_json = cJSON_Parse(monitor);if (monitor_json == NULL){const char *error_ptr = cJSON_GetErrorPtr();if (error_ptr != NULL){fprintf(stderr, "Error before: %s\n", error_ptr);}status = 0;goto end;}name = cJSON_GetObjectItemCaseSensitive(monitor_json, "name");if (cJSON_IsString(name) && (name->valuestring != NULL)){printf("Checking monitor \"%s\"\n", name->valuestring);}resolutions = cJSON_GetObjectItemCaseSensitive(monitor_json, "resolutions");cJSON_ArrayForEach(resolution, resolutions){cJSON *width = cJSON_GetObjectItemCaseSensitive(resolution, "width");cJSON *height = cJSON_GetObjectItemCaseSensitive(resolution, "height");if (!cJSON_IsNumber(width) || !cJSON_IsNumber(height)){status = 0;goto end;}if ((width->valuedouble == 1920) && (height->valuedouble == 1080)){status = 1;goto end;}}end:cJSON_Delete(monitor_json);return status; }

Note that there are no NULL checks except for the result of cJSON_Parse because cJSON_GetObjectItemCaseSensitive checks for NULL inputs already, so a NULL value is just propagated and cJSON_IsNumber and cJSON_IsString return 0 if the input is NULL.

請注意，除了 cJSON_Parse 的結果之外沒有任何 NULL 檢查，因為 cJSON_GetObjectItemCaseSensitive 已經檢查了 NULL 輸入，因此只是傳播 NULL 值，如果輸入為 NULL，則 cJSON_IsNumber 和 cJSON_IsString 返回 0。

VS上測試（略）

Caveats 注意事項

Zero Character

cJSON doesn’t support strings that contain the zero character ‘\0’ or \u0000. This is impossible with the current API because strings are zero terminated.

cJSON 不支持包含零字符 ‘\0’ 或 \u0000 的字符串。 這在當前的 API 中是不可能的，因為字符串是零終止的。

Character Encoding

cJSON only supports UTF-8 encoded input. In most cases it doesn’t reject invalid UTF-8 as input though, it just propagates it through as is. As long as the input doesn’t contain invalid UTF-8, the output will always be valid UTF-8.

cJSON 僅支持 UTF-8 編碼輸入。 在大多數情況下，它不會拒絕無效的 UTF-8 作為輸入，它只是按原樣傳播它。 只要輸入不包含無效的 UTF-8，輸出將始終是有效的 UTF-8。

C Standard

cJSON is written in ANSI C (or C89, C90). If your compiler or C library doesn’t follow this standard, correct behavior is not guaranteed.

NOTE: ANSI C is not C++ therefore it shouldn’t be compiled with a C++ compiler. You can compile it with a C compiler and link it with your C++ code however. Although compiling with a C++ compiler might work, correct behavior is not guaranteed.

cJSON 是用 ANSI C（或 C89、C90）編寫的。 如果您的編譯器或 C 庫不遵循此標準，則無法保證正確的行為。

注意：ANSI C 不是 C++，因此不應使用 C++ 編譯器對其進行編譯。 您可以使用 C 編譯器對其進行編譯，然后將其與您的 C++ 代碼鏈接。 盡管使用 C++ 編譯器進行編譯可能會起作用，但不能保證正確的行為。

Floating Point Numbers

cJSON does not officially support any double implementations other than IEEE754 double precision floating point numbers. It might still work with other implementations but bugs with these will be considered invalid.

The maximum length of a floating point literal that cJSON supports is currently 63 characters.

cJSON 不正式支持除 IEEE754 雙精度浮點數之外的任何雙精度實現。 它可能仍然適用于其他實現，但這些錯誤將被視為無效。

cJSON 支持的浮點文字的最大長度目前為 63 個字符。

Deep Nesting Of Arrays And Objects 數組和對象的深度嵌套

cJSON doesn’t support arrays and objects that are nested too deeply because this would result in a stack overflow. To prevent this cJSON limits the depth to CJSON_NESTING_LIMIT which is 1000 by default but can be changed at compile time.

cJSON 不支持嵌套太深的數組和對象，因為這會導致堆棧溢出。 為了防止這種情況，cJSON 將深度限制為 CJSON_NESTING_LIMIT，默認為 1000，但可以在編譯時更改。

Thread Safety

In general cJSON is not thread safe.

However it is thread safe under the following conditions:

cJSON_GetErrorPtr is never used (the return_parse_end parameter of cJSON_ParseWithOpts can be used instead)
cJSON_InitHooks is only ever called before using cJSON in any threads.
setlocale is never called before all calls to cJSON functions have returned.

一般來說，cJSON 不是線程安全的。

但是，它在以下條件下是線程安全的：

cJSON_GetErrorPtr 從不使用（可以使用 cJSON_ParseWithOpts 的 return_parse_end 參數代替）
cJSON_InitHooks 只會在任何線程中使用 cJSON 之前被調用。
在所有對 cJSON 函數的調用都返回之前，永遠不會調用 setlocale。

Case Sensitivity

When cJSON was originally created, it didn’t follow the JSON standard and didn’t make a distinction between uppercase and lowercase letters. If you want the correct, standard compliant, behavior, you need to use the CaseSensitive functions where available.

最初創建 cJSON 時，它沒有遵循 JSON 標準，也沒有區分大小寫字母。 如果您想要正確的、符合標準的行為，則需要在可用的情況下使用 CaseSensitive 函數。

Duplicate Object Members 重復的對象成員

cJSON supports parsing and printing JSON that contains objects that have multiple members with the same name. cJSON_GetObjectItemCaseSensitive however will always only return the first one.

cJSON 支持解析和打印包含具有多個同名成員的對象的 JSON。 但是，cJSON_GetObjectItemCaseSensitive 將始終只返回第一個。

總結

以上是生活随笔為你收集整理的cJSON使用教程（树外构建 out of tree build 概念）（组包概念）的全部內容，希望文章能夠幫你解決所遇到的問題。

如果覺得生活随笔網站內容還不錯，歡迎將生活随笔推薦給好友。