--- a/ucx/cx/json.h Sun Dec 07 20:16:59 2025 +0100
+++ b/ucx/cx/json.h Fri Dec 19 17:53:18 2025 +0100
@@ -41,8 +41,7 @@
#include "string.h"
#include "buffer.h"
#include "array_list.h"
-
-#include <string.h>
+#include "map.h"
#ifdef __cplusplus
extern "C" {
@@ -184,13 +183,10 @@
typedef struct cx_json_value_s CxJsonValue;
/**
- * Type alias for the JSON array struct.
+ * Type alias for the map representing a JSON object.
+ * The map contains pointers of type @c CxJsonValue.
*/
-typedef struct cx_json_array_s CxJsonArray;
-/**
- * Type alias for the JSON object struct.
- */
-typedef struct cx_json_object_s CxJsonObject;
+typedef CxMap* CxJsonObject;
/**
* Type alias for a JSON string.
*/
@@ -209,49 +205,6 @@
typedef enum cx_json_literal CxJsonLiteral;
/**
- * Type alias for a key/value pair in a JSON object.
- */
-typedef struct cx_json_obj_value_s CxJsonObjValue;
-
-/**
- * JSON array structure.
- */
-struct cx_json_array_s {
- /**
- * The array data.
- */
- CX_ARRAY_DECLARE(CxJsonValue*, array);
-};
-
-/**
- * JSON object structure.
- */
-struct cx_json_object_s {
- /**
- * The key/value entries.
- */
- CX_ARRAY_DECLARE(CxJsonObjValue, values);
- /**
- * The original indices to reconstruct the order in which the members were added.
- */
- size_t *indices;
-};
-
-/**
- * Structure for a key/value entry in a JSON object.
- */
-struct cx_json_obj_value_s {
- /**
- * The key (or name in JSON terminology) of the value.
- */
- cxmutstr name;
- /**
- * The value.
- */
- CxJsonValue *value;
-};
-
-/**
* Structure for a JSON value.
*/
struct cx_json_value_s {
@@ -274,7 +227,7 @@
/**
* The array data if the type is #CX_JSON_ARRAY.
*/
- CxJsonArray array;
+ CX_ARRAY(CxJsonValue*, array);
/**
* The object data if the type is #CX_JSON_OBJECT.
*/
@@ -295,7 +248,7 @@
* The literal type if the type is #CX_JSON_LITERAL.
*/
CxJsonLiteral literal;
- } value;
+ };
};
/**
@@ -329,6 +282,7 @@
* The allocator used for produced JSON values.
*/
const CxAllocator *allocator;
+
/**
* The input buffer.
*/
@@ -349,21 +303,21 @@
CxJsonValue *parsed;
/**
- * A pointer to an intermediate state of a currently parsed object member.
+ * The name of a not yet completely parsed object member.
*
* Never access this value manually.
*/
- CxJsonObjValue uncompleted_member;
+ cxmutstr uncompleted_member_name;
/**
* State stack.
*/
- CX_ARRAY_DECLARE_SIZED(int, states, unsigned);
+ CX_ARRAY(int, states);
/**
* Value buffer stack.
*/
- CX_ARRAY_DECLARE_SIZED(CxJsonValue*, vbuf, unsigned);
+ CX_ARRAY(CxJsonValue*, vbuf);
/**
* Internally reserved memory for the state stack.
@@ -439,10 +393,6 @@
*/
bool pretty;
/**
- * Set false to output the members in the order in which they were added.
- */
- bool sort_members;
- /**
* The maximum number of fractional digits in a number value.
* The default value is 6 and values larger than 15 are reduced to 15.
* Note that the actual number of digits may be lower, depending on the concrete number.
@@ -508,6 +458,33 @@
CX_EXPORT int cxJsonWrite(void* target, const CxJsonValue* value,
cx_write_func wfunc, const CxJsonWriter* settings);
+
+/**
+ * Produces a compact string representation of the specified JSON value.
+ *
+ * @param allocator the allocator for the string
+ * @param value the JSON value
+ * @return the produced string
+ * @see cxJsonWrite()
+ * @see cxJsonWriterCompact()
+ * @see cxJsonToPrettyString()
+ */
+cx_attr_nonnull_arg(2)
+CX_EXPORT cxmutstr cxJsonToString(const CxAllocator *allocator, CxJsonValue *value);
+
+/**
+ * Produces a pretty string representation of the specified JSON value.
+ *
+ * @param allocator the allocator for the string
+ * @param value the JSON value
+ * @return the produced string
+ * @see cxJsonWrite()
+ * @see cxJsonWriterPretty()
+ * @see cxJsonToString()
+ */
+cx_attr_nonnull_arg(2)
+CX_EXPORT cxmutstr cxJsonToPrettyString(const CxAllocator *allocator, CxJsonValue *value);
+
/**
* Initializes the JSON interface.
*
@@ -530,8 +507,8 @@
/**
* Destroys and re-initializes the JSON interface.
*
- * You might want to use this to reset the parser after
- * encountering a syntax error.
+ * You must use this to reset the parser after encountering a syntax error
+ * if you want to continue using it.
*
* @param json the JSON interface
*/
@@ -556,7 +533,7 @@
* @retval non-zero internal allocation error
* @see cxJsonFill()
*/
-cx_attr_nonnull cx_attr_access_r(2, 3)
+cx_attr_nonnull_arg(1) cx_attr_access_r(2, 3)
CX_EXPORT int cxJsonFilln(CxJson *json, const char *buf, size_t len);
@@ -592,6 +569,36 @@
*/
#define cxJsonFill(json, str) cx_json_fill(json, cx_strcast(str))
+
+/**
+ * Internal function - use cxJsonFromString() instead.
+ *
+ * @param allocator the allocator for the JSON value
+ * @param str the string to parse
+ * @param value a pointer where the JSON value shall be stored to
+ * @return status code
+ */
+cx_attr_nonnull_arg(3)
+CX_EXPORT CxJsonStatus cx_json_from_string(const CxAllocator *allocator,
+ cxstring str, CxJsonValue **value);
+
+/**
+ * Parses a string into a JSON value.
+ *
+ * @param allocator (@c CxAllocator*) the allocator for the JSON value
+ * @param str (any string) the string to parse
+ * @param value (@c CxJsonValue**) a pointer where the JSON value shall be stored to
+ * @retval CX_JSON_NO_ERROR success
+ * @retval CX_JSON_NO_DATA the string was empty or blank
+ * @retval CX_JSON_INCOMPLETE_DATA the string unexpectedly ended
+ * @retval CX_JSON_BUFFER_ALLOC_FAILED allocating internal buffer space failed
+ * @retval CX_JSON_VALUE_ALLOC_FAILED allocating memory for the CxJsonValue failed
+ * @retval CX_JSON_FORMAT_ERROR_NUMBER the JSON text contains an illegally formatted number
+ * @retval CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN JSON syntax error
+ */
+#define cxJsonFromString(allocator, str, value) \
+ cx_json_from_string(allocator, cx_strcast(str), value)
+
/**
* Creates a new (empty) JSON object.
*
@@ -606,13 +613,16 @@
/**
* Creates a new (empty) JSON array.
*
+ * Optionally, this function already allocates memory with the given capacity.
+ *
* @param allocator the allocator to use
+ * @param capacity optional capacity or zero if it's unknown how many elements the array will have
* @return the new JSON array or @c NULL if allocation fails
* @see cxJsonObjPutArr()
* @see cxJsonArrAddValues()
*/
cx_attr_nodiscard
-CX_EXPORT CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator);
+CX_EXPORT CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator, size_t capacity);
/**
* Creates a new JSON number value.
@@ -641,28 +651,27 @@
/**
* Creates a new JSON string.
*
+ * Internal function - use cxJsonCreateString() instead.
+ *
* @param allocator the allocator to use
* @param str the string data
* @return the new JSON value or @c NULL if allocation fails
- * @see cxJsonCreateString()
* @see cxJsonObjPutString()
- * @see cxJsonArrAddStrings()
+ * @see cxJsonArrAddCxStrings()
*/
-cx_attr_nodiscard cx_attr_nonnull_arg(2) cx_attr_cstr_arg(2)
-CX_EXPORT CxJsonValue* cxJsonCreateString(const CxAllocator* allocator, const char *str);
+cx_attr_nodiscard
+CX_EXPORT CxJsonValue* cx_json_create_string(const CxAllocator* allocator, cxstring str);
/**
* Creates a new JSON string.
*
- * @param allocator the allocator to use
- * @param str the string data
- * @return the new JSON value or @c NULL if allocation fails
- * @see cxJsonCreateCxString()
- * @see cxJsonObjPutCxString()
+ * @param allocator (@c CxAllocator*) the allocator to use
+ * @param str the string
+ * @return (@c CxJsonValue*) the new JSON value or @c NULL if allocation fails
+ * @see cxJsonObjPutString()
* @see cxJsonArrAddCxStrings()
*/
-cx_attr_nodiscard
-CX_EXPORT CxJsonValue* cxJsonCreateCxString(const CxAllocator* allocator, cxstring str);
+#define cxJsonCreateString(allocator, str) cx_json_create_string(allocator, cx_strcast(str))
/**
* Creates a new JSON literal.
@@ -760,10 +769,7 @@
/**
* Adds or replaces a value within a JSON object.
*
- * The value will be directly added and not copied.
- *
- * @note If a value with the specified @p name already exists,
- * it will be (recursively) freed with its own allocator.
+ * Internal function - use cxJsonObjPut().
*
* @param obj the JSON object
* @param name the name of the value
@@ -772,11 +778,29 @@
* @retval non-zero allocation failure
*/
cx_attr_nonnull
-CX_EXPORT int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child);
+CX_EXPORT int cx_json_obj_put(CxJsonValue* obj, cxstring name, CxJsonValue* child);
+
+/**
+ * Adds or replaces a value within a JSON object.
+ *
+ * The value will be directly added and not copied.
+ *
+ * @note If a value with the specified @p name already exists,
+ * it will be (recursively) freed with its own allocator.
+ *
+ * @param obj (@c CxJsonValue*) the JSON object
+ * @param name (any string) the name of the value
+ * @param child (@c CxJsonValue*) the value
+ * @retval zero success
+ * @retval non-zero allocation failure
+ */
+#define cxJsonObjPut(obj, name, child) cx_json_obj_put(obj, cx_strcast(name), child)
/**
* Creates a new JSON object and adds it to an existing object.
*
+ * Internal function - use cxJsonObjPutObj().
+ *
* @param obj the target JSON object
* @param name the name of the new value
* @return the new value or @c NULL if allocation fails
@@ -784,23 +808,51 @@
* @see cxJsonCreateObj()
*/
cx_attr_nonnull
-CX_EXPORT CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name);
+CX_EXPORT CxJsonValue* cx_json_obj_put_obj(CxJsonValue* obj, cxstring name);
+
+/**
+ * Creates a new JSON object and adds it to an existing object.
+ *
+ * @param obj (@c CxJsonValue*) the target JSON object
+ * @param name (any string) the name of the new value
+ * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateObj()
+ */
+#define cxJsonObjPutObj(obj, name) cx_json_obj_put_obj(obj, cx_strcast(name))
/**
* Creates a new JSON array and adds it to an object.
*
+ * Internal function - use cxJsonObjPutArr().
+ *
* @param obj the target JSON object
* @param name the name of the new value
+ * @param capacity optional initial capacity
* @return the new value or @c NULL if allocation fails
* @see cxJsonObjPut()
* @see cxJsonCreateArr()
*/
cx_attr_nonnull
-CX_EXPORT CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name);
+CX_EXPORT CxJsonValue* cx_json_obj_put_arr(CxJsonValue* obj, cxstring name, size_t capacity);
+
+/**
+ * Creates a new JSON array and adds it to an object.
+ *
+ * @param obj (@c CxJsonValue*) the target JSON object
+ * @param name (any string) the name of the new value
+ * @param capacity (@c size_t) optional initial capacity
+ * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateArr()
+ */
+#define cxJsonObjPutArr(obj, name, capacity) cx_json_obj_put_arr(obj, cx_strcast(name), capacity)
/**
* Creates a new JSON number and adds it to an object.
*
+ * Internal function - use cxJsonObjPutNumber().
+ *
* @param obj the target JSON object
* @param name the name of the new value
* @param num the numeric value
@@ -809,11 +861,25 @@
* @see cxJsonCreateNumber()
*/
cx_attr_nonnull
-CX_EXPORT CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj, cxstring name, double num);
+CX_EXPORT CxJsonValue* cx_json_obj_put_number(CxJsonValue* obj, cxstring name, double num);
+
+/**
+ * Creates a new JSON number and adds it to an object.
+ *
+ * @param obj (@c CxJsonValue*) the target JSON object
+ * @param name (any string) the name of the new value
+ * @param num (@c double) the numeric value
+ * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateNumber()
+ */
+#define cxJsonObjPutNumber(obj, name, num) cx_json_obj_put_number(obj, cx_strcast(name), num)
/**
* Creates a new JSON number, based on an integer, and adds it to an object.
*
+ * Internal function - use cxJsonObjPutInteger().
+ *
* @param obj the target JSON object
* @param name the name of the new value
* @param num the numeric value
@@ -822,12 +888,24 @@
* @see cxJsonCreateInteger()
*/
cx_attr_nonnull
-CX_EXPORT CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj, cxstring name, int64_t num);
+CX_EXPORT CxJsonValue* cx_json_obj_put_integer(CxJsonValue* obj, cxstring name, int64_t num);
+
+/**
+ * Creates a new JSON number, based on an integer, and adds it to an object.
+ *
+ * @param obj (@c CxJsonValue*) the target JSON object
+ * @param name (any string) the name of the new value
+ * @param num (@c int64_t) the numeric value
+ * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateInteger()
+ */
+#define cxJsonObjPutInteger(obj, name, num) cx_json_obj_put_integer(obj, cx_strcast(name), num)
/**
* Creates a new JSON string and adds it to an object.
*
- * The string data is copied.
+ * Internal function - use cxJsonObjPutString()
*
* @param obj the target JSON object
* @param name the name of the new value
@@ -836,27 +914,28 @@
* @see cxJsonObjPut()
* @see cxJsonCreateString()
*/
-cx_attr_nonnull cx_attr_cstr_arg(3)
-CX_EXPORT CxJsonValue* cxJsonObjPutString(CxJsonValue* obj, cxstring name, const char* str);
+cx_attr_nonnull
+CX_EXPORT CxJsonValue* cx_json_obj_put_string(CxJsonValue* obj, cxstring name, cxstring str);
/**
* Creates a new JSON string and adds it to an object.
*
* The string data is copied.
*
- * @param obj the target JSON object
- * @param name the name of the new value
- * @param str the string data
- * @return the new value or @c NULL if allocation fails
+ * @param obj (@c CxJsonValue*) the target JSON object
+ * @param name (any string) the name of the new value
+ * @param str (any string) the string data
+ * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
* @see cxJsonObjPut()
- * @see cxJsonCreateCxString()
+ * @see cxJsonCreateString()
*/
-cx_attr_nonnull
-CX_EXPORT CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj, cxstring name, cxstring str);
+#define cxJsonObjPutString(obj, name, str) cx_json_obj_put_string(obj, cx_strcast(name), cx_strcast(str))
/**
* Creates a new JSON literal and adds it to an object.
*
+ * Internal function - use cxJsonObjPutLiteral().
+ *
* @param obj the target JSON object
* @param name the name of the new value
* @param lit the type of literal
@@ -865,7 +944,19 @@
* @see cxJsonCreateLiteral()
*/
cx_attr_nonnull
-CX_EXPORT CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj, cxstring name, CxJsonLiteral lit);
+CX_EXPORT CxJsonValue* cx_json_obj_put_literal(CxJsonValue* obj, cxstring name, CxJsonLiteral lit);
+
+/**
+ * Creates a new JSON literal and adds it to an object.
+ *
+ * @param obj (@c CxJsonValue*) the target JSON object
+ * @param name (any string) the name of the new value
+ * @param lit (@c CxJsonLiteral) the type of literal
+ * @return (@c CxJsonValue*) the new value or @c NULL if allocation fails
+ * @see cxJsonObjPut()
+ * @see cxJsonCreateLiteral()
+ */
+#define cxJsonObjPutLiteral(obj, name, lit) cx_json_obj_put_literal(obj, cx_strcast(name), lit)
/**
* Recursively deallocates the memory of a JSON value.
@@ -998,7 +1089,7 @@
*/
cx_attr_nonnull
CX_INLINE bool cxJsonIsBool(const CxJsonValue *value) {
- return cxJsonIsLiteral(value) && value->value.literal != CX_JSON_NULL;
+ return cxJsonIsLiteral(value) && value->literal != CX_JSON_NULL;
}
/**
@@ -1015,7 +1106,7 @@
*/
cx_attr_nonnull
CX_INLINE bool cxJsonIsTrue(const CxJsonValue *value) {
- return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_TRUE;
+ return cxJsonIsLiteral(value) && value->literal == CX_JSON_TRUE;
}
/**
@@ -1032,7 +1123,7 @@
*/
cx_attr_nonnull
CX_INLINE bool cxJsonIsFalse(const CxJsonValue *value) {
- return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_FALSE;
+ return cxJsonIsLiteral(value) && value->literal == CX_JSON_FALSE;
}
/**
@@ -1045,7 +1136,7 @@
*/
cx_attr_nonnull
CX_INLINE bool cxJsonIsNull(const CxJsonValue *value) {
- return cxJsonIsLiteral(value) && value->value.literal == CX_JSON_NULL;
+ return cxJsonIsLiteral(value) && value->literal == CX_JSON_NULL;
}
/**
@@ -1123,7 +1214,7 @@
*/
cx_attr_nonnull
CX_INLINE bool cxJsonAsBool(const CxJsonValue *value) {
- return value->value.literal == CX_JSON_TRUE;
+ return value->literal == CX_JSON_TRUE;
}
/**
@@ -1137,7 +1228,7 @@
*/
cx_attr_nonnull
CX_INLINE size_t cxJsonArrSize(const CxJsonValue *value) {
- return value->value.array.array_size;
+ return value->array.size;
}
/**
@@ -1188,10 +1279,24 @@
CX_EXPORT CxIterator cxJsonArrIter(const CxJsonValue *value);
/**
- * Returns an iterator over the JSON object members.
+ * Returns the size of a JSON object.
+ *
+ * If the @p value is not a JSON object, the behavior is undefined.
*
- * The iterator yields values of type @c CxJsonObjValue* which
- * contain the name and value of the member.
+ * @param value the JSON value
+ * @return the size of the object, i.e., the number of key/value pairs
+ * @see cxJsonIsObject()
+ */
+cx_attr_nonnull
+CX_INLINE size_t cxJsonObjSize(const CxJsonValue *value) {
+ return cxCollectionSize(value->object);
+}
+
+/**
+ * Returns a map iterator over the JSON object members.
+ *
+ * The iterator yields values of type @c CxMapEntry* which
+ * contain the name and the @c CxJsonObjValue* of the member.
*
* If the @p value is not a JSON object, the behavior is undefined.
*
@@ -1200,7 +1305,7 @@
* @see cxJsonIsObject()
*/
cx_attr_nonnull cx_attr_nodiscard
-CX_EXPORT CxIterator cxJsonObjIter(const CxJsonValue *value);
+CX_EXPORT CxMapIterator cxJsonObjIter(const CxJsonValue *value);
/**
* Internal function, do not use.
@@ -1251,6 +1356,66 @@
*/
#define cxJsonObjRemove(value, name) cx_json_obj_remove(value, cx_strcast(name))
+/**
+ * Performs a deep comparison of two JSON values.
+ *
+ * The order of object members is ignored during comparison.
+ *
+ * @param json the JSON value
+ * @param other the other JSON value that the JSON value is compared to
+ * @retval zero the values are equal (except for ordering of object members)
+ * @retval non-zero the values differ
+ */
+CX_EXPORT int cxJsonCompare(const CxJsonValue *json, const CxJsonValue *other);
+
+
+/**
+ * Creates a deep copy of the specified JSON value.
+ *
+ * If you need a @c cx_clone_func compatible version, see cxJsonCloneFunc().
+ *
+ * @note when you are cloning @c NULL, you will get a pointer to a statically
+ * allocated value which represents nothing.
+ *
+ * @param value the value to be cloned
+ * @param allocator the allocator for the new value
+ * @return the new value or @c NULL if any allocation was unsuccessful
+ * @see cxJsonCloneFunc()
+ */
+cx_attr_nodiscard
+CX_EXPORT CxJsonValue* cxJsonClone(const CxJsonValue* value,
+ const CxAllocator* allocator);
+
+
+/**
+ * A @c cx_clone_func compatible version of cxJsonClone().
+ *
+ * Internal function - use cxJsonCloneFunc() to get a properly casted function pointer.
+ *
+ * @param target the target memory or @c NULL
+ * @param source the value to be cloned
+ * @param allocator the allocator for the new value
+ * @param data unused
+ * @return the new value or @c NULL if any allocation was unsuccessful
+ * @see cxJsonClone()
+ */
+cx_attr_nodiscard
+CX_EXPORT CxJsonValue* cx_json_clone_func(
+ CxJsonValue* target, const CxJsonValue* source,
+ const CxAllocator* allocator, void *data);
+
+/**
+ * A @c cx_clone_func compatible version of cxJsonClone().
+ *
+ * @param target (@c CxJsonValue*) the target memory or @c NULL
+ * @param source (@c CxJsonValue*) the value to be cloned
+ * @param allocator (@c CxAllocator*) the allocator for the new value
+ * @param data unused
+ * @return the new value or @c NULL if any allocation was unsuccessful
+ * @see cxJsonClone()
+ */
+#define cxJsonCloneFunc ((cx_clone_func) cx_json_clone_func)
+
#ifdef __cplusplus
}
#endif