JSON Conversion

Conversion between Lite³ and JSON. More...

Functions
int	lite3_json_dec (unsigned char *buf, size_t *__restrict out_buflen, size_t bufsz, const char *__restrict json_str, size_t json_len)
	Convert JSON string to Lite³
int	lite3_json_dec_file (unsigned char *buf, size_t *__restrict out_buflen, size_t bufsz, const char *__restrict path)
	Convert JSON from file path to Lite³
int	lite3_json_dec_fp (unsigned char *buf, size_t *__restrict out_buflen, size_t bufsz, FILE *fp)
	Convert JSON from file pointer to Lite³
int	lite3_json_print (const unsigned char *buf, size_t buflen, size_t ofs)
	Print Lite³ buffer as JSON to stdout
char *	lite3_json_enc (const unsigned char *buf, size_t buflen, size_t ofs, size_t *__restrict out_len)
	Convert Lite³ to JSON string.
char *	lite3_json_enc_pretty (const unsigned char *buf, size_t buflen, size_t ofs, size_t *__restrict out_len)
	Convert Lite³ to JSON prettified string.
int64_t	lite3_json_enc_buf (const unsigned char *buf, size_t buflen, size_t ofs, char *__restrict json_buf, size_t json_bufsz)
	Convert Lite³ to JSON and write to output buffer.
int64_t	lite3_json_enc_pretty_buf (const unsigned char *buf, size_t buflen, size_t ofs, char *__restrict json_buf, size_t json_bufsz)
	Convert Lite³ to prettified JSON and write to output buffer.

Detailed Description

Conversion between Lite³ and JSON.

All JSON functionality is enabled internally by the yyjson library.

JSON encode functions read buflen to know the currently used portion of the buffer.

The ofs (offset) field is used to target an object or array inside the Lite³ buffer. To target the root-level object/array, use ofs == 0.

Number reading

Lite³ implements an integer and floating point type, while JSON only implements a single 'number' type. Some rules apply to JSON number reading:

• Numbers without a decimal point are read as int64_t.
• Numbers with a decimal point are read as double with correct rounding.
• If a number is too large for int64_t, it is converted to double.
• If a double number overflows (reaches infinity), an error is returned.
• If a number does not conform to the JSON standard, an error is returned.

See: enum lite3_type

Note

This feature requires subdependencies enabled via build flags. See the Makefile for more details. Also LITE3_JSON must be defined inside the lite3.h header or using compiler -D flags. See Library Configuration Options.

Warning

Read-only operations are thread-safe. This includes all JSON encode funtions. Decoding JSON however is not thread-safe for the given Lite³ buffer and requires manual locking. Mixing reads and writes on the same Lite³ buffer is also not thread-safe.

Function Documentation

lite3_json_dec()

int lite3_json_dec	(	unsigned char *	buf,
		size_t *__restrict	out_buflen,
		size_t	bufsz,
		const char *__restrict	json_str,
		size_t	json_len
	)

Convert JSON string to Lite³

The number of bytes written to *buf never exceeds bufsz.

Returns

0 on success

< 0 on error

Note

This function performs internal memory allocation using malloc().

Parameters

[in]	buf	Lite³ buffer pointer
[out]	out_buflen	buffer used length (bytes, out value)
[in]	bufsz	buffer max size (bytes)
[in]	json_str	JSON input string (string)
[in]	json_len	JSON input string length (bytes, including or excluding NULL-terminator)

lite3_json_dec_file()

int lite3_json_dec_file	(	unsigned char *	buf,
		size_t *__restrict	out_buflen,
		size_t	bufsz,
		const char *__restrict	path
	)

Convert JSON from file path to Lite³

The number of bytes written to *buf never exceeds bufsz.

Returns

0 on success

< 0 on error

Note

This function performs internal memory allocation using malloc().

Parameters

[in]	buf	Lite³ buffer pointer
[out]	out_buflen	buffer used length (bytes, out value)
[in]	bufsz	buffer max size (bytes)
[in]	path	JSON file path (string)

lite3_json_dec_fp()

int lite3_json_dec_fp	(	unsigned char *	buf,
		size_t *__restrict	out_buflen,
		size_t	bufsz,
		FILE *	fp
	)

Convert JSON from file pointer to Lite³

