docs/Writerside/topics/json.h.md

# JSON

<warning>
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

<!--
    /**
     * 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>
</category>
</seealso>