# HG changeset patch
# User Mike Becker <universe@uap-core.de>
# Date 1742653795 -3600
# Node ID 946cadf95ea421bc454871d98a962617cb408bc7
# Parent  b9a940779877edd0ec1e9451bf471e556b435f07
define structure for json.h doc

relates to #451

diff -r b9a940779877 -r 946cadf95ea4 docs/Writerside/topics/json.h.md
--- a/docs/Writerside/topics/json.h.md	Sat Mar 22 14:14:29 2025 +0100
+++ b/docs/Writerside/topics/json.h.md	Sat Mar 22 15:29:55 2025 +0100
@@ -4,43 +4,237 @@
 New Feature - will be documented soon!
 </warning>
 
+## Parser
+
+```C
+#include <cx/json.h>
+
+void cxJsonInit(CxJson *json, const CxAllocator *allocator);
+
+void cxJsonReset(CxJson *json);
+
+int cxJsonFilln(CxJson *json, const char *buf, size_t len);
+
+int cxJsonFill(CxJson *json, AnyStr str);
+
+CxJsonStatus cxJsonNext(CxJson *json, CxJsonValue **value);
+
+void cxJsonDestroy(CxJson *json);
+```
+
+<warning>
+TODO: document
+</warning>
+
+### List of Status Codes
+
 <!--
-## Undocumented Symbols (TODO)
-### cxJsonArrAddCxStrings
-### cxJsonArrAddIntegers
-### cxJsonArrAddLiterals
-### cxJsonArrAddNumbers
-### cxJsonArrAddStrings
-### cxJsonArrAddValues
-### cxJsonArrGet
-### cxJsonArrIter
-### cxJsonCreateArr
-### cxJsonCreateCxString
-### cxJsonCreateInteger
-### cxJsonCreateLiteral
-### cxJsonCreateNumber
-### cxJsonCreateObj
-### cxJsonCreateString
-### cxJsonDestroy
-### cxJsonFilln
-### cxJsonInit
-### cxJsonNext
-### cx_json_obj_get_cxstr
-### cxJsonObjIter
-### cxJsonObjPut
-### cxJsonObjPutArr
-### cxJsonObjPutCxString
-### cxJsonObjPutInteger
-### cxJsonObjPutLiteral
-### cxJsonObjPutNumber
-### cxJsonObjPutObj
-### cxJsonObjPutString
-### cxJsonValueFree
-### cxJsonWrite
-### cxJsonWriterCompact
-### cx_json_write_rec
-### cxJsonWriterPretty
+    /**
+     * Everything is fine.
+     */
+    CX_JSON_NO_ERROR,
+    /**
+     * The input buffer does not contain more data.
+     */
+    CX_JSON_NO_DATA,
+    /**
+     * The input ends unexpectedly.
+     *
+     * Refill the buffer with cxJsonFill() to complete the json data.
+     */
+    CX_JSON_INCOMPLETE_DATA,
+    /**
+     * Not used as a status and never returned by any function.
+     *
+     * You can use this enumerator to check for all "good" status results
+     * by checking if the status is less than @c CX_JSON_OK.
+     *
+     * A "good" status means, that you can refill data and continue parsing.
+     */
+    CX_JSON_OK,
+    /**
+     * The input buffer has never been filled.
+     */
+    CX_JSON_NULL_DATA,
+    /**
+     * Allocating memory for the internal buffer failed.
+     */
+    CX_JSON_BUFFER_ALLOC_FAILED,
+    /**
+     * Allocating memory for a json value failed.
+     */
+    CX_JSON_VALUE_ALLOC_FAILED,
+    /**
+     * A number value is incorrectly formatted.
+     */
+    CX_JSON_FORMAT_ERROR_NUMBER,
+    /**
+     * The tokenizer found something unexpected.
+     */
+    CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN
 -->
