Interface for parsing data from JSON files. More...

#include "common.h"
#include "allocator.h"
#include "string.h"
#include "buffer.h"
#include "array_list.h"

Data Structures
struct	cx_json_array_s
	JSON array structure. More...

struct	cx_json_object_s
	JSON object structure. More...

struct	cx_json_obj_value_s
	Structure for a key/value entry in a JSON object. More...

struct	cx_json_value_s
	Structure for a JSON value. More...

struct	cx_json_token_s
	Internally used structure for a parsed token. More...

struct	cx_json_s
	The JSON parser interface. More...

struct	cx_json_writer_s
	The JSON writer settings. More...

Macros
#define	cxJsonFill(json, str)
	Fills the input buffer.

#define	cxJsonCreateString(allocator, str)
	Creates a new JSON string.

#define	cxJsonObjPut(obj, name, child)
	Adds or replaces a value within a JSON object.

#define	cxJsonObjPutObj(obj, name)
	Creates a new JSON object and adds it to an existing object.

#define	cxJsonObjPutArr(obj, name)
	Creates a new JSON array and adds it to an object.

#define	cxJsonObjPutNumber(obj, name, num)
	Creates a new JSON number and adds it to an object.

#define	cxJsonObjPutInteger(obj, name, num)
	Creates a new JSON number, based on an integer, and adds it to an object.

#define	cxJsonObjPutString(obj, name, str)
	Creates a new JSON string and adds it to an object.

#define	cxJsonObjPutLiteral(obj, name, lit)
	Creates a new JSON literal and adds it to an object.

#define	cxJsonObjGet(value, name)
	Returns a value corresponding to a key in a JSON object.

#define	cxJsonObjRemove(value, name)
	Removes and returns a value corresponding to a key in a JSON object.

Typedefs
typedef enum cx_json_token_type	CxJsonTokenType
	Type alias for the token type enum.

typedef enum cx_json_value_type	CxJsonValueType
	Type alias for the value type enum.

typedef struct cx_json_s	CxJson
	Type alias for the JSON parser interface.

typedef struct cx_json_token_s	CxJsonToken
	Type alias for the token struct.

typedef struct cx_json_value_s	CxJsonValue
	Type alias for the JSON value struct.

typedef struct cx_json_array_s	CxJsonArray
	Type alias for the JSON array struct.

typedef struct cx_json_object_s	CxJsonObject
	Type alias for the JSON object struct.

typedef struct cx_mutstr_s	CxJsonString
	Type alias for a JSON string.

typedef int64_t	CxJsonInteger
	Type alias for a number that can be represented as a 64-bit signed integer.

typedef double	CxJsonNumber
	Type alias for a number that is not an integer.

typedef enum cx_json_literal	CxJsonLiteral
	Type alias for a JSON literal.

typedef struct cx_json_obj_value_s	CxJsonObjValue
	Type alias for a key/value pair in a JSON object.

typedef enum cx_json_status	CxJsonStatus
	Typedef for the JSON status enum.

typedef struct cx_json_writer_s	CxJsonWriter
	Typedef for the JSON writer.

Enumerations
enum	cx_json_token_type { CX_JSON_NO_TOKEN , CX_JSON_TOKEN_ERROR , CX_JSON_TOKEN_BEGIN_ARRAY , CX_JSON_TOKEN_BEGIN_OBJECT , CX_JSON_TOKEN_END_ARRAY , CX_JSON_TOKEN_END_OBJECT , CX_JSON_TOKEN_NAME_SEPARATOR , CX_JSON_TOKEN_VALUE_SEPARATOR , CX_JSON_TOKEN_STRING , CX_JSON_TOKEN_INTEGER , CX_JSON_TOKEN_NUMBER , CX_JSON_TOKEN_LITERAL , CX_JSON_TOKEN_SPACE }
	The type of the parsed token. More...

enum	cx_json_value_type { CX_JSON_NOTHING , CX_JSON_OBJECT , CX_JSON_ARRAY , CX_JSON_STRING , CX_JSON_INTEGER , CX_JSON_NUMBER , CX_JSON_LITERAL }
	The type of some JSON value. More...

enum	cx_json_literal { CX_JSON_NULL , CX_JSON_TRUE , CX_JSON_FALSE }
	JSON literal types. More...

enum	cx_json_status { CX_JSON_NO_ERROR , CX_JSON_NO_DATA , CX_JSON_INCOMPLETE_DATA , CX_JSON_OK , CX_JSON_NULL_DATA , CX_JSON_BUFFER_ALLOC_FAILED , CX_JSON_VALUE_ALLOC_FAILED , CX_JSON_FORMAT_ERROR_NUMBER , CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN }
	Status codes for the JSON interface. More...

Functions
CxJsonWriter	cxJsonWriterCompact (void)
	Creates a default writer configuration for compact output.

CxJsonWriter	cxJsonWriterPretty (bool use_spaces)
	Creates a default writer configuration for pretty output.

int	cxJsonWrite (void target, const CxJsonValue value, cx_write_func wfunc, const CxJsonWriter *settings)
	Writes a JSON value to a buffer or stream.

