about.md- allocator.h.md
- array_list.h.md
- buffer.h.md
- collection.h.md
- collections.md
- compare.h.md
- features.md
- hash_key.h.md
- hash_map.h.md
- install.md
- iterator.h.md
- json.h.md
- kv_list.h.md
- license.md
- linked_list.h.md
- list.h.md
- map.h.md
- memory.md
- mempool.h.md
- parsers.md
- printf.h.md
- properties.h.md
- streams.h.md
- string.h.md
- strings.md
- test.h.md
- tree.h.md
- utils.md
# JSON
The UCX JSON API allows [parsing](#parser) and [formatting](#writer) of JSON data.
The parser API is similar to the [properties](properties.h.md) parser,
but - due to the nature of JSON - is not allocation-free.
## Parser
The following listing shows the JSON parser API.
> To simplify documentation, we introduce the pseudo-type `AnyStr` with the meaning that
> any UCX string and any C string are supported.
> The implementation is actually hidden behind a macro which uses `cx_strcast()` to guarantee compatibility.
{style="note"}
```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);
CxJsonStatus cxJsonFromString(const CxAllocator *allocator,
AnyStr str, CxJsonValue **value);
```
The first step is to initialize a `CxJson` structure with a call to `cxJsonInit()`,
specifying the allocator that shall be used for allocating values of type `CxJsonValue`.
Specifying `NULL` as `allocator` is allowed, in which case the `cxDefaultAllocator` will be used.
The actual parsing is an interleaving invocation of the `cxJsonFill()` (or `cxJsonFilln()`) and `cxJsonNext()` functions.
The `cxJsonFill()` function is a convenience function that accepts UCX strings and normal zero-terminated C strings.
Calling `cxJsonNext()` will return with `CX_JSON_NO_ERROR` (= zero) for each JSON value that is successfully parsed,
and stores the pointer to the allocated value in the variable pointed to by `value`.
> The parser is capable of parsing multiple consecutive JSON values.
> If those values are not objects or arrays, they must, however, be separated by any whitespace character.
When all the data from the input buffer was successfully consumed, `cxJsonNext()` returns `CX_JSON_NO_DATA`.
If `cxJsonNext()` returns `CX_JSON_INCOMPLETE_DATA` it means that the input buffer is exhausted,
but the parsed input does not constitute a complete JSON value.
In that case, you can call `cxJsonFill()` again to add more data and continue with `cxJsonNext()`.
A complete list of all status codes can be seen [below](#list-of-status-codes).
If you want to reuse a `CxJson` structure, you can call `cxJsonReset()`.
In particular, you _must_ reset the parser when the last operation was a failure.
Otherwise, you need to call `cxJsonDestroy()` when you are done with the parser.
The function `cxJsonFromString()` combines the above procedure.
### List of Status Codes
Below is a full list of status codes for `cxJsonNext()`.
| Status Code | Meaning |
|---------------------------------------|---------------------------------------------------------------------------------------------------|
| CX_JSON_NO_ERROR | A value was successfully parsed. | |
| CX_JSON_NO_DATA | The input buffer does not contain more data. |
| CX_JSON_INCOMPLETE_DATA | The input ends unexpectedly. Use `cxJsonFill()` to add more data before retrying. |
| CX_JSON_NULL_DATA | The input buffer was never initialized. Probably you forgot to call `cxJsonFill()` at least once. |
| CX_JSON_BUFFER_ALLOC_FAILED | More internal buffer was needed, but could not be allocated. |
| CX_JSON_VALUE_ALLOC_FAILED | Allocating memory for a json value failed. |
| CX_JSON_FORMAT_ERROR_NUMBER | A number value is incorrectly formatted. |
| CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN | The tokenizer found something unexpected, i.e. the JSON string contains a syntax error. |
## 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 *cxJsonArrRemove(const CxJsonValue *value, size_t index);
size_t cxJsonObjSize(const CxJsonValue *value);
CxJsonValue *cxJsonObjGet(const CxJsonValue *value, AnyStr name);
CxJsonValue *cxJsonObjRemove(const CxJsonValue *value, AnyStr name);
CxIterator cxJsonArrIter(const CxJsonValue *value);
CxIterator cxJsonObjIter(const CxJsonValue *value);
```
The `cxJsonIsXYZ()` family functions check the type of the specified JSON value.
The JSON specification only defines numbers, therefore `cxJsonIsNumber()` returns true for both floating-point and integer numbers.
On the other hand, `cxJsonIsInteger()` only returns true for integral numbers.
The function `cxJsonIsBool()` returns true if `cxJsonIsLiteral()` returns true, but `cxJsonIsNull()` does not.
> Since a literal can be `true`, `false`, or `null`, note carefully that `!cxJsonIsTrue(v)`
> is in general _not_ equivalent to `cxJsonIsFalse(v)`.
>
> Additionally, UCX does implement the JavaScript concept of a "falsy" value, meaning that
> `cxJsonIsFalse()` _only_ returns true, if the value is a literal `false`.
>{style="note"}
The `cxJsonAsXYZ()` family of functions return the value with its corresponding C type.
The functions `cxJsonAsInteger()` and `cxJsonAsDouble()` can be used for any number value.
For example, if `cxJsonAsInteger()` is used on a non-integral number, a double-to-int conversion is performed.
The function `cxJsonArraySize()` returns the number of items in an array value,
which can be accessed via index with `cxJsonArrGet()` or via an iterator created with `cxJsonArrIter()`.
An element can be removed from an array with `cxJsonArrRemove()`.
The function `cxJsonObjGet()` returns the member in a JSON object associated with the specified `name`.
To remove a member, use `cxJsonObjRemove()`.
> Both `cxJsonArrGet()` and `cxJsonObjGet()` are safe regarding access to non-existing values.
>
> When `cxJsonArrGet()` is used with an out-of-bounds index, or `cxJsonObjGet()` is used with a non-existent name,
> they return a JSON value, that returns `false` for any `cxJsonIsXYZ()` function.
>
> This is **not** the case for `cxJsonArrRemove()` and `cxJsonObjRemove()`, which return `NULL` in that case.
> If you don't have full control over the JSON data, you should always check the datatype of a value first before accessing it.
>{style="note"}
## Compare Values
```C
#include <cx/json.h>
int cxJsonCompare(const CxJsonValue *value,
const CxJsonValue *other);
```
The function `cxJsonCompare()` performs a deep comparison of two JSON values.
It returns zero if both values are equal except for the order of object members.
When the values are not equal, the return-value is an unspecified non-zero value.
## 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,
AnyStr 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, AnyStr name, CxJsonValue* child);
CxJsonValue* cxJsonObjPutObj(CxJsonValue* obj, AnyStr name);
CxJsonValue* cxJsonObjPutArr(CxJsonValue* obj, AnyStr name);
CxJsonValue* cxJsonObjPutNumber(CxJsonValue* obj,
AnyStr name, double num);
CxJsonValue* cxJsonObjPutInteger(CxJsonValue* obj,
AnyStr name, int64_t num);
CxJsonValue* cxJsonObjPutString(CxJsonValue* obj,
AnyStr name, AnyStr str);
CxJsonValue* cxJsonObjPutLiteral(CxJsonValue* obj,
AnyStr name, CxJsonLiteral lit);
```
The `cxJsonCreateXY()`-family of functions can be used to create JSON values which are allocated by the specified `allocator`.
If you specify `NULL` as allocator, the `cxDefaultAllocator` is used.
If you want to add created values to a JSON array or JSON object,
you can use `cxJsonArrAddValues()` or `cxJsonObjPut()`, respectively.
However, it is usually more convenient to use one of the other functions, as they automatically create the JSON value for.
```C
#include <cx/json.h>
CxJsonValue* arr = cxJsonCreateArr(NULL);
// this is equivalent...
CxJsonValue* x = cxJsonCreateInteger(NULL, 47);
CxJsonValue* y = cxJsonCreateInteger(NULL, 11);
cxJsonArrAddValues(arr, (CxJsonValue*[]){x, y}, 2);
// ... to this
cxJsonArrAddIntegers(arr, (int64_t[]){47, 11}, 2);
```
The following example shows how to construct a complete JSON object.
```C
CxJsonValue *obj = cxJsonCreateObj(NULL);
cxJsonObjPutLiteral(obj, "bool", CX_JSON_FALSE);
cxJsonObjPutInteger(obj, "int", 47);
CxJsonValue *strings = cxJsonObjPutArr(obj, "strings");
cxJsonArrAddStrings(strings, (const char*[]) {"hello", "world"}, 2);
CxJsonValue *nested = cxJsonObjPutObj(obj, "nested");
CxJsonValue *objects = cxJsonObjPutArr(nested, "objects");
CxJsonValue *obj_in_arr[2] = {
cxJsonCreateObj(NULL),
cxJsonCreateObj(NULL),
};
cxJsonObjPutInteger(obj_in_arr[0], "name1", 1);
cxJsonObjPutInteger(obj_in_arr[0], "name2", 3);
cxJsonObjPutInteger(obj_in_arr[1], "name2", 7);
cxJsonObjPutInteger(obj_in_arr[1], "name1", 3);
cxJsonArrAddValues(objects, obj_in_arr, 2);
cxJsonArrAddNumbers(cxJsonObjPutArr(nested, "floats"),
(double[]){3.1415, 47.11, 8.15}, 3);
cxJsonArrAddLiterals(cxJsonObjPutArr(nested, "literals"),
(CxJsonLiteral[]){CX_JSON_TRUE, CX_JSON_NULL, CX_JSON_FALSE}, 3);
CxJsonValue *ints = cxJsonObjPutArr(nested, "ints");
cxJsonArrAddIntegers(ints, (int64_t[]){4, 8, 15}, 3);
CxJsonValue *nested_array = cxJsonCreateArr(NULL);
cxJsonArrAddValues(ints, &nested_array, 1);
cxJsonArrAddIntegers(nested_array, (int64_t[]){16, 23}, 2);
cxJsonArrAddIntegers(ints, (int64_t[]){42}, 1);
CxJsonWriter w = cxJsonWriterPretty(true);
cxJsonWrite(stdout, obj, (cx_write_func) fwrite, &w);
cxJsonValueFree(obj);
```
The above code writes the following output to `stdout`:
```JSON
{
"bool": false,
"int": 47,
"strings": ["hello", "world"],
"nested": {
"objects": [{
"name1": 1,
"name2": 3
}, {
"name2": 7,
"name1": 3
}],
"floats": [3.1415, 47.11, 8.15],
"literals": [true, null, false],
"ints": [4, 8, 15, [16, 23], 42]
}
}
```
## Writer
```C
#include <cx/json.h>
typedef struct cx_json_writer_s {
bool pretty;
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);
cxmutstr cxJsonToString(CxJsonValue *value,
const CxAllocator *allocator);
cxmutstr cxJsonToPrettyString(CxJsonValue *value,
const CxAllocator *allocator);
```
A JSON value can be formatted with the `cxJsonWrite()` function.
The `target` can be a stream, a UCX [buffer](buffer.h.md), or anything else that can be written to with a write function.
The behavior of the function is controlled via a `CxJsonWriter` struct.
With the functions `cxJsonWriterCompact()` and `cxJsonWriterPretty()` you can create default settings,
which you may modify to suit your needs (see the table below).
The functions `cxJsonToString()` and `cxJsonToPrettyString()` are convenience functions
which create a writer with default settings to produce a null-terminated string allocated by the specified allocator.
| Setting | Compact Default | Pretty Default | Description |
|-------------------|-----------------|----------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `pretty` | `false` | `true` | If true, the JSON will be formatted with line breaks and tabs or spaces. If false, output is as compact as possible without extra characters. |
| `frac_max_digits` | 6 | 6 | The maximum number of fractional digits in a number value. |
| `indent_space` | ignored | depends on `use_spaces` argument | If true, use spaces for indentation, otherwise use tabs. |
| `indent` | ignored | 4 | If `indent_space` is `true`, this is the number of spaces per tab. Ignored otherwise. |
| `escape_slash` | `false` | `false` | If `true`, the slash character (a.k.a forward solidus: `/`) is also escaped. This is usually only needed when you want to use JSON as part of an HTML attribute. |
<seealso>
<category ref="apidoc">
<a href="https://ucx.sourceforge.io/api/json_8h.html">json.h</a>
</category>
</seealso>