The number of bytes written to *buf never exceeds bufsz.

Returns

0 on success

< 0 on error

Note

This function performs internal memory allocation using malloc().

Parameters

[in]	buf	Lite³ buffer pointer
[out]	out_buflen	buffer used length (bytes, out value)
[in]	bufsz	buffer max size (bytes)
[in]	fp	JSON file pointer

lite3_json_enc()

char * lite3_json_enc	(	const unsigned char *	buf,
		size_t	buflen,
		size_t	ofs,
		size_t *__restrict	out_len
	)

Convert Lite³ to JSON string.

Returns

char * pointer to the JSON string on success

NULL on error

Note

1. This function performs internal memory allocation using malloc().
2. Because JSON does not support encoding of raw bytes, LITE3_TYPE_BYTES are automatically converted to a base64 string.

Warning

You must manually call free() on the pointer returned by this function.

Parameters

[in]	buf	Lite³ buffer
[in]	buflen	buffer used length (bytes)
[in]	ofs	start offset (0 == root)
[out]	out_len	string length excluding NULL-terminator (if not needed, pass NULL)

lite3_json_enc_buf()

int64_t lite3_json_enc_buf	(	const unsigned char *	buf,
		size_t	buflen,
		size_t	ofs,
		char *__restrict	json_buf,
		size_t	json_bufsz
	)

Convert Lite³ to JSON and write to output buffer.

Returns

>= 0 on success (number of bytes written)

< 0 on error

Note

1. This function performs internal memory allocation using malloc().
2. Because JSON does not support encoding of raw bytes, LITE3_TYPE_BYTES are automatically converted to a base64 string.

Parameters

[in]	buf	Lite³ buffer
[in]	buflen	Lite³ buffer used length (bytes)
[in]	ofs	start offset (0 == root)
[in]	json_buf	JSON output buffer
[in]	json_bufsz	JSON output buffer max size (bytes)

lite3_json_enc_pretty()

char * lite3_json_enc_pretty	(	const unsigned char *	buf,
		size_t	buflen,
		size_t	ofs,
		size_t *__restrict	out_len
	)

Convert Lite³ to JSON prettified string.

The prettified string uses a tab space indent of 4.

Returns

char * pointer to the JSON string on success

NULL on error

Note

1. This function performs internal memory allocation using malloc().
2. Because JSON does not support encoding of raw bytes, LITE3_TYPE_BYTES are automatically converted to a base64 string.

Warning

You must manually call free() on the pointer returned by this function.

Parameters

[in]	buf	Lite³ buffer
[in]	buflen	Lite³ buffer used length (bytes)
[in]	ofs	start offset (0 == root)
[out]	out_len	string length excluding NULL-terminator (if not needed, pass NULL)

lite3_json_enc_pretty_buf()

int64_t lite3_json_enc_pretty_buf	(	const unsigned char *	buf,
		size_t	buflen,
		size_t	ofs,
		char *__restrict	json_buf,
		size_t	json_bufsz
	)

Convert Lite³ to prettified JSON and write to output buffer.

The prettified string uses a tab space indent of 4.

Returns

>= 0 on success (number of bytes written)

< 0 on error

Note

1. This function performs internal memory allocation using malloc().
2. Because JSON does not support encoding of raw bytes, LITE3_TYPE_BYTES are automatically converted to a base64 string.

Parameters

[in]	buf	Lite³ buffer
[in]	buflen	Lite³ buffer used length (bytes)
[in]	ofs	start offset (0 == root)
[in]	json_buf	JSON output buffer
[in]	json_bufsz	JSON output buffer max size (bytes)

lite3_json_print()

int lite3_json_print	(	const unsigned char *	buf,
		size_t	buflen,
		size_t	ofs
	)

Print Lite³ buffer as JSON to stdout

Returns

0 on success

< 0 on error

Very useful to make Lite³ structures human-readable inside a terminal. The ofs parameter can be used to selectively print an internal object or array. To print out the entire structure, call from the root using ofs == 0.

Note

1. This function performs internal memory allocation using malloc().
2. Because JSON does not support encoding of raw bytes, LITE3_TYPE_BYTES are automatically converted to a base64 string.

Parameters

[in]	buf	Lite³ buffer
[in]	buflen	buffer used length (bytes)
[in]	ofs	start offset (0 == root)