void	cxJsonInit (CxJson json, const CxAllocator allocator)
	Initializes the JSON interface.

void	cxJsonDestroy (CxJson *json)
	Destroys the JSON interface.

void	cxJsonReset (CxJson *json)
	Destroys and re-initializes the JSON interface.

int	cxJsonFilln (CxJson json, const char buf, size_t len)
	Fills the input buffer.

static int	cx_json_fill (CxJson *json, cxstring str)
	Internal function, do not use.

CxJsonValue *	cxJsonCreateObj (const CxAllocator *allocator)
	Creates a new (empty) JSON object.

CxJsonValue *	cxJsonCreateArr (const CxAllocator *allocator)
	Creates a new (empty) JSON array.

CxJsonValue *	cxJsonCreateNumber (const CxAllocator *allocator, double num)
	Creates a new JSON number value.

CxJsonValue *	cxJsonCreateInteger (const CxAllocator *allocator, int64_t num)
	Creates a new JSON number value based on an integer.

CxJsonValue *	cx_json_create_string (const CxAllocator *allocator, cxstring str)
	Creates a new JSON string.

CxJsonValue *	cxJsonCreateLiteral (const CxAllocator *allocator, CxJsonLiteral lit)
	Creates a new JSON literal.

int	cxJsonArrAddNumbers (CxJsonValue arr, const double num, size_t count)
	Adds number values to a JSON array.

int	cxJsonArrAddIntegers (CxJsonValue arr, const int64_t num, size_t count)
	Adds number values, of which all are integers, to a JSON array.

int	cxJsonArrAddStrings (CxJsonValue arr, const char const *str, size_t count)
	Adds strings to a JSON array.

int	cxJsonArrAddCxStrings (CxJsonValue arr, const cxstring str, size_t count)
	Adds strings to a JSON array.

int	cxJsonArrAddLiterals (CxJsonValue arr, const CxJsonLiteral lit, size_t count)
	Adds literals to a JSON array.

int	cxJsonArrAddValues (CxJsonValue arr, CxJsonValue const *val, size_t count)
	Add arbitrary values to a JSON array.

int	cx_json_obj_put (CxJsonValue obj, cxstring name, CxJsonValue child)
	Adds or replaces a value within a JSON object.

CxJsonValue *	cx_json_obj_put_obj (CxJsonValue *obj, cxstring name)
	Creates a new JSON object and adds it to an existing object.

CxJsonValue *	cx_json_obj_put_arr (CxJsonValue *obj, cxstring name)
	Creates a new JSON array and adds it to an object.

CxJsonValue *	cx_json_obj_put_number (CxJsonValue *obj, cxstring name, double num)
	Creates a new JSON number and adds it to an object.

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.

CxJsonValue *	cx_json_obj_put_string (CxJsonValue *obj, cxstring name, cxstring str)
	Creates a new JSON string and adds it to an object.

CxJsonValue *	cx_json_obj_put_literal (CxJsonValue *obj, cxstring name, CxJsonLiteral lit)
	Creates a new JSON literal and adds it to an object.

void	cxJsonValueFree (CxJsonValue *value)
	Recursively deallocates the memory of a JSON value.

CxJsonStatus	cxJsonNext (CxJson json, CxJsonValue *value)
	Tries to obtain the next JSON value.

static bool	cxJsonIsObject (const CxJsonValue *value)
	Checks if the specified value is a JSON object.

static bool	cxJsonIsArray (const CxJsonValue *value)
	Checks if the specified value is a JSON array.

static bool	cxJsonIsString (const CxJsonValue *value)
	Checks if the specified value is a string.

static bool	cxJsonIsNumber (const CxJsonValue *value)
	Checks if the specified value is a JSON number.

static bool	cxJsonIsInteger (const CxJsonValue *value)
	Checks if the specified value is an integer number.

static bool	cxJsonIsLiteral (const CxJsonValue *value)
	Checks if the specified value is a JSON literal.

static bool	cxJsonIsBool (const CxJsonValue *value)
	Checks if the specified value is a Boolean literal.

static bool	cxJsonIsTrue (const CxJsonValue *value)
	Checks if the specified value is `true`.

static bool	cxJsonIsFalse (const CxJsonValue *value)
	Checks if the specified value is `false`.

static bool	cxJsonIsNull (const CxJsonValue *value)
	Checks if the specified value is `null`.

char *	cxJsonAsString (const CxJsonValue *value)
	Obtains a C string from the given JSON value.

cxstring	cxJsonAsCxString (const CxJsonValue *value)
	Obtains a UCX string from the given JSON value.

cxmutstr	cxJsonAsCxMutStr (const CxJsonValue *value)
	Obtains a mutable UCX string from the given JSON value.

double	cxJsonAsDouble (const CxJsonValue *value)
	Obtains a double-precision floating-point value from the given JSON value.

int64_t	cxJsonAsInteger (const CxJsonValue *value)
	Obtains a 64-bit signed integer from the given JSON value.

static bool	cxJsonAsBool (const CxJsonValue *value)
	Obtains a Boolean value from the given JSON value.

static size_t	cxJsonArrSize (const CxJsonValue *value)
	Returns the size of a JSON array.

