apiReference.md 6.2 KB
RyanJson API 说明（公开接口，使用导向）
范围
- 本页是公开 API 的语义速查，不展开内部实现优化细节。
- 场景化路径优先看
apiPatterns.md，所有权细节看ownershipAndErrors.md。 - hooks 与平台接入看
hooksInitPolicy.md、rtThreadExamples.md。
0. 初始化与配置
RyanJsonInitHooks(malloc, free, realloc)
- 必须最先调用。
- 成功返回
RyanJsonTrue，失败返回RyanJsonFalse。 - 失败后禁止继续调用 Parse/Create/Add/Replace/Print 等 API。
- 依据：当前实现的
jsonMalloc/jsonFree/jsonRealloc全局指针默认是NULL（RyanJson/RyanJson.c）。
RyanJsonStrictObjectKeyCheck（RyanJsonConfig.h）
true：Object 下拒绝重复 key（Parse/Insert/ReplaceByIndex 等路径更严格）。false：允许重复 key；按 key 查询/替换/删除通常命中第一个，语义由上层约束。
RyanJsonFree(void *block)
- 用于释放
RyanJsonPrint返回的动态字符串。
1. Parse 类
RyanJsonParse(const char *text)
- 输入
\0结尾字符串。 - 成功返回根节点，失败返回
NULL。 - 成功返回值由调用方
RyanJsonDelete。 - 默认等价于
RyanJsonParseOptions(text, strlen(text), RyanJsonFalse, NULL)。 - 默认是非严格尾部模式（允许尾部存在未消费数据），以当前实现为准。
RyanJsonParseOptions(text, size, requireNullTerminator, parseEndPtr)
- 适合非
\0缓冲区或精确控制解析终点。 requireNullTerminator = RyanJsonTrue时，解析后仅允许尾部空白。
2. Create 类
标量创建
RyanJsonCreateNull(key)RyanJsonCreateBool(key, boolean)RyanJsonCreateInt(key, number)RyanJsonCreateDouble(key, number)RyanJsonCreateString(key, string)
容器创建
RyanJsonCreateObject()RyanJsonCreateArray()RyanJsonCreateIntArray(numbers, count)RyanJsonCreateDoubleArray(numbers, count)RyanJsonCreateStringArray(strings, count)
语义：
- Create 成功后节点归调用者。
- 节点未挂到父树前，异常路径必须由调用者释放。
3. Add / Insert 类
常用语法糖
- Object：
RyanJsonAddIntToObject/RyanJsonAddStringToObject... - Array：
RyanJsonAddIntToArray/RyanJsonAddStringToArray...
RyanJsonAddItemToObject(pJson, key, item) / RyanJsonAddItemToArray
AddItem仅接受Array/Object节点。- 标量请使用
AddInt/AddString/...。
RyanJsonInsert(pJson, index, item)
index=0头插。index=UINT32_MAX或越界可视为尾插。- Object 场景要求
item带 key。
所有权：
- 成功：
item转移到父节点。 - 失败：
item为游离节点时，Add/Insert失败路径由库侧清理。item非游离节点时，直接返回 false，不接管释放（保护原树）。AddItemToObject传入标量时会直接失败并删除该标量节点（当前实现语义）。
4. Change 类（仅同类型改值）
RyanJsonChangeKey(pJson, key)RyanJsonChangeStringValue(pJson, strValue)RyanJsonChangeIntValue(pJson, number)RyanJsonChangeDoubleValue(pJson, number)RyanJsonChangeBoolValue(pJson, boolean)
规则：
- Change 会做基础入参/类型校验，失败返回
RyanJsonFalse。 - Change 不做类型切换；类型切换请用 Replace。
5. Replace 类（类型切换主入口）
RyanJsonReplaceByIndex(pJson, index, item)
- 数组/对象都可用（对象场景更推荐
ReplaceByKey）。
RyanJsonReplaceByKey(pJson, key, item)
- 仅 Object。
item无 key 时会按目标 key 包装。item有 key 且不同于目标 key 时会尝试改 key。
规则：
- 调用前要求
item为游离节点（RyanJsonIsDetachedItem）。 - 成功：旧节点被删除，新节点接管到树中。
- 失败：默认不消费
item，调用方负责复用或释放。
6. Get / Has / 路径类
RyanJsonGetObjectByKey/RyanJsonGetObjectByIndexRyanJsonHasObjectByKey/RyanJsonHasObjectByIndexRyanJsonGetObjectToKey/RyanJsonGetObjectToIndex
关键约束：
GetKey/GetString/GetInt/GetDouble/GetBool/GetObjectValue这类取值前，必须先判空并用RyanJsonIsXXX判型。
7. Detach / Delete 类
RyanJsonDetachByKey/DetachByIndex
- 从树中摘除节点并返回。
- 返回节点归调用者，必须手动
RyanJsonDelete（或再次挂树）。
RyanJsonDeleteByKey/DeleteByIndex
- 直接删除目标节点，不返回。
RyanJsonDelete(root)
- 删除整棵树。
8. Print / Minify / Compare
RyanJsonPrint：动态输出，返回值用RyanJsonFree。RyanJsonPrintPreallocated：预分配输出，适合 RT-Thread 固定缓冲。- 传输场景优先：
Print(..., RyanJsonFalse, ...)/PrintPreallocated(..., RyanJsonFalse, ...)直接输出紧凑 Json。 RyanJsonMinify：原地文本清洗（去空白/注释），用于已有 Json 文本处理，不作为首选传输输出路径。RyanJsonMinify终止符规则：- 返回值
< textLen：会写入\0； - 返回值
== textLen：不会额外写入\0，调用方需自行保证字符串终止空间。
- 返回值
RyanJsonCompare/RyanJsonCompareOnlyKey/RyanJsonCompareDouble。
依据（仓库内）
RyanJson/RyanJson.c（RyanJsonInitHooks全局 hooks 初始化）RyanJson/RyanJsonParse.c（RyanJsonParse -> RyanJsonParseOptions(..., RyanJsonFalse, NULL)）RyanJson/RyanJsonItem.c（RyanJsonInsert失败清理、RyanJsonAddItemToObject标量失败删除、RyanJsonReplaceByKey/ByIndex失败不消费）test/unityTest/cases/core/testCreate.c（Insert/Add 失败语义与已挂树拒绝）test/unityTest/cases/core/testReplace.c（Replace 失败所有权）test/unityTest/cases/utils/testPrint.c（format=false紧凑输出与 preallocated 行为）RyanJson/RyanJson.c中RyanJsonMinify实现test/unityTest/cases/utils/testUtils.c、test/unityTest/cases/utils/testRobust.c、test/fuzzer/cases/fuzzerMinify.c
9. 对外/对内边界
RyanJsonChangeObjectValue属于内部实现接口，不作为公开 API 使用。- 对外业务修改对象/数组内容，请通过 Add/Insert/Detach/Replace 组合完成。