From ff0fdd5f7ed5d8e474ea9fa5c6126f56820f8aa0 Mon Sep 17 00:00:00 2001 From: JIgar-maheshwari-dev Date: Wed, 22 Jul 2026 23:04:33 +0530 Subject: [PATCH] docs: clarify contracts for parse_hex4 and cJSON_ReplaceItemInArray - Add doc comment above parse_hex4 explaining that returning 0 represents both valid 0x0000 and parse failures. - Document cJSON_ReplaceItemInArray return behavior in cJSON.h and cJSON.c, noting that returning cJSON_False covers both NULL inputs and out-of-bounds indices. Signed-off-by: JIgar-maheshwari-dev --- cJSON.c | 13 ++++++++++++- cJSON.h | 9 +++++++++ 2 files changed, 21 insertions(+), 1 deletion(-) diff --git a/cJSON.c b/cJSON.c index 727e1827c..242c138e9 100644 --- a/cJSON.c +++ b/cJSON.c @@ -545,7 +545,16 @@ static cJSON_bool print_number(const cJSON * const item, printbuffer * const out return true; } -/* parse 4 digit hexadecimal number */ +/* Helper function to parse 4 hexadecimal digits from input. + * + * NOTE ON RETURN VALUE: + * Returns 0 in two scenarios: + * 1. Success: The input sequence is valid hexadecimal representing 0x0000 (e.g., "\u0000"). + * 2. Failure: An invalid hexadecimal character was encountered. + * + * Callers that need to distinguish a valid 0x0000 from a parse failure must check input + * validation or pointer offset before relying solely on a non-zero return value. + */ static unsigned parse_hex4(const unsigned char * const input) { unsigned int h = 0; @@ -2288,6 +2297,8 @@ CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemViaPointer(cJSON * const parent, cJSON return true; } +/* Replace an item in an array at a given index. + * Returns cJSON_False if input pointers are NULL or if 'which' index is out of bounds. */ CJSON_PUBLIC(void) cJSON_ReplaceItemInArray(cJSON *array, int which, cJSON *newitem) { if (which < 0) diff --git a/cJSON.h b/cJSON.h index 9267c93c3..1dd3b302c 100644 --- a/cJSON.h +++ b/cJSON.h @@ -232,6 +232,15 @@ CJSON_PUBLIC(void) cJSON_DeleteItemFromObjectCaseSensitive(cJSON *object, const /* Update array items. */ CJSON_PUBLIC(void) cJSON_InsertItemInArray(cJSON *array, int which, cJSON *newitem); /* Shifts pre-existing items to the right. */ CJSON_PUBLIC(cJSON_bool) cJSON_ReplaceItemViaPointer(cJSON * const parent, cJSON * const item, cJSON * replacement); + +/* Replaces an item at index 'which' in 'array' with 'newitem'. + * + * @return cJSON_True (1) on successful replacement. + * @return cJSON_False (0) if the operation fails (e.g., if 'array' or 'newitem' is NULL, + * or if 'which' is negative or exceeds the current array bounds). + * + * Note: An out-of-range index fails silently by returning cJSON_False without modifying the array. + */ CJSON_PUBLIC(void) cJSON_ReplaceItemInArray(cJSON *array, int which, cJSON *newitem); CJSON_PUBLIC(void) cJSON_ReplaceItemInObject(cJSON *object,const char *string,cJSON *newitem); CJSON_PUBLIC(void) cJSON_ReplaceItemInObjectCaseSensitive(cJSON *object,const char *string,cJSON *newitem);