CxJsonValue *	cxJsonArrGet (const CxJsonValue *value, size_t index)
	Returns an element from a JSON array.

CxJsonValue *	cxJsonArrRemove (CxJsonValue *value, size_t index)
	Removes an element from a JSON array.

CxIterator	cxJsonArrIter (const CxJsonValue *value)
	Returns an iterator over the JSON array elements.

static size_t	cxJsonObjSize (const CxJsonValue *value)
	Returns the size of a JSON object.

CxIterator	cxJsonObjIter (const CxJsonValue *value)
	Returns an iterator over the JSON object members.

CxJsonValue *	cx_json_obj_get (const CxJsonValue *value, cxstring name)
	Internal function, do not use.

CxJsonValue *	cx_json_obj_remove (CxJsonValue *value, cxstring name)
	Internal function, do not use.

Detailed Description

Interface for parsing data from JSON files.

Author: Mike Becker; Olaf Wintermann

Copyright: 2-Clause BSD License

Macro Definition Documentation

◆ cxJsonCreateString

#define cxJsonCreateString	(		allocator,
			str )

Value:

cx_json_create_string(allocator, cx_strcast(str))

cx_json_create_string

CxJsonValue * cx_json_create_string(const CxAllocator *allocator, cxstring str)

Creates a new JSON string.

cx_strcast

#define cx_strcast(str)

Wraps any string into an UCX string.

Definition string.h:312

Creates a new JSON string.

Parameters

allocator	(`CxAllocator*`) the allocator to use
str	the string

Returns: (CxJsonValue*) the new JSON value or NULL if allocation fails

See also: cxJsonObjPutString(); cxJsonArrAddCxStrings()

◆ cxJsonFill

#define cxJsonFill	(		json,
			str )

Value:

cx_json_fill(json, cx_strcast(str))

cx_json_fill

static int cx_json_fill(CxJson *json, cxstring str)

Internal function, do not use.

Definition json.h:572

Fills the input buffer.

The JSON interface tries to avoid copying the input data. When you use this function and cxJsonNext() interleaving, no copies are performed. However, you must not free the pointer to the data in that case. When you invoke the fill function more than once before calling cxJsonNext(), the additional data is appended - inevitably leading to an allocation of a new buffer and copying the previous contents.

Parameters

json	the JSON interface
str	the source string

Return values

zero	success
non-zero	internal allocation error

See also: cxJsonFilln()

◆ cxJsonObjGet

#define cxJsonObjGet	(		value,
			name )

Value:

cx_json_obj_get(value, cx_strcast(name))

cx_json_obj_get

CxJsonValue * cx_json_obj_get(const CxJsonValue *value, cxstring name)

Internal function, do not use.

Returns a value corresponding to a key in a JSON object.

If the value is not a JSON object, the behavior is undefined.

This function guarantees to return a JSON value. If the object does not contain name, the returned JSON value will be of type CX_JSON_NOTHING, but never NULL.

Parameters

value	the JSON object
name	the key to look up

Returns: the value corresponding to the key

See also: cxJsonIsObject()

◆ cxJsonObjPut

#define cxJsonObjPut	(	obj,
		name,
		child )

Value:

cx_json_obj_put(obj, cx_strcast(name), child)

cx_json_obj_put

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 name already exists, it will be (recursively) freed with its own allocator.

Parameters

obj	(`CxJsonValue*`) the JSON object
name	(any string) the name of the value
child	(`CxJsonValue*`) the value

Return values

zero	success
non-zero	allocation failure

◆ cxJsonObjPutArr

#define cxJsonObjPutArr	(		obj,
			name )

Value:

cx_json_obj_put_arr(obj, cx_strcast(name))

cx_json_obj_put_arr

CxJsonValue * cx_json_obj_put_arr(CxJsonValue *obj, cxstring name)

Creates a new JSON array and adds it to an object.

Parameters

obj	(`CxJsonValue*`) the target JSON object
name	(any string) the name of the new value

Returns: (CxJsonValue*) the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateArr()

◆ cxJsonObjPutInteger

#define cxJsonObjPutInteger	(	obj,
		name,
		num )

Value:

cx_json_obj_put_integer(obj, cx_strcast(name), num)

cx_json_obj_put_integer

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.

Parameters

obj	(`CxJsonValue*`) the target JSON object
name	(any string) the name of the new value
num	(`int64_t`) the numeric value

Returns: (CxJsonValue*) the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateInteger()

◆ cxJsonObjPutLiteral

#define cxJsonObjPutLiteral	(	obj,
		name,
		lit )

Value:

cx_json_obj_put_literal(obj, cx_strcast(name), lit)

cx_json_obj_put_literal

CxJsonValue * cx_json_obj_put_literal(CxJsonValue *obj, cxstring name, CxJsonLiteral lit)

Creates a new JSON literal and adds it to an object.

Parameters

obj	(`CxJsonValue*`) the target JSON object
name	(any string) the name of the new value
lit	(`CxJsonLiteral`) the type of literal

Returns: (CxJsonValue*) the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateLiteral()

◆ cxJsonObjPutNumber

#define cxJsonObjPutNumber	(	obj,
		name,
		num )

