docs: 更新readme中的Json结构体描述

Author: Ryan-CW-Code

.gitignore

@@ -18,6 +18,7 @@ build
 default.profdata
 default.profraw
 test/fuzzer/corpus
+./coverage/**
 
 fuzz-*
 RyanJson_Technical_Paper.md

README.md

@@ -42,6 +42,7 @@ RyanJson 的核心在于对内存布局的精细控制，**结构体表示最小
 // 其余数据（flag、key、stringValue、numberValue、doubleValue 等）均通过动态内存分配管理。
 struct RyanJsonNode
 {
+	// 理论上next的低2位也是可以利用起来的
 	struct RyanJsonNode *next; // 单链表节点指针
 
 	/**
@@ -66,20 +67,19 @@ struct RyanJsonNode
 	 *
 	 * - bit3   : 扩展位
 	 *            Bool 类型：0=false, 1=true
-	 *            Number 类型：0=int(4字节), 1=double(8字节)
+	 *            Number 类型：0=int32_t(4字节), 1=double(8字节)
 	 *
-	 * - bit4   : 是否包含 Key
-	 *            0=无 Key（数组元素）
-	 *            1=有 Key（对象成员）
+	 * - bit4-5 : Key 长度字段字节数
+	 *            00:无key
+	 *            01:keyLen=1字节 (≤UINT8_MAX)
+	 *            10:keyLen=2字节 (≤UINT16_MAX)
+	 *            11:keyLen=4字节 (≤UINT32_MAX)
 	 *
-	 * - bit5-6 : Key 长度字段字节数
-	 *            00=1字节 (≤UINT8_MAX)
-	 *            01=2字节 (≤UINT16_MAX)
-	 *            10=3字节 (≤UINT24_MAX)
-	 *            11=4字节 (≤UINT32_MAX)
+	 * - bit6   : 表示key / strValue 存储模式
+	 *            0:inline 模式, 1:ptr 模式
 	 *
-	 * - bit7   : 表示key / strValue 存储模式
-	 *            0:inline 模式, 1=ptr 模式
+	 * - bit7   : 表示是否为当前链表的最后一位，是的话nexe指针会指向Parent(线索化链表)
+	 *            0:next 指向兄弟节点, 1:next 指向Parent节点
 	 *
 	 * @brief 动态载荷存储区
      * 目的：
@@ -90,7 +90,7 @@ struct RyanJsonNode
      * 存储策略：
      * 利用结构体内存对齐产生的 Padding（如 Flag 后的空隙）以及原本用于存储指针的空间，形成一个缓冲区
      * 若节点包含 key / strValue，则可能有两种方案：
-     * 1. inline 模式 (小数据优化)
+     * inline 模式 (小数据优化)
      *    - 当 (KeyLen + Key + Value) 的总长度 ≤ 阈值时，直接存储在结构体内部。
      *    - 阈值计算公式：
      *        阈值 = Padding + sizeof(void*) + (malloc头部空间的一半)，再向上对齐到字节边界。
@@ -103,16 +103,16 @@ struct RyanJsonNode
      *        [ KeyLen | Key | Value ]
      *      起始地址即为 flag 之后，数据紧凑排列，无需额外 malloc。
      *
-     * 2. ptr 模式 (大数据)
+     * ptr 模式 (大数据)
      *    - 当数据长度 > 阈值时，结构体存储一个指针，指向独立的堆区。
      *    - 存储布局：
-     *        [ KeyLen | *ptr ] -> (ptr指向) [ Key | Value ]
+     *        [ KeyLen | *ptr | Padding ] -> (ptr指向) [ Key | Value ]
      *    - KeyLen 的大小由 flag 中的长度字段决定 (最多 4 字节)。
      *    - 这样保证大数据不会撑爆结构体，同时保持 API 一致性。
 
      * 其他类型的存储：
 	 * - null / bool : 由 flag 位直接表示，无需额外空间。
-	 * - number      : 根据 flag 扩展位决定存储 int(4字节) 或 double(8字节)。
+	 * - number      : 根据 flag 扩展位决定存储 int32_t(4字节) 或 double(8字节)。
 	 * - object      : 动态分配空间存储子节点，采用链表结构。
      *
      * 设计考量：

RyanJson/RyanJson.c

@@ -335,9 +335,14 @@ static RyanJsonBool_e RyanJsonInternalCompare(RyanJson_t leftJson, RyanJson_t ri
 	while (1)
 	{
 		// 比较当前节点的类型、值与规模
-		RyanJsonCheckReturnFalse(RyanJsonGetType(leftCurrent) == RyanJsonGetType(rightCurrent));
-
-		switch (RyanJsonGetType(leftCurrent))
+		RyanJsonType_e leftType = RyanJsonGetType(leftCurrent);
+		RyanJsonCheckReturnFalse(leftType == RyanJsonGetType(rightCurrent));
+
+#if defined(__clang__)
+#pragma clang diagnostic push
+#pragma clang diagnostic ignored "-Wcovered-switch-default"
+#endif
+		switch (leftType)
 		{
 		case RyanJsonTypeNull: break;
 		case RyanJsonTypeBool:
@@ -371,6 +376,9 @@ static RyanJsonBool_e RyanJsonInternalCompare(RyanJson_t leftJson, RyanJson_t ri
 		case RyanJsonTypeObject: RyanJsonCheckReturnFalse(RyanJsonGetSize(leftCurrent) == RyanJsonGetSize(rightCurrent)); break;
 		default: return RyanJsonFalse;
 		}
+#if defined(__clang__)
+#pragma clang diagnostic pop
+#endif
 
 		// 容器节点尝试下沉到子节点继续比较
 		if (_checkType(leftCurrent, RyanJsonTypeArray) || _checkType(leftCurrent, RyanJsonTypeObject))
@@ -407,35 +415,84 @@ static RyanJsonBool_e RyanJsonInternalCompare(RyanJson_t leftJson, RyanJson_t ri
 			}
 		}
 
-		// 同层前进，必要时回溯
+		// 走到这里说明当前节点对已经比较完成，且若它们是容器，则其子树也已经比较完毕。
+		// 接下来要在“不使用递归栈”的前提下，找到 DFS 意义上的下一个待比较节点对：
+		// 1) 优先尝试同父层的下一个兄弟；
+		// 2) 当前层没有兄弟时，沿内部 parent 回链逐层回溯；
+		// 3) 一旦回溯到入口 root，说明整棵树已经完全比较结束。
 		while (1)
 		{
+			// 进入本循环时，leftCurrent/rightCurrent 表示“刚完成比较的节点对”。
+			// 如果它已经回到入口 root，且前面也没有可继续下沉的子节点，
+			// 则表示从 root 出发的整棵树都已匹配完成，可以直接返回 True。
 			if (leftCurrent == leftJson) { return RyanJsonTrue; }
 
-			// 优先定位右侧对应的兄弟节点
+			// 先看左侧当前节点是否还有同父兄弟。
+			// 有的话，下一个比较目标就必须切到这个兄弟；右侧则去找“语义上与它对应”的兄弟。
 			RyanJson_t leftNext = RyanJsonGetNext(leftCurrent);
 			if (leftNext)
 			{
 				RyanJson_t rightNext = NULL;
-				if (RyanJsonFalse == RyanJsonIsKey(leftNext)) { rightNext = RyanJsonGetNext(rightCurrent); }
+				if (RyanJsonFalse == RyanJsonIsKey(leftNext))
+				{
+					// 无 key 节点只会出现在数组路径上，数组比较是严格按顺序进行的，
+					// 因而右侧可以直接取当前节点的 next 兄弟，不需要额外查找。
+					rightNext = RyanJsonGetNext(rightCurrent);
+				}
 				else
 				{
 					RyanJsonCheckAssert(RyanJsonTrue == RyanJsonIsKey(leftNext));
 					const char *leftNextKey = RyanJsonGetKey(leftNext);
 					RyanJson_t rightParent = RyanJsonInternalGetParent(rightCurrent);
 
-					// 同序快路径：优先尝试右侧当前节点的直接兄弟，未命中再回退到按 key 查找
-					RyanJson_t rightCandidate = RyanJsonGetNext(rightCurrent);
-					if (rightCandidate) { RyanJsonCheckAssert(RyanJsonTrue == RyanJsonIsKey(rightCandidate)); }
-					if (rightCandidate &&
-					    RyanJsonTrue == RyanJsonInternalStrEq(leftNextKey, RyanJsonGetKey(rightCandidate)))
+					// 对象比较是“同层无序、同 key 对齐”语义，不能像数组那样直接依赖 rightCurrent->next：
+					// - strict 模式下 key 唯一，按 key 找即可；
+					// - non-strict 模式下允许重复 key，必须继续保证“同 key 的第 N 次出现”彼此对齐，
+					//   否则会把后一个重复 key 错配到右侧第一个同名节点，导致 Compare/CompareOnlyKey 语义漂移。
+					RyanJsonCheckAssert(NULL != rightParent && RyanJsonTrue == RyanJsonIsObject(rightParent));
+#if true == RyanJsonStrictObjectKeyCheck
+					// strict 模式下 key 唯一，直接按 key 查找即可。
+					rightNext = RyanJsonGetObjectByKey(rightParent, leftNextKey);
+#else
+					// 非严格模式下允许重复 key，按“同 key + 相同出现序号”精确匹配。
+					RyanJson_t leftParent = RyanJsonInternalGetParent(leftCurrent);
+					RyanJsonCheckAssert(NULL != leftParent && RyanJsonTrue == RyanJsonIsObject(leftParent));
+
+					// 先在左父节点里统计 leftNext 是该 key 的第几次出现（0-based）。
+					// 例如 leftParent 子节点是 a,b,a,c，则第二个 a 的序号是 1。
+					uint32_t leftSameKeyIndex = 0;
+					RyanJson_t leftScan = RyanJsonGetObjectValue(leftParent);
+					RyanJsonCheckAssert(NULL != leftScan);
+					while (leftScan != leftNext)
 					{
-						rightNext = rightCandidate;
+						RyanJsonCheckAssert(RyanJsonTrue == RyanJsonIsKey(leftScan));
+						if (RyanJsonTrue == RyanJsonInternalStrEq(leftNextKey, RyanJsonGetKey(leftScan)))
+						{
+							leftSameKeyIndex++;
+						}
+						leftScan = RyanJsonGetNext(leftScan);
+						RyanJsonCheckAssert(NULL != leftScan);
 					}
-					else
+
+					// 再在右父节点里找到“同 key 的同序号节点”。
+					// 这样重复 key 的比较就不是“命中任意一个同名节点”，而是稳定地按出现次序对齐。
+					uint32_t rightSameKeyIndex = 0;
+					RyanJson_t rightScan = RyanJsonGetObjectValue(rightParent);
+					while (rightScan)
 					{
-						rightNext = RyanJsonGetObjectByKey(rightParent, leftNextKey);
+						RyanJsonCheckAssert(RyanJsonTrue == RyanJsonIsKey(rightScan));
+						if (RyanJsonTrue == RyanJsonInternalStrEq(leftNextKey, RyanJsonGetKey(rightScan)))
+						{
+							if (rightSameKeyIndex == leftSameKeyIndex)
+							{
+								rightNext = rightScan;
+								break;
+							}
+							rightSameKeyIndex++;
+						}
+						rightScan = RyanJsonGetNext(rightScan);
 					}
+#endif
 				}
 
 				RyanJsonCheckReturnFalse(NULL != rightNext);
@@ -445,9 +502,17 @@ static RyanJsonBool_e RyanJsonInternalCompare(RyanJson_t leftJson, RyanJson_t ri
 				break;
 			}
 
-			// 无兄弟可比时回溯到父层
+			// 当前层已没有可比较的兄弟，开始回溯。
+			// 这里故意不用 RyanJsonGetNext(leftCurrent)：
+			// - 公开语义下，没有兄弟时它会返回 NULL；
+			// - 但内部链表约定中，“最后一个兄弟节点的 next”挂的是父节点，
+			//   正是这里做迭代式 DFS 回溯所需要的那条内部回链。
 			leftCurrent = leftCurrent->next;
 
+			// leftCurrent 此时已经被抬回父节点，所以这里按“父节点类型”决定右侧如何回溯。
+			// - array：左右两边始终按相同 sibling 顺序推进，rightCurrent->next 正好也挂回父节点；
+			// - object：右侧当前节点可能是按 key/序号匹配得到的任意兄弟，未必处在链表尾部，
+			//   这时不能假设 rightCurrent->next 是父节点，只能显式调用 RyanJsonInternalGetParent。
 			if (RyanJsonIsArray(leftCurrent)) { rightCurrent = rightCurrent->next; }
 			else
 			{

RyanJson/RyanJsonItem.c

@@ -351,6 +351,19 @@ RyanJsonBool_e RyanJsonChangeKey(RyanJson_t pJson, const char *key)
 {
 	RyanJsonCheckReturnFalse(NULL != pJson && NULL != key);
 	RyanJsonCheckReturnFalse(RyanJsonIsKey(pJson));
+
+#if true == RyanJsonStrictObjectKeyCheck
+	// 严格模式下，若节点挂在 Object 下，改 key 不能制造重复 key
+	if (RyanJsonTrue != RyanJsonInternalStrEq(RyanJsonGetKey(pJson), key))
+	{
+		RyanJson_t parent = RyanJsonInternalGetParent(pJson);
+		if (NULL != parent && RyanJsonTrue == RyanJsonIsObject(parent))
+		{
+			RyanJsonCheckReturnFalse(RyanJsonFalse == RyanJsonObjectHasKeyConflict(parent, key, pJson));
+		}
+	}
+#endif
+
 	return RyanJsonInternalChangeString(pJson, RyanJsonFalse, key, RyanJsonIsString(pJson) ? RyanJsonGetStringValue(pJson) : NULL);
 }