JSON routines.

Overview

These functions provide an easy but robust way to convert native data to JSON format. More…

// typedefs

typedef enum te_json_compound te_json_compound;
typedef struct te_json_level_t te_json_level_t;
typedef enum te_json_out_t te_json_out_t;
typedef union te_json_out_loc_t te_json_out_loc_t;
typedef struct te_json_ctx_t te_json_ctx_t;

// enums

enum te_json_compound;
enum te_json_out_t;

// structs

struct te_json_ctx_t;
struct te_json_level_t;

// unions

union te_json_out_loc_t;

// global functions

void te_json_add_simple(te_json_ctx_t* ctx, const char* fmt, ...);
static void static void te_json_add_null(te_json_ctx_t* ctx);
static void te_json_add_bool(te_json_ctx_t* ctx, bool val);
static void te_json_add_integer(te_json_ctx_t* ctx, intmax_t val);
static void te_json_add_float(te_json_ctx_t* ctx, double val, int precision);
void te_json_add_string(te_json_ctx_t* ctx, const char* fmt, ...);
void void te_json_start_string(te_json_ctx_t* ctx);
void te_json_append_string(te_json_ctx_t* ctx, const char* fmt, ...);
void void te_json_append_string_va(te_json_ctx_t* ctx, const char* fmt, va_list args);
void te_json_start_raw(te_json_ctx_t* ctx);
void te_json_append_raw(te_json_ctx_t* ctx, const char* value, size_t len);
void te_json_start_array(te_json_ctx_t* ctx);
void te_json_start_object(te_json_ctx_t* ctx);
void te_json_end(te_json_ctx_t* ctx);
void te_json_add_key(te_json_ctx_t* ctx, const char* key);
static void te_json_add_key_str(te_json_ctx_t* ctx, const char* key, const char* val);
static void te_json_add_key_enum(te_json_ctx_t* ctx, const te_enum_map* map, const char* key, int val);
void te_json_add_array_str(te_json_ctx_t* ctx, bool skip_null, size_t n_strs, const char* strs[n_strs]);
void te_json_add_kvpair(te_json_ctx_t* ctx, const te_kvpair_h* head);

Detailed Documentation

These functions provide an easy but robust way to convert native data to JSON format.

Note, however, that it is not a full-fledged JSON serializer, so it is still possible to generate invalid JSON if the API is used carelessly.

Since they are intended to be used with C data of known layout, they do not report errors: if anything goes wrong, it’s considered API contract violation and an assertion fires.

Typedefs

typedef enum te_json_compound te_json_compound

The kind of JSON compound.

typedef struct te_json_level_t te_json_level_t

One level of JSON value nesting

typedef enum te_json_out_t te_json_out_t

JSON output type.

typedef union te_json_out_loc_t te_json_out_loc_t

Output location for generated JSON.

typedef struct te_json_ctx_t te_json_ctx_t

The context for JSON serialization.

While the structure is declared public to make on-stack variables possible, it shall be treated as an opaque and only initialized with TE_JSON_INIT_STR() and then passed to the API from this group.

Global Functions

void te_json_add_simple(te_json_ctx_t* ctx, const char* fmt, ...)

Serialize a simple JSON value formatted according to fmt.

This function does no escaping, so is not intended for general usage. Normally one should use one of type-specific functions.

Parameters:

ctx	JSON context
fmt	format string
…	arguments

static void static void te_json_add_null(te_json_ctx_t* ctx)

Serialize JSON null.

Parameters:

ctx	JSON context

static void te_json_add_bool(te_json_ctx_t* ctx, bool val)

Serialize a JSON boolean.

Parameters:

ctx	JSON context
val	boolean value

static void te_json_add_integer(te_json_ctx_t* ctx, intmax_t val)

Serialize a JSON integer value.

Parameters:

ctx	JSON context
val	integral value

static void te_json_add_float(te_json_ctx_t* ctx, double val, int precision)

Serialize a JSON floating value.

If val is not finite (infinity or NaN), null is serialized.