Value:

cx_json_obj_put_number(obj, cx_strcast(name), num)

cx_json_obj_put_number

CxJsonValue * cx_json_obj_put_number(CxJsonValue *obj, cxstring name, double num)

Creates a new JSON number and adds it to an object.

Parameters

obj	(`CxJsonValue*`) the target JSON object
name	(any string) the name of the new value
num	(`double`) the numeric value

Returns: (CxJsonValue*) the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateNumber()

◆ cxJsonObjPutObj

#define cxJsonObjPutObj	(		obj,
			name )

Value:

cx_json_obj_put_obj(obj, cx_strcast(name))

cx_json_obj_put_obj

CxJsonValue * cx_json_obj_put_obj(CxJsonValue *obj, cxstring name)

Creates a new JSON object and adds it to an existing object.

Parameters

obj	(`CxJsonValue*`) the target JSON object
name	(any string) the name of the new value

Returns: (CxJsonValue*) the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateObj()

◆ cxJsonObjPutString

#define cxJsonObjPutString	(	obj,
		name,
		str )

Value:

cx_json_obj_put_string(obj, cx_strcast(name), cx_strcast(str))

cx_json_obj_put_string

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.

Parameters

obj	(`CxJsonValue*`) the target JSON object
name	(any string) the name of the new value
str	(any string) the string data

Returns: (CxJsonValue*) the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateString()

◆ cxJsonObjRemove

#define cxJsonObjRemove	(		value,
			name )

Value:

cx_json_obj_remove(value, cx_strcast(name))

cx_json_obj_remove

CxJsonValue * cx_json_obj_remove(CxJsonValue *value, cxstring name)

Internal function, do not use.

Removes and returns a value corresponding to a key in a JSON object.

If the value is not a JSON object, the behavior is undefined.

This function, in contrast to cxJsonObjGet() returns NULL when the object does not contain name.

Parameters

value	the JSON object
name	the key to look up

Returns: the value corresponding to the key or NULL when the key is not part of the object

See also: cxJsonIsObject()

Enumeration Type Documentation

◆ cx_json_literal

enum cx_json_literal

JSON literal types.

Enumerator
CX_JSON_NULL	The `null` literal.
CX_JSON_TRUE	The `true` literal.
CX_JSON_FALSE	The `false` literal.

◆ cx_json_status

enum cx_json_status

Status codes for the JSON interface.

Enumerator
CX_JSON_NO_ERROR	Everything is fine.
CX_JSON_NO_DATA	The input buffer does not contain more data.
CX_JSON_INCOMPLETE_DATA	The input ends unexpectedly. Refill the buffer with cxJsonFill() to complete the JSON data.
CX_JSON_OK	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 `CX_JSON_OK`. A "good" status means that you can refill data and continue parsing.
CX_JSON_NULL_DATA	The input buffer has never been filled.
CX_JSON_BUFFER_ALLOC_FAILED	Allocating memory for the internal buffer failed.
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.

◆ cx_json_token_type

enum cx_json_token_type

The type of the parsed token.

Enumerator
CX_JSON_NO_TOKEN	No complete token parsed, yet.
CX_JSON_TOKEN_ERROR	The presumed token contains syntactical errors.
CX_JSON_TOKEN_BEGIN_ARRAY	A "begin of array" '[' token.
CX_JSON_TOKEN_BEGIN_OBJECT	A "begin of object" '{' token.
CX_JSON_TOKEN_END_ARRAY	An "end of array" ']' token.
CX_JSON_TOKEN_END_OBJECT	An "end of object" '}' token.
CX_JSON_TOKEN_NAME_SEPARATOR	A colon ':' token separating names and values.
CX_JSON_TOKEN_VALUE_SEPARATOR	A comma ',' token separating object entries or array elements.
CX_JSON_TOKEN_STRING	A string token.
CX_JSON_TOKEN_INTEGER	A number token that can be represented as an integer.
CX_JSON_TOKEN_NUMBER	A number token that cannot be represented as an integer.
CX_JSON_TOKEN_LITERAL	A literal token.
CX_JSON_TOKEN_SPACE	A white-space token.

◆ cx_json_value_type

enum cx_json_value_type

The type of some JSON value.

Enumerator
CX_JSON_NOTHING	Reserved.
CX_JSON_OBJECT	A JSON object.
CX_JSON_ARRAY	A JSON array.
CX_JSON_STRING	A string.
CX_JSON_INTEGER	A number that contains an integer.
CX_JSON_NUMBER	A number, not necessarily an integer.
CX_JSON_LITERAL	A literal (true, false, null).

Function Documentation

◆ cx_json_create_string()

CxJsonValue * cx_json_create_string	(	const CxAllocator *	allocator,
		cxstring	str )

Creates a new JSON string.

Internal function - use cxJsonCreateString() instead.

Parameters

allocator	the allocator to use
str	the string data

Returns: the new JSON value or NULL if allocation fails

See also: cxJsonObjPutString(); cxJsonArrAddCxStrings()

◆ cx_json_fill()

static int cx_json_fill	(	CxJson *	json,
		cxstring	str )

inlinestatic

