Lite³
A JSON-Compatible Zero-Copy Serialization Format
Loading...
Searching...
No Matches
Functions
JSON Conversion
Context API

Conversion between Lite³ and JSON. More...

Functions

static int lite3_ctx_json_dec (lite3_ctx *ctx, const char *__restrict json_str, size_t json_len)
 Convert JSON string to Lite³
 
static int lite3_ctx_json_dec_file (lite3_ctx *ctx, const char *__restrict path)
 Convert JSON from file path to Lite³
 
static int lite3_ctx_json_dec_fp (lite3_ctx *ctx, FILE *fp)
 Convert JSON from file pointer to Lite³
 
static int lite3_ctx_json_print (lite3_ctx *ctx, size_t ofs)
 Print Lite³ buffer as JSON to stdout
 
static char * lite3_ctx_json_enc (lite3_ctx *ctx, size_t ofs, size_t *__restrict out_len)
 Convert Lite³ to JSON string.
 
static char * lite3_ctx_json_enc_pretty (lite3_ctx *ctx, size_t ofs, size_t *__restrict out_len)
 Convert Lite³ to JSON prettified string.
 
static int64_t lite3_ctx_json_enc_buf (lite3_ctx *ctx, size_t ofs, char *__restrict json_buf, size_t json_bufsz)
 Convert Lite³ to JSON and write to output buffer.
 
static int64_t lite3_ctx_json_enc_pretty_buf (lite3_ctx *ctx, 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.

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_ctx_json_dec()

static int lite3_ctx_json_dec ( lite3_ctx *  ctx,
const char *__restrict  json_str,
size_t  json_len 
)
inlinestatic

Convert JSON string to Lite³

Returns
0 on success
< 0 on error
Note
This function performs internal memory allocation using malloc().
Parameters
[in]ctxcontext pointer
[in]json_strJSON input string (string)
[in]json_lenJSON input string length (bytes, including or excluding NULL-terminator)

Definition at line 2137 of file lite3_context_api.h.

◆ lite3_ctx_json_dec_file()

static int lite3_ctx_json_dec_file ( lite3_ctx *  ctx,
const char *__restrict  path 
)
inlinestatic

Convert JSON from file path to Lite³

Returns
0 on success
< 0 on error
Note
This function performs internal memory allocation using malloc().
Parameters
[in]ctxcontext pointer
[in]pathJSON file path (string)

Definition at line 2163 of file lite3_context_api.h.

◆ lite3_ctx_json_dec_fp()

static int lite3_ctx_json_dec_fp ( lite3_ctx *  ctx,
FILE *  fp 
)
inlinestatic

Convert JSON from file pointer to Lite³

Returns
0 on success
< 0 on error
Note
This function performs internal memory allocation using malloc().
Parameters
[in]ctxcontext pointer
[in]fpJSON file pointer

Definition at line 2188 of file lite3_context_api.h.

◆ lite3_ctx_json_enc()

static char * lite3_ctx_json_enc ( lite3_ctx *  ctx,
size_t  ofs,
size_t *__restrict  out_len 
)
inlinestatic

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]ctxcontext pointer
[in]ofsstart offset (0 == root)
[out]out_lenstring length excluding NULL-terminator (if not needed, pass NULL)

Definition at line 2237 of file lite3_context_api.h.

◆ lite3_ctx_json_enc_buf()

static int64_t lite3_ctx_json_enc_buf ( lite3_ctx *  ctx,
size_t  ofs,
char *__restrict  json_buf,
size_t  json_bufsz 
)
inlinestatic

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]ctxcontext pointer
[in]ofsstart offset (0 == root)
[in]json_bufJSON output buffer
[in]json_bufszJSON output buffer max size (bytes)

Definition at line 2278 of file lite3_context_api.h.

◆ lite3_ctx_json_enc_pretty()

static char * lite3_ctx_json_enc_pretty ( lite3_ctx *  ctx,
size_t  ofs,
size_t *__restrict  out_len 
)
inlinestatic

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]ctxcontext pointer
[in]ofsstart offset (0 == root)
[out]out_lenstring length excluding NULL-terminator (if not needed, pass NULL)

Definition at line 2260 of file lite3_context_api.h.

◆ lite3_ctx_json_enc_pretty_buf()

static int64_t lite3_ctx_json_enc_pretty_buf ( lite3_ctx *  ctx,
size_t  ofs,
char *__restrict  json_buf,
size_t  json_bufsz 
)
inlinestatic

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]ctxcontext pointer
[in]ofsstart offset (0 == root)
[in]json_bufJSON output buffer
[in]json_bufszJSON output buffer max size (bytes)

Definition at line 2300 of file lite3_context_api.h.

◆ lite3_ctx_json_print()

static int lite3_ctx_json_print ( lite3_ctx *  ctx,
size_t  ofs 
)
inlinestatic

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]ctxcontext pointer
[in]ofsstart offset (0 == root)

Definition at line 2217 of file lite3_context_api.h.