Parameters:

ctx	JSON context
val	Value
precision	Floating-point precision (unlimited if negative)

void te_json_add_string(te_json_ctx_t* ctx, const char* fmt, ...)

Serialize a string value escaping it if necessary.

Namely, double quotes, backslashes and control characters are properly escaped. No special provision is made for Unicode non-ASCII characters, though. Embedded zeroes are not supported.

Double quotes are added around the value.

Parameters:

ctx	JSON context
fmt	format string
…	arguments

void void te_json_start_string(te_json_ctx_t* ctx)

Start serializing a JSON string.

te_json_append_string() should be used to append bytes to the serialized string. At the end, te_json_end() must be called to finalize JSON string. Double quotes around the composed string value are added automatically. Unlike te_json_add_string(), this allows to construct string value incrementally instead of specifying it all at once.

Parameters:

ctx	JSON context

void te_json_append_string(te_json_ctx_t* ctx, const char* fmt, ...)

Append formatted string to a string value which was started with te_json_start_string(). The same escaping is done as with te_json_add_string().

Parameters:

ctx	JSON context
fmt	format string
…	arguments

See also:

te_json_append_string_va()

void void te_json_append_string_va(te_json_ctx_t* ctx, const char* fmt, va_list args)

Same as te_json_append_string() but accepts va_list instead of a list of arguments.

Parameters:

ctx	JSON context
fmt	format string
args	arguments

void te_json_start_raw(te_json_ctx_t* ctx)

Start “raw” JSON value. te_json_end() should be called once the value is finished. te_json_append_raw() should be used to construct the value.

This function can be used when there is a string containing JSON object which should simply be attached to constructed JSON tree without any editing.

Parameters:

ctx	JSON context

void te_json_append_raw(te_json_ctx_t* ctx, const char* value, size_t len)

Append preformatted JSON string.

Parameters:

ctx	JSON context
value	String to append
len	Length of the string (if zero, the string must include the terminating null byte)

void te_json_start_array(te_json_ctx_t* ctx)

Start serializing a JSON array.

te_json_end() shall be called after all items are serialized.

Parameters:

ctx	JSON context

void te_json_start_object(te_json_ctx_t* ctx)

Start serializing a JSON object.

te_json_end() shall be called after all items are serialized.

Parameters:

ctx	JSON context

void te_json_end(te_json_ctx_t* ctx)

Finalize the current JSON value nesting.

This function must be called after te_json_start_object() or te_json_start_array(). It may be called at the toplevel and has no effect in this case.

Parameters:

ctx	JSON context

void te_json_add_key(te_json_ctx_t* ctx, const char* key)

Mark the beginning of a new key in an object.

Parameters:

ctx	JSON context
key	key (it is assumed that it does not need escaping); `NULL` value is treated as an empty string

static void te_json_add_key_str(te_json_ctx_t* ctx, const char* key, const char* val)

Output a new key of an object with a given string value.

If val is NULL, nothing is added, not a null value.

Parameters:

ctx	JSON context
key	key
val	string value

static void te_json_add_key_enum(te_json_ctx_t* ctx, const te_enum_map* map, const char* key, int val)

Output a new key with an enumeration-like value.

The string representation of a value is produced by applying map to val. If val is not found in map or if it maps to NULL explicitly, the key is omitted.

Parameters:

ctx	JSON context
map	enum-to-string mapping
key	key
val	enum value

void te_json_add_array_str(te_json_ctx_t* ctx, bool skip_null, size_t n_strs, const char* strs[n_strs])

Serialize an array of strings.

If skip_null is true, NULL values in strs will be skipped, otherwise serialized as JSON null.

Parameters:

ctx	JSON context
skip_null	null handling mode
n_strs	number of elements in `strs`
strs	array of strings

void te_json_add_kvpair(te_json_ctx_t* ctx, const te_kvpair_h* head)

Serialize a list of kv_pairs as a JSON object.

Parameters:

ctx	JSON context
head	Key-value list