Internal function, do not use.

Parameters

json	the JSON interface
str	the string

Return values

zero	success
non-zero	internal allocation error

◆ cx_json_obj_get()

CxJsonValue * cx_json_obj_get	(	const CxJsonValue *	value,
		cxstring	name )

Internal function, do not use.

Parameters

value	the JSON object
name	the key to look up

Returns: the value corresponding to the key

◆ cx_json_obj_put()

int cx_json_obj_put	(	CxJsonValue *	obj,
		cxstring	name,
		CxJsonValue *	child )

Adds or replaces a value within a JSON object.

Internal function - use cxJsonObjPut().

Parameters

obj	the JSON object
name	the name of the value
child	the value

Return values

zero	success
non-zero	allocation failure

◆ cx_json_obj_put_arr()

CxJsonValue * cx_json_obj_put_arr	(	CxJsonValue *	obj,
		cxstring	name )

Creates a new JSON array and adds it to an object.

Internal function - use cxJsonObjPutArr().

Parameters

obj	the target JSON object
name	the name of the new value

Returns: the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateArr()

◆ cx_json_obj_put_integer()

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.

Internal function - use cxJsonObjPutInteger().

Parameters

obj	the target JSON object
name	the name of the new value
num	the numeric value

Returns: the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateInteger()

◆ cx_json_obj_put_literal()

CxJsonValue * cx_json_obj_put_literal	(	CxJsonValue *	obj,
		cxstring	name,
		CxJsonLiteral	lit )

Creates a new JSON literal and adds it to an object.

Internal function - use cxJsonObjPutLiteral().

Parameters

obj	the target JSON object
name	the name of the new value
lit	the type of literal

Returns: the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateLiteral()

◆ cx_json_obj_put_number()

CxJsonValue * cx_json_obj_put_number	(	CxJsonValue *	obj,
		cxstring	name,
		double	num )

Creates a new JSON number and adds it to an object.

Internal function - use cxJsonObjPutNumber().

Parameters

obj	the target JSON object
name	the name of the new value
num	the numeric value

Returns: the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateNumber()

◆ cx_json_obj_put_obj()

CxJsonValue * cx_json_obj_put_obj	(	CxJsonValue *	obj,
		cxstring	name )

Creates a new JSON object and adds it to an existing object.

Internal function - use cxJsonObjPutObj().

Parameters

obj	the target JSON object
name	the name of the new value

Returns: the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateObj()

◆ cx_json_obj_put_string()

CxJsonValue * cx_json_obj_put_string	(	CxJsonValue *	obj,
		cxstring	name,
		cxstring	str )

Creates a new JSON string and adds it to an object.

Internal function - use cxJsonObjPutString()

Parameters

obj	the target JSON object
name	the name of the new value
str	the string data

Returns: the new value or NULL if allocation fails

See also: cxJsonObjPut(); cxJsonCreateString()

◆ cx_json_obj_remove()

CxJsonValue * cx_json_obj_remove	(	CxJsonValue *	value,
		cxstring	name )

Internal function, do not use.

Parameters

value	the JSON object
name	the key to look up

Returns: the value corresponding to the key or NULL when the key is not part of the object

◆ cxJsonArrAddCxStrings()

int cxJsonArrAddCxStrings	(	CxJsonValue *	arr,
		const cxstring *	str,
		size_t	count )

Adds strings to a JSON array.

The strings will be copied with the allocator of the array.

Parameters

arr	the JSON array
str	the array of strings
count	the number of elements

Return values

zero	success
non-zero	allocation failure

See also: cxJsonArrAddStrings()

◆ cxJsonArrAddIntegers()

int cxJsonArrAddIntegers	(	CxJsonValue *	arr,
		const int64_t *	num,
		size_t	count )

Adds number values, of which all are integers, to a JSON array.

Parameters

arr	the JSON array
num	the array of values
count	the number of elements

Return values

zero	success
non-zero	allocation failure

◆ cxJsonArrAddLiterals()

int cxJsonArrAddLiterals	(	CxJsonValue *	arr,
		const CxJsonLiteral *	lit,
		size_t	count )

Adds literals to a JSON array.

Parameters

arr	the JSON array
lit	the array of literal types
count	the number of elements

Return values

zero	success
non-zero	allocation failure

◆ cxJsonArrAddNumbers()

int cxJsonArrAddNumbers	(	CxJsonValue *	arr,
		const double *	num,
		size_t	count )

Adds number values to a JSON array.

Parameters

arr	the JSON array
num	the array of values
count	the number of elements

Return values

zero	success
non-zero	allocation failure

◆ cxJsonArrAddStrings()

int cxJsonArrAddStrings	(	CxJsonValue *	arr,
		const char const	str,
		size_t	count )

Adds strings to a JSON array.

The strings will be copied with the allocator of the array.

Parameters

arr	the JSON array
str	the array of strings
count	the number of elements

Return values

zero	success
non-zero	allocation failure

See also: cxJsonArrAddCxStrings()

◆ cxJsonArrAddValues()

int cxJsonArrAddValues	(	CxJsonValue *	arr,
		CxJsonValue const	val,
		size_t	count )