+
+## Access Values
+
+```C
+#include <cx/json.h>
+
+bool cxJsonIsObject(const CxJsonValue *value);
+
+bool cxJsonIsArray(const CxJsonValue *value);
+
+bool cxJsonIsString(const CxJsonValue *value);
+
+bool cxJsonIsNumber(const CxJsonValue *value);
+
+bool cxJsonIsInteger(const CxJsonValue *value);
+
+bool cxJsonIsLiteral(const CxJsonValue *value);
+
+bool cxJsonIsBool(const CxJsonValue *value);
+
+bool cxJsonIsTrue(const CxJsonValue *value);
+
+bool cxJsonIsFalse(const CxJsonValue *value);
+
+bool cxJsonIsNull(const CxJsonValue *value);
+
+char *cxJsonAsString(const CxJsonValue *value);
+
+cxstring cxJsonAsCxString(const CxJsonValue *value);
+
+cxmutstr cxJsonAsCxMutStr(const CxJsonValue *value);
+
+double cxJsonAsDouble(const CxJsonValue *value);
+
+int64_t cxJsonAsInteger(const CxJsonValue *value);
+
+bool cxJsonAsBool(const CxJsonValue *value);
+
+size_t cxJsonArrSize(const CxJsonValue *value);
+
+CxJsonValue *cxJsonArrGet(const CxJsonValue *value, size_t index);
+
+CxJsonValue *cxJsonObjGet(const CxJsonValue *value, AnyStr name);
+
+CxIterator cxJsonArrIter(const CxJsonValue *value);
+
+CxIterator cxJsonObjIter(const CxJsonValue *value);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Deallocate Memory
+
+```C
+#include <cx/json.h>
+
+void cxJsonValueFree(CxJsonValue *value);
+```
+
+Once a JSON value is not needed anymore, the memory can be deallocated with `cxJsonValueFree()`.
+Nested values are also recursively deallocated. 
+
+> Make sure that you are not accidentally deallocating values that are still part of an object or array.
+> When deallocating the enclosing object/array, this will lead to a double-free.
+>{style="warning"}
+
+## Create Objects
+
+```C
+#include <cx/json.h>
+
+CxJsonValue* cxJsonCreateObj(const CxAllocator* allocator);
+
+CxJsonValue* cxJsonCreateArr(const CxAllocator* allocator);
+
+CxJsonValue* cxJsonCreateNumber(
+        const CxAllocator* allocator, double num);
+
+CxJsonValue* cxJsonCreateInteger(
+        const CxAllocator* allocator, int64_t num);
+
+CxJsonValue* cxJsonCreateString(const CxAllocator* allocator,
+        const char *str);
+
+CxJsonValue* cxJsonCreateCxString(
+        const CxAllocator* allocator, cxstring str);
+
+CxJsonValue* cxJsonCreateLiteral(
+        const CxAllocator* allocator, CxJsonLiteral lit);
+
+int cxJsonArrAddNumbers(CxJsonValue* arr,
+        const double* num, size_t count);
+
+int cxJsonArrAddIntegers(CxJsonValue* arr,
+        const int64_t* num, size_t count);
+
+int cxJsonArrAddStrings(CxJsonValue* arr,
+        const char* const* str, size_t count);
+
+int cxJsonArrAddCxStrings(CxJsonValue* arr,
+        const cxstring* str, size_t count);
+
+int cxJsonArrAddLiterals(CxJsonValue* arr,
+        const CxJsonLiteral* lit, size_t count);
+
+int cxJsonArrAddValues(CxJsonValue* arr,
+        CxJsonValue* const* val, size_t count);
+
+int cxJsonObjPut(CxJsonValue* obj, cxstring name, CxJsonValue* child);
+
+CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, cxstring name);
+
+CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, cxstring name);
+
+CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj,
+        cxstring name, double num);
+
+CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj,
+        cxstring name, int64_t num);
+
+CxJsonValue* cxJsonObjPutString(CxJsonValue* obj,
+        cxstring name, const char* str);
+
+CxJsonValue* cxJsonObjPutCxString(CxJsonValue* obj,
+        cxstring name, cxstring str);
+
+CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj,
+        cxstring name, CxJsonLiteral lit);
+```
+
+<warning>
+TODO: document
+</warning>
+
+## Writer
+
+```C
+#include <cx/json.h>
+
+typedef struct cx_json_writer_s {
+    bool pretty;
+    bool sort_members;
+    uint8_t frac_max_digits;
+    bool indent_space;
+    uint8_t indent;
+    bool escape_slash;
+} CxJsonWriter;
+
+CxJsonWriter cxJsonWriterCompact(void);
+
+CxJsonWriter cxJsonWriterPretty(bool use_spaces);
+
+int cxJsonWrite(void* target, const CxJsonValue* value,
+        cx_write_func wfunc, const CxJsonWriter* settings);
+```
+
+<warning>
+TODO: document
+</warning>
+
 <seealso>
 <category ref="apidoc">
 <a href="https://ucx.sourceforge.io/api/json_8h.html">json.h</a>