Add arbitrary values to a JSON array.

Attention: In contrast to all other add functions, this function adds the values directly to the array instead of copying them.

Parameters

arr	the JSON array
val	the values
count	the number of elements

Return values

zero	success
non-zero	allocation failure

◆ cxJsonArrGet()

CxJsonValue * cxJsonArrGet	(	const CxJsonValue *	value,
		size_t	index )

Returns an element from a JSON array.

If the value is not a JSON array, the behavior is undefined.

This function guarantees to return a value. If the index is out of bounds, the returned value will be of type CX_JSON_NOTHING, but never NULL.

Parameters

value	the JSON value
index	the index in the array

Returns: the value at the specified index

See also: cxJsonIsArray()

◆ cxJsonArrIter()

CxIterator cxJsonArrIter ( const CxJsonValue * value )

Returns an iterator over the JSON array elements.

The iterator yields values of type CxJsonValue* .

If the value is not a JSON array, the behavior is undefined.

Parameters

value the JSON value

Returns: an iterator over the array elements

See also: cxJsonIsArray()

◆ cxJsonArrRemove()

CxJsonValue * cxJsonArrRemove	(	CxJsonValue *	value,
		size_t	index )

Removes an element from a JSON array.

If the value is not a JSON array, the behavior is undefined.

This function, in contrast to cxJsonArrayGet(), returns NULL when the index is out of bounds.

Parameters

value	the JSON value
index	the index in the array

Returns: the removed value from the specified index or NULL when the index was out of bounds

See also: cxJsonIsArray()

◆ cxJsonArrSize()

static size_t cxJsonArrSize ( const CxJsonValue * value )

inlinestatic

Returns the size of a JSON array.

If the value is not a JSON array, the behavior is undefined.

Parameters

value the JSON value

Returns: the size of the array

See also: cxJsonIsArray()

◆ cxJsonAsBool()

static bool cxJsonAsBool ( const CxJsonValue * value )

inlinestatic

Obtains a Boolean value from the given JSON value.

If the value is not a JSON literal, the behavior is undefined. The null literal is interpreted as false.

Parameters

value the JSON value

Returns: the value represented as double

See also: cxJsonIsLiteral()

◆ cxJsonAsCxMutStr()

cxmutstr cxJsonAsCxMutStr ( const CxJsonValue * value )

Obtains a mutable UCX string from the given JSON value.

If the value is not a string, the behavior is undefined.

Parameters

value the JSON value

Returns: the value represented as mutable UCX string

See also: cxJsonIsString()

◆ cxJsonAsCxString()

cxstring cxJsonAsCxString ( const CxJsonValue * value )

Obtains a UCX string from the given JSON value.

If the value is not a string, the behavior is undefined.

Parameters

value the JSON value

Returns: the value represented as UCX string

See also: cxJsonIsString()

◆ cxJsonAsDouble()

double cxJsonAsDouble ( const CxJsonValue * value )

Obtains a double-precision floating-point value from the given JSON value.

If the value is not a JSON number, the behavior is undefined.

Parameters

value the JSON value

Returns: the value represented as double

See also: cxJsonIsNumber()

◆ cxJsonAsInteger()

int64_t cxJsonAsInteger ( const CxJsonValue * value )

Obtains a 64-bit signed integer from the given JSON value.

If the value is not a JSON number, the behavior is undefined. If it is a JSON number, but not an integer, the value will be converted to an integer, possibly losing precision.

Parameters

value the JSON value

Returns: the value represented as double

See also: cxJsonIsNumber(); cxJsonIsInteger()

◆ cxJsonAsString()

char * cxJsonAsString ( const CxJsonValue * value )

Obtains a C string from the given JSON value.

If the value is not a string, the behavior is undefined.

Parameters

value the JSON value

Returns: the value represented as C string

See also: cxJsonIsString()

◆ cxJsonCreateArr()

CxJsonValue * cxJsonCreateArr ( const CxAllocator * allocator )

Creates a new (empty) JSON array.

Parameters

allocator the allocator to use

Returns: the new JSON array or NULL if allocation fails

See also: cxJsonObjPutArr(); cxJsonArrAddValues()

◆ cxJsonCreateInteger()

CxJsonValue * cxJsonCreateInteger	(	const CxAllocator *	allocator,
		int64_t	num )

Creates a new JSON number value based on an integer.

Parameters

allocator	the allocator to use
num	the numeric value

Returns: the new JSON value or NULL if allocation fails

See also: cxJsonObjPutInteger(); cxJsonArrAddIntegers()

◆ cxJsonCreateLiteral()

CxJsonValue * cxJsonCreateLiteral	(	const CxAllocator *	allocator,
		CxJsonLiteral	lit )

Creates a new JSON literal.

Parameters

allocator	the allocator to use
lit	the type of literal

Returns: the new JSON value or NULL if allocation fails

See also: cxJsonObjPutLiteral(); cxJsonArrAddLiterals()

◆ cxJsonCreateNumber()

CxJsonValue * cxJsonCreateNumber	(	const CxAllocator *	allocator,
		double	num )

Creates a new JSON number value.

Parameters

allocator	the allocator to use
num	the numeric value

Returns: the new JSON value or NULL if allocation fails

See also: cxJsonObjPutNumber(); cxJsonArrAddNumbers()

◆ cxJsonCreateObj()

CxJsonValue * cxJsonCreateObj ( const CxAllocator * allocator )

Creates a new (empty) JSON object.

Parameters

allocator the allocator to use

Returns: the new JSON object or NULL if allocation fails

See also: cxJsonObjPutObj(); cxJsonArrAddValues()

◆ cxJsonDestroy()

void cxJsonDestroy ( CxJson * json )

Destroys the JSON interface.

Parameters

json	the JSON interface

See also: cxJsonInit()

◆ cxJsonFilln()

int cxJsonFilln	(	CxJson *	json,
		const char *	buf,
		size_t	len )

Fills the input buffer.

Remarks: The JSON interface tries to avoid copying the input data. When you use this function and cxJsonNext() interleaving, no copies are performed. However, you must not free the pointer to the data in that case. When you invoke the fill function more than once before calling cxJsonNext(), the additional data is appended - inevitably leading to an allocation of a new buffer and copying the previous contents.

Parameters

json	the JSON interface
buf	the source buffer
len	the length of the source buffer

Return values

zero	success
non-zero	internal allocation error

See also: cxJsonFill()

◆ cxJsonInit()

void cxJsonInit	(	CxJson *	json,
		const CxAllocator *	allocator )

Initializes the JSON interface.

Parameters

json	the JSON interface
allocator	the allocator that shall be used for the produced values

See also: cxJsonDestroy()

◆ cxJsonIsArray()

static bool cxJsonIsArray ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is a JSON array.

Parameters

value a pointer to the value

Return values

true	the value is a JSON array
false	otherwise

◆ cxJsonIsBool()

static bool cxJsonIsBool ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is a Boolean literal.

Parameters

value a pointer to the value

Return values

true	the value is either `true` or `false`
false	otherwise

See also: cxJsonIsTrue(); cxJsonIsFalse()

◆ cxJsonIsFalse()

static bool cxJsonIsFalse ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is false.

Remarks: Be advised that this is different from testing !cxJsonIsTrue(v).

Parameters

value a pointer to the value

Return values

true	the value is `false`
false	otherwise

See also: cxJsonIsBool(); cxJsonIsTrue()

◆ cxJsonIsInteger()

static bool cxJsonIsInteger ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is an integer number.

Parameters

value a pointer to the value

Return values

true	the value is an integer number
false	otherwise

See also: cxJsonIsNumber()

◆ cxJsonIsLiteral()

static bool cxJsonIsLiteral ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is a JSON literal.

JSON literals are true, false, and null.

Parameters

value a pointer to the value

Return values

true	the value is a JSON literal
false	otherwise

See also: cxJsonIsTrue(); cxJsonIsFalse(); cxJsonIsNull()

◆ cxJsonIsNull()

static bool cxJsonIsNull ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is null.

Parameters

value a pointer to the value

Return values

true	the value is `null`
false	otherwise

See also: cxJsonIsLiteral()

◆ cxJsonIsNumber()

static bool cxJsonIsNumber ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is a JSON number.

This function will return true for both floating-point and integer numbers.

Parameters

value a pointer to the value

Return values

true	the value is a JSON number
false	otherwise

See also: cxJsonIsInteger()

◆ cxJsonIsObject()

static bool cxJsonIsObject ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is a JSON object.

Parameters

value a pointer to the value

Return values

true	the value is a JSON object
false	otherwise

◆ cxJsonIsString()

static bool cxJsonIsString ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is a string.

Parameters

value a pointer to the value

Return values

true	the value is a string
false	otherwise

◆ cxJsonIsTrue()

static bool cxJsonIsTrue ( const CxJsonValue * value )

inlinestatic

Checks if the specified value is true.

Remarks: Be advised that this is different from testing !cxJsonIsFalse(v).

Parameters

value a pointer to the value

Return values

true	the value is `true`
false	otherwise

See also: cxJsonIsBool(); cxJsonIsFalse()

◆ cxJsonNext()

CxJsonStatus cxJsonNext	(	CxJson *	json,
		CxJsonValue **	value )

Tries to obtain the next JSON value.

Before this function can be called, the input buffer needs to be filled with cxJsonFill().

When this function returns CX_JSON_INCOMPLETE_DATA, you can add the missing data with another invocation of cxJsonFill() and then repeat the call to cxJsonNext().

Parameters

json	the JSON interface
value	a pointer where the next value shall be stored

Return values

CX_JSON_NO_ERROR	successfully retrieve the `value`
CX_JSON_NO_DATA	there is no (more) data in the buffer to read from
CX_JSON_INCOMPLETE_DATA	an incomplete value was read and more data needs to be filled
CX_JSON_NULL_DATA	the buffer was never initialized
CX_JSON_BUFFER_ALLOC_FAILED	allocating internal buffer space failed
CX_JSON_VALUE_ALLOC_FAILED	allocating memory for a CxJsonValue failed
CX_JSON_FORMAT_ERROR_NUMBER	the JSON text contains an illegally formatted number
CX_JSON_FORMAT_ERROR_UNEXPECTED_TOKEN	JSON syntax error

◆ cxJsonObjIter()

CxIterator cxJsonObjIter ( const CxJsonValue * value )

Returns an iterator over the JSON object members.

The iterator yields values of type CxJsonObjValue* which contain the name and value of the member.

If the value is not a JSON object, the behavior is undefined.

Parameters

value the JSON value

Returns: an iterator over the object members

See also: cxJsonIsObject()

◆ cxJsonObjSize()

static size_t cxJsonObjSize ( const CxJsonValue * value )

inlinestatic

Returns the size of a JSON object.

If the value is not a JSON object, the behavior is undefined.

Parameters

value the JSON value

Returns: the size of the object, i.e., the number of key/value pairs

See also: cxJsonIsObject()

◆ cxJsonReset()

void cxJsonReset ( CxJson * json )

Destroys and re-initializes the JSON interface.

You might want to use this to reset the parser after encountering a syntax error.

Parameters

json	the JSON interface

◆ cxJsonValueFree()

void cxJsonValueFree ( CxJsonValue * value )

Recursively deallocates the memory of a JSON value.

Remarks: The type of each deallocated value will be changed to CX_JSON_NOTHING, and values of such a type will be skipped by the deallocation. That means this function protects you from double-frees when you are accidentally freeing a nested value and then the parent value (or vice versa).

Parameters

value the value

◆ cxJsonWrite()

int cxJsonWrite	(	void *	target,
		const CxJsonValue *	value,
		cx_write_func	wfunc,
		const CxJsonWriter *	settings )

Writes a JSON value to a buffer or stream.

This function blocks until either all data is written, or an error occurs. The write operation is not atomic in the sense that it might happen that the data is only partially written when an error occurs with no way to indicate how much data was written. To avoid this problem, you can use a CxBuffer as target which is unlikely to fail a write operation. You can, for example, use the buffer's flush feature to relay the data.

Parameters

target	the buffer or stream where to write to
value	the value that shall be written
wfunc	the write function to use
settings	formatting settings (or `NULL` to use a compact default)

Return values

zero	success
non-zero	when no or not all data could be written

◆ cxJsonWriterCompact()

CxJsonWriter cxJsonWriterCompact ( void )

Creates a default writer configuration for compact output.

Returns: new JSON writer settings

◆ cxJsonWriterPretty()

CxJsonWriter cxJsonWriterPretty ( bool use_spaces )

Creates a default writer configuration for pretty output.

Parameters

use_spaces false if you want tabs, true if you want four spaces instead

Returns: new JSON writer settings

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ cxJsonCreateString

◆ cxJsonFill

◆ cxJsonObjGet

◆ cxJsonObjPut

◆ cxJsonObjPutArr

◆ cxJsonObjPutInteger

◆ cxJsonObjPutLiteral

◆ cxJsonObjPutNumber

◆ cxJsonObjPutObj

◆ cxJsonObjPutString

◆ cxJsonObjRemove

Enumeration Type Documentation

◆ cx_json_literal

◆ cx_json_status

◆ cx_json_token_type

◆ cx_json_value_type

Function Documentation

◆ cx_json_create_string()

◆ cx_json_fill()

◆ cx_json_obj_get()

◆ cx_json_obj_put()

◆ cx_json_obj_put_arr()

◆ cx_json_obj_put_integer()

◆ cx_json_obj_put_literal()

◆ cx_json_obj_put_number()

◆ cx_json_obj_put_obj()

◆ cx_json_obj_put_string()

◆ cx_json_obj_remove()

◆ cxJsonArrAddCxStrings()

◆ cxJsonArrAddIntegers()

◆ cxJsonArrAddLiterals()

◆ cxJsonArrAddNumbers()

◆ cxJsonArrAddStrings()

◆ cxJsonArrAddValues()

◆ cxJsonArrGet()

◆ cxJsonArrIter()

◆ cxJsonArrRemove()

◆ cxJsonArrSize()

◆ cxJsonAsBool()

◆ cxJsonAsCxMutStr()

◆ cxJsonAsCxString()

◆ cxJsonAsDouble()

◆ cxJsonAsInteger()

◆ cxJsonAsString()

◆ cxJsonCreateArr()

◆ cxJsonCreateInteger()

◆ cxJsonCreateLiteral()

◆ cxJsonCreateNumber()

◆ cxJsonCreateObj()

◆ cxJsonDestroy()

◆ cxJsonFilln()

◆ cxJsonInit()

◆ cxJsonIsArray()

◆ cxJsonIsBool()

◆ cxJsonIsFalse()

◆ cxJsonIsInteger()

◆ cxJsonIsLiteral()

◆ cxJsonIsNull()

◆ cxJsonIsNumber()

◆ cxJsonIsObject()

◆ cxJsonIsString()

◆ cxJsonIsTrue()

◆ cxJsonNext()

◆ cxJsonObjIter()

◆ cxJsonObjSize()

◆ cxJsonReset()

◆ cxJsonValueFree()

◆ cxJsonWrite()

◆ cxJsonWriterCompact()

◆ cxJsonWriterPretty()