yyjson 0.5.0 A high performance C JSON library.

API

# API Design

## API prefix

All public functions and structs are prefixed with `yyjson_`, and all constants are prefixed with `YYJSON_`.

## API for immutable/mutable data

yyjson have 2 types of data structures: immutable and mutable:

type | immutable | mutable
--- | --- | ---
JSON value | yyjson_val | yyjson_mut_val
JSON document | yyjson_doc | yyjson_mut_doc

When reading a JSON, yyjson returns immutable document and values;
When building a JSON, yyjson creates mutable document and values;
The document holds memory for all its JSON values and strings.

For most immutable APIs, you can just add a `mut` after `yyjson_` to get the mutable version, for example:

char *yyjson_write(yyjson_doc *doc, ...);
char *yyjson_mut_write(yyjson_mut_doc *doc, ...);
bool yyjson_is_str(yyjson_val *val);
bool yyjson_mut_is_str(yyjson_mut_val *val);
yyjson_is_str
yyjson_api_inline bool yyjson_is_str(yyjson_val *val)
Definition: yyjson.h:3511
yyjson_mut_write
yyjson_api_inline char * yyjson_mut_write(const yyjson_mut_doc *doc, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1033
yyjson_write
yyjson_api_inline char * yyjson_write(const yyjson_doc *doc, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:953
yyjson_mut_is_str
yyjson_api_inline bool yyjson_mut_is_str(yyjson_mut_val *val)
Definition: yyjson.h:3985
yyjson_doc
Definition: yyjson.h:3274
yyjson_mut_doc
Definition: yyjson.h:3873
yyjson_mut_val
Definition: yyjson.h:3829
yyjson_val
Definition: yyjson.h:3269

yyjson also provides some functions to convert immutable into mutable:

yyjson_mut_doc *yyjson_doc_mut_copy(yyjson_doc *doc, yyjson_alc *alc);
yyjson_mut_val *yyjson_val_mut_copy(yyjson_mut_doc *doc, yyjson_val *val);
yyjson_alc
Definition: yyjson.h:474
yyjson_val_mut_copy
yyjson_api yyjson_mut_val * yyjson_val_mut_copy(yyjson_mut_doc *doc, yyjson_val *val)
yyjson_doc_mut_copy
yyjson_api yyjson_mut_doc * yyjson_doc_mut_copy(yyjson_doc *doc, const yyjson_alc *alc)

## API for string

yyjson supports strings with or without null-terminator.
When you need to use a non null-terminated string, or you know the length of the string explicitly, you can use a function that ends with `n`, for example:

// null-terminated is required
bool yyjson_equals_str(yyjson_val *val, const char *str);
// null-terminator is not required
bool yyjson_equals_strn(yyjson_val *val, const char *str, size_t len);
yyjson_equals_str
yyjson_api_inline bool yyjson_equals_str(yyjson_val *val, const char *str)
Definition: yyjson.h:3593
yyjson_equals_strn
yyjson_api_inline bool yyjson_equals_strn(yyjson_val *val, const char *str, size_t len)
Definition: yyjson.h:3600

When creating JSON, yyjson treats strings as constants for better performance. When your string will be modified, you should use a function with a `cpy` to copy the string to the document, for example:

// reference only, null-terminated is required
yyjson_mut_val *yyjson_mut_str(yyjson_mut_doc *doc, const char *str);
// reference only, null-terminator is not required
yyjson_mut_val *yyjson_mut_strn(yyjson_mut_doc *doc, const char *str, size_t len);
// copied, null-terminated is required
yyjson_mut_val *yyjson_mut_strcpy(yyjson_mut_doc *doc, const char *str);
// copied, null-terminator is not required
yyjson_mut_val *yyjson_mut_strncpy(yyjson_mut_doc *doc, const char *str, size_t len);
yyjson_mut_strn
yyjson_api_inline yyjson_mut_val * yyjson_mut_strn(yyjson_mut_doc *doc, const char *str, size_t len)
Definition: yyjson.h:4216
yyjson_mut_strncpy
yyjson_api_inline yyjson_mut_val * yyjson_mut_strncpy(yyjson_mut_doc *doc, const char *str, size_t len)
Definition: yyjson.h:4236
yyjson_mut_strcpy
yyjson_api_inline yyjson_mut_val * yyjson_mut_strcpy(yyjson_mut_doc *doc, const char *str)
Definition: yyjson.h:4230
yyjson_mut_str
yyjson_api_inline yyjson_mut_val * yyjson_mut_str(yyjson_mut_doc *doc, const char *str)
Definition: yyjson.h:4210

# Read JSON

yyjson provides 3 methods for reading JSON,
each method accepts an input of UTF-8 data or file,
returns a document if succeeds, or returns NULL if fails.

## Read JSON from string

The `dat` should be a UTF-8 string, null-terminator is not required.
The `len` is the byte length of `dat`.
The `flg` is reader flag, pass 0 if you don't need it, see `reader flag` for details.
If input is invalid, `NULL` is returned.

yyjson_doc *yyjson_read(const char *dat,
size_t len,
yyjson_read_flag flg);
yyjson_read_flag
uint32_t yyjson_read_flag
Definition: yyjson.h:561
yyjson_read
yyjson_api_inline yyjson_doc * yyjson_read(const char *dat, size_t len, yyjson_read_flag flg)
Definition: yyjson.h:738

Sample code:

const char *str = "[1,2,3,4]";
yyjson_doc *doc = yyjson_read(str, strlen(str), 0);
if (doc) {...}
yyjson_doc_free(doc);
yyjson_doc_free
yyjson_api_inline void yyjson_doc_free(yyjson_doc *doc)
Definition: yyjson.h:3457

## Read JSON from file

The `path` is JSON file path.
The `flg` is reader flag, pass 0 if you don't need it, see `reader flag` for details.
The `alc` is memory allocator, pass NULL if you don't need it, see `memory allocator` for details.
The `err` is a pointer to receive error message, pass NULL if you don't need it.
If input is invalid, `NULL` is returned.

yyjson_doc *yyjson_read_file(const char *path,
yyjson_read_flag flg,
yyjson_alc *alc,
yyjson_read_err *err);
yyjson_read_file
yyjson_api yyjson_doc * yyjson_read_file(const char *path, yyjson_read_flag flg, const yyjson_alc *alc, yyjson_read_err *err)
yyjson_read_err
Definition: yyjson.h:659

Sample code:

yyjson_doc *doc = yyjson_read_file("/tmp/test.json", 0, NULL, NULL);
if (doc) {...}
yyjson_doc_free(doc);

## Read JSON with options

The `dat` should be a UTF-8 string, you can pass a const string if you don't use `YYJSON_READ_INSITU` flag.
The `len` is the `dat`'s length in bytes.
The `flg` is reader flag, pass 0 if you don't need it, see `reader flag` for details.
The `alc` is memory allocator, pass NULL if you don't need it, see `memory allocator` for details.
The `err` is a pointer to receive error message, pass NULL if you don't need it.

yyjson_doc *yyjson_read_opts(char *dat,
size_t len,
yyjson_read_flag flg,
yyjson_alc *alc,
yyjson_read_err *err);
yyjson_read_opts
yyjson_api yyjson_doc * yyjson_read_opts(char *dat, size_t len, yyjson_read_flag flg, const yyjson_alc *alc, yyjson_read_err *err)

Sample code:

const char *dat = your_file.bytes;
size_t len = your_file.size;
yyjson_read_flag flg = YYJSON_READ_ALLOW_COMMENTS | YYJSON_READ_ALLOW_INF_AND_NAN;
yyjson_err err;
yyjson_doc *doc = yyjson_read_opts(dat, len, flg, NULL, &err);
if (doc) {...}
else printf("read error: %s code: %u at position: %ld\n", err.msg, err.code, err.pos);
yyjson_doc_free(doc);
YYJSON_READ_ALLOW_INF_AND_NAN
static const yyjson_read_flag YYJSON_READ_ALLOW_INF_AND_NAN
Definition: yyjson.h:595
YYJSON_READ_ALLOW_COMMENTS
static const yyjson_read_flag YYJSON_READ_ALLOW_COMMENTS
Definition: yyjson.h:591

## Reader flag

yyjson provides a set of flags for JSON reader.
You can use a single flag, or combine multiple flags with bitwise `|` operator.

● YYJSON_READ_NOFLAG

This is the default flag for JSON reader (RFC-8259 or ECMA-404 compliant):

- Read positive integer as `uint64_t`.
- Read negative integer as `int64_t`.
- Read floating-point number as `double` with correct rounding.
- Read integer which cannot fit in `uint64_t` or `int64_t` as `double`.
- Report error if real number is infinity.
- Report error if string contains invalid UTF-8 character or BOM.
- Report error on trailing commas, comments, `inf` and `nan` literals.

● YYJSON_READ_INSITU
Read the input data in-situ.
This option allows the reader to modify and use input data to store string values, which can increase reading speed slightly. The caller should hold the input data before free the document. The input data must be padded by at least `YYJSON_PADDING_SIZE` byte. For example: "[1,2]" should be "[1,2]\0\0\0\0", length should be 5.

Sample code:

size_t dat_len = ...;
char *buf = malloc(dat_len + 4); // create a buffer larger than (len + 4)
read_from_socket(buf, ...);
memset(buf + file_size, 0, 4); // set 4-byte padding after data
yyjson_doc *doc = yyjson_read_opts(buf, dat_len, YYJSON_READ_INSITU, NULL, NULL);
if (doc) {...}
yyjson_doc_free(doc);
free(buf); // the input dat should free after document.
YYJSON_READ_INSITU
static const yyjson_read_flag YYJSON_READ_INSITU
Definition: yyjson.h:579

● YYJSON_READ_STOP_WHEN_DONE
Stop when done instead of issues an error if there's additional content after a JSON document.
This option may used to parse small pieces of JSON in larger data, such as NDJSON.

Sample code:

// single file with multiple json, such as:
// [1,2,3] [4,5,6] {"a":"b"}
size_t file_size = ...;
char *dat = malloc(file_size + 4);
your_read_file(dat, file);
memset(dat + file_size, 0, 4); // add padding
char *hdr = dat;
char *end = dat + file_size;
yyjson_read_flag flg = YYJSON_READ_INSITU | YYJSON_READ_STOP_WHEN_DONE;
while (true) {
yyjson_doc *doc = yyjson_read_opts(hdr, end - hdr, flg, NULL, NULL);
if (!doc) break;
your_doc_process(doc);
hdr += yyjson_doc_get_read_size(doc); // move to next position
yyjson_doc_free(doc);
}
free(dat);
yyjson_doc_get_read_size
yyjson_api_inline size_t yyjson_doc_get_read_size(yyjson_doc *doc)
Definition: yyjson.h:3449
YYJSON_READ_STOP_WHEN_DONE
static const yyjson_read_flag YYJSON_READ_STOP_WHEN_DONE
Definition: yyjson.h:584

● YYJSON_READ_ALLOW_TRAILING_COMMAS
Allow single trailing comma at the end of an object or array, for example:

{
"a": 1,
"b": 2,
}
[
"a",
"b",
]

● YYJSON_READ_ALLOW_COMMENTS
Allow C-style single line and multiple line comments, for example:

{
"name": "Harry", // single line comment
"id": /* multiple line comment */ 123
}

● YYJSON_READ_ALLOW_INF_AND_NAN
Allow nan/inf number or literal (case-insensitive), such as 1e999, NaN, Inf, -Infinity, for example:

{
"large": 123e999,
"nan1": NaN,
"nan2": nan,
"inf1:" Inf,
"inf2": -Infinity
}

● YYJSON_READ_NUMBER_AS_RAW
Read numbers as raw strings without parsing, allowing you to keep arbitrarily large numbers.

You can use these functions to extract raw strings:

bool yyjson_is_raw(yyjson_val *val);
const char *yyjson_get_raw(yyjson_val *val);
size_t yyjson_get_len(yyjson_val *val)

● YYJSON_READ_ALLOW_INVALID_UNICODE
Allow reading invalid unicode when parsing string values (non-standard), for example:

"\x80xyz"
"\xF0\x81\x81\x81"

Invalid characters will be allowed to appear in the string values, but invalid escape sequences will still be reported as errors. This flag does not affect the performance of correctly encoded strings.

Warning: strings in JSON values may contain incorrect encoding when this option is used, you need to handle these strings carefully to avoid security risks.

# Write JSON

yyjson provides 3 methods for writing JSON,
each method accepts an input of JSON document or root value, returns a UTF-8 string or file.

## Write JSON to string

The `doc/val` is JSON document or root value, if you pass NULL, you will get NULL result.
The `flg` is writer flag, pass 0 if you don't need it, see `writer flag` for details.
The `len` is a pointer to receive output length, pass NULL if you don't need it.
This function returns a new JSON string, or NULL if error occurs.
The string is encoded as UTF-8 with a null-terminator.
You should use free() or alc->free() to release it when it's no longer needed.

char *yyjson_write(const yyjson_doc *doc, yyjson_write_flag flg, size_t *len);
char *yyjson_mut_write(const yyjson_mut_doc *doc, yyjson_write_flag flg, size_t *len);
char *yyjson_val_write(const yyjson_val *val, yyjson_write_flag flg, size_t *len);
char *yyjson_mut_val_write(const yyjson_mut_val *val, yyjson_write_flag flg, size_t *len);
yyjson_val_write
yyjson_api_inline char * yyjson_val_write(const yyjson_val *val, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1114
yyjson_mut_val_write
yyjson_api_inline char * yyjson_mut_val_write(const yyjson_mut_val *val, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1192
yyjson_write_flag
uint32_t yyjson_write_flag
Definition: yyjson.h:809

Sample code 1:

yyjson_doc *doc = yyjson_read("[1,2,3]", 7, 0);
char *json = yyjson_write(doc, YYJSON_WRITE_PRETTY, NULL);
printf("%s\n", json);
free(json);
YYJSON_WRITE_PRETTY
static const yyjson_write_flag YYJSON_WRITE_PRETTY
Definition: yyjson.h:819

Sample code 2:

yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
yyjson_mut_val *arr = yyjson_mut_arr(doc);
yyjson_mut_doc_set_root(doc, arr);
yyjson_mut_arr_add_int(doc, arr, 1);
yyjson_mut_arr_add_int(doc, arr, 2);
yyjson_mut_arr_add_int(doc, arr, 3);
char *json = yyjson_mut_write(doc, YYJSON_WRITE_PRETTY, NULL);
printf("%s\n", json);
free(json);
yyjson_mut_doc_set_root
yyjson_api_inline void yyjson_mut_doc_set_root(yyjson_mut_doc *doc, yyjson_mut_val *root)
Definition: yyjson.h:3934
yyjson_mut_arr_add_int
yyjson_api_inline bool yyjson_mut_arr_add_int(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num)
Definition: yyjson.h:4816
yyjson_mut_doc_new
yyjson_api yyjson_mut_doc * yyjson_mut_doc_new(const yyjson_alc *alc)
yyjson_mut_arr
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr(yyjson_mut_doc *doc)
Definition: yyjson.h:4354

## Write JSON to file

The `path` is output JSON file path, If the path is invalid, you will get an error. If the file is not empty, the content will be discarded.
The `doc/val` is JSON document or root value, if you pass NULL, you will get an error.
The `flg` is writer flag, pass 0 if you don't need it, see `writer flag` for details.
The `alc` is memory allocator, pass NULL if you don't need it, see `memory allocator` for details.
The `err` is a pointer to receive error message, pass NULL if you don't need it.
This function returns true on success, or false if error occurs.

bool yyjson_write_file(const char *path,
const yyjson_doc *doc,
yyjson_write_flag flg,
const yyjson_alc *alc,
yyjson_write_err *err);
bool yyjson_mut_write_file(const char *path,
const yyjson_mut_doc *doc,
yyjson_write_flag flg,
const yyjson_alc *alc,
yyjson_write_err *err);
bool yyjson_val_write_file(const char *path,
const yyjson_val *val,
yyjson_write_flag flg,
const yyjson_alc *alc,
yyjson_write_err *err);
bool yyjson_mut_val_write_file(const char *path,
const yyjson_mut_val *val,
yyjson_write_flag flg,
const yyjson_alc *alc,
yyjson_write_err *err);
yyjson_write_file
yyjson_api bool yyjson_write_file(const char *path, const yyjson_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_val_write_file
yyjson_api bool yyjson_val_write_file(const char *path, const yyjson_val *val, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_mut_write_file
yyjson_api bool yyjson_mut_write_file(const char *path, const yyjson_mut_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_mut_val_write_file
yyjson_api bool yyjson_mut_val_write_file(const char *path, const yyjson_mut_val *val, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_write_err
Definition: yyjson.h:871

Sample code:

yyjson_doc *doc = yyjson_read_file("/tmp/test.json", 0, NULL, NULL);
bool suc = yyjson_write_file("tmp/test.json", doc, YYJSON_WRITE_PRETTY, NULL, NULL);
if (suc) printf("OK");

## Write JSON with options

The `doc/val` is JSON document or root value, if you pass NULL, you will get NULL result.
The `flg` is writer flag, pass 0 if you don't need it, see `writer flag` for details.
The `alc` is memory allocator, pass NULL if you don't need it, see `memory allocator` for details.
The `len` is a pointer to receive output length, pass NULL if you don't need it.
The `err` is a pointer to receive error message, pass NULL if you don't need it.

This function returns a new JSON string, or NULL if error occurs.
The string is encoded as UTF-8 with a null-terminator.
You should use free() or alc->free() to release it when it's no longer needed.

char *yyjson_write_opts(const yyjson_doc *doc,
yyjson_write_flag flg,
const yyjson_alc *alc,
size_t *len,
yyjson_write_err *err);
char *yyjson_mut_write_opts(const yyjson_mut_doc *doc,
yyjson_write_flag flg,
const yyjson_alc *alc,
size_t *len,
yyjson_write_err *err);
char *yyjson_val_write_opts(const yyjson_val *val,
yyjson_write_flag flg,
const yyjson_alc *alc,
size_t *len,
yyjson_write_err *err);
char *yyjson_mut_val_write_opts(const yyjson_mut_val *val,
yyjson_write_flag flg,
const yyjson_alc *alc,
size_t *len,
yyjson_write_err *err);
yyjson_write_opts
yyjson_api char * yyjson_write_opts(const yyjson_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err)
yyjson_val_write_opts
yyjson_api char * yyjson_val_write_opts(const yyjson_val *val, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err)
yyjson_mut_write_opts
yyjson_api char * yyjson_mut_write_opts(const yyjson_mut_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err)
yyjson_mut_val_write_opts
yyjson_api char * yyjson_mut_val_write_opts(const yyjson_mut_val *val, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err)

Sample code:

yyjson_doc *doc = ...;
// init an allocator with stack memory
char buf[64 * 1024];
yyjson_alc alc;
yyjson_alc_pool_init(&alc, buf, sizeof(buf));
// write
size_t len;
yyjson_write_err err;
char *json = yyjson_write_opts(doc, YYJSON_WRITE_PRETTY | YYJSON_WRITE_ESCAPE_UNICODE, &alc, &len, &err);
// get result
if (json) {
printf("suc: %lu\n%s\n", len, json);
} else {
printf("err: %u msg:%s\n", err.code, err.msg);
}
alc.free(alc.ctx, json);
yyjson_alc::free
void(* free)(void *ctx, void *ptr)
Definition: yyjson.h:480
yyjson_alc::ctx
void * ctx
Definition: yyjson.h:482
yyjson_write_err::msg
const char * msg
Definition: yyjson.h:875
yyjson_alc_pool_init
yyjson_api bool yyjson_alc_pool_init(yyjson_alc *alc, void *buf, size_t size)
YYJSON_WRITE_ESCAPE_UNICODE
static const yyjson_write_flag YYJSON_WRITE_ESCAPE_UNICODE
Definition: yyjson.h:822
yyjson_write_err::code
yyjson_write_code code
Definition: yyjson.h:873

## Writer flag

yyjson provides a set of flags for JSON writer.
You can use a single flag, or combine multiple flags with bitwise `|` operator.

● YYJSON_WRITE_NOFLAG = 0
This is the default flag for JSON writer:

- Write JSON minify.
- Report error on inf or nan number.
- Report error on invalid UTF-8 string.
- Do not escape unicode or slash.

● YYJSON_WRITE_PRETTY
Write JSON pretty with 4 space indent.

● YYJSON_WRITE_ESCAPE_UNICODE
Escape unicode as `\uXXXX`, make the output ASCII only, for example:

["Alizée, 😊"]
["Aliz\\u00E9e, \\uD83D\\uDE0A"]

● YYJSON_WRITE_ESCAPE_SLASHES
Escape `/` as `\/`, for example:

["https://github.com"]
["https:\/\/github.com"]

● YYJSON_WRITE_ALLOW_INF_AND_NAN
Write inf/nan number as `Infinity` and `NaN` literals.
Note that this output is NOT standard JSON and may be rejected by other JSON libraries, for example:

{"not a number":NaN,"large number":Infinity}

● YYJSON_WRITE_INF_AND_NAN_AS_NULL
Write inf/nan number as `null` literal.
This flag will override `YYJSON_WRITE_ALLOW_INF_AND_NAN` flag, for example:

{"not a number":null,"large number":null}

● YYJSON_WRITE_ALLOW_INVALID_UNICODE
Allow invalid unicode when encoding string values.

Invalid characters in string value will be copied byte by byte. If `YYJSON_WRITE_ESCAPE_UNICODE` flag is also set, invalid character will be escaped as `\uFFFD` (replacement character).

This flag does not affect the performance of correctly encoded string.

# Access JSON Document

## JSON Document API

Returns the root value of this JSON document.

yyjson_val *yyjson_doc_get_root(yyjson_doc *doc);
yyjson_doc_get_root
yyjson_api_inline yyjson_val * yyjson_doc_get_root(yyjson_doc *doc)
Definition: yyjson.h:3445

Returns read size of input JSON data.

size_t yyjson_doc_get_read_size(yyjson_doc *doc);

Returns total value count in this JSON document.

size_t yyjson_doc_get_val_count(yyjson_doc *doc);
yyjson_doc_get_val_count
yyjson_api_inline size_t yyjson_doc_get_val_count(yyjson_doc *doc)
Definition: yyjson.h:3453

Release the JSON document and free the memory.

void yyjson_doc_free(yyjson_doc *doc);

## JSON Value API

Returns true if the JSON value is specified type.
Returns false if the input is `NULL` or not the specified type.

This set of APIs also have version for mutable values, see `mutable and immutable` for details.

bool yyjson_is_null(yyjson_val *val); // null
bool yyjson_is_true(yyjson_val *val); // true
bool yyjson_is_false(yyjson_val *val); // false
bool yyjson_is_bool(yyjson_val *val); // true or false
bool yyjson_is_uint(yyjson_val *val); // unsigned integer
bool yyjson_is_sint(yyjson_val *val); // signed integer
bool yyjson_is_int(yyjson_val *val); // unsigned or signed integer
bool yyjson_is_real(yyjson_val *val); // double number
bool yyjson_is_num(yyjson_val *val); // integer or double number
bool yyjson_is_str(yyjson_val *val); // string
bool yyjson_is_arr(yyjson_val *val); // array
bool yyjson_is_obj(yyjson_val *val); // object
bool yyjson_is_ctn(yyjson_val *val); // array or object
yyjson_is_ctn
yyjson_api_inline bool yyjson_is_ctn(yyjson_val *val)
Definition: yyjson.h:3523
yyjson_is_bool
yyjson_api_inline bool yyjson_is_bool(yyjson_val *val)
Definition: yyjson.h:3487
yyjson_is_real
yyjson_api_inline bool yyjson_is_real(yyjson_val *val)
Definition: yyjson.h:3503
yyjson_is_int
yyjson_api_inline bool yyjson_is_int(yyjson_val *val)
Definition: yyjson.h:3499
yyjson_is_true
yyjson_api_inline bool yyjson_is_true(yyjson_val *val)
Definition: yyjson.h:3479
yyjson_is_false
yyjson_api_inline bool yyjson_is_false(yyjson_val *val)
Definition: yyjson.h:3483
yyjson_is_null
yyjson_api_inline bool yyjson_is_null(yyjson_val *val)
Definition: yyjson.h:3475
yyjson_is_sint
yyjson_api_inline bool yyjson_is_sint(yyjson_val *val)
Definition: yyjson.h:3495
yyjson_is_uint
yyjson_api_inline bool yyjson_is_uint(yyjson_val *val)
Definition: yyjson.h:3491
yyjson_is_arr
yyjson_api_inline bool yyjson_is_arr(yyjson_val *val)
Definition: yyjson.h:3515
yyjson_is_num
yyjson_api_inline bool yyjson_is_num(yyjson_val *val)
Definition: yyjson.h:3507
yyjson_is_obj
yyjson_api_inline bool yyjson_is_obj(yyjson_val *val)
Definition: yyjson.h:3519

## JSON Value Content API

Returns the content or type of a JSON value.
This set of APIs also have version for mutable values, see `mutable and immutable` for details.

Returns value's type.

yyjson_type yyjson_get_type(yyjson_val *val);
yyjson_type
uint8_t yyjson_type
Definition: yyjson.h:430
yyjson_get_type
yyjson_api_inline yyjson_type yyjson_get_type(yyjson_val *val)
Definition: yyjson.h:3533

Returns value's subtype.

yyjson_subtype yyjson_get_subtype(yyjson_val *val);
yyjson_subtype
uint8_t yyjson_subtype
Definition: yyjson.h:441
yyjson_get_subtype
yyjson_api_inline yyjson_subtype yyjson_get_subtype(yyjson_val *val)
Definition: yyjson.h:3537

Returns value's tag.

uint8_t yyjson_get_tag(yyjson_val *val);
yyjson_get_tag
yyjson_api_inline uint8_t yyjson_get_tag(yyjson_val *val)
Definition: yyjson.h:3541

Returns type description, such as: "null", "string", "array", "object", "true", "false", "uint", "sint", "real", "unknown"

const char *yyjson_get_type_desc(yyjson_val *val);
yyjson_get_type_desc
yyjson_api_inline const char * yyjson_get_type_desc(yyjson_val *val)
Definition: yyjson.h:3545

Returns bool value, or false if the value is not bool type.

bool yyjson_get_bool(yyjson_val *val);
yyjson_get_bool
yyjson_api_inline bool yyjson_get_bool(yyjson_val *val)
Definition: yyjson.h:3565

Returns uint value, or 0 if the value is not uint type.

uint64_t yyjson_get_uint(yyjson_val *val);
yyjson_get_uint
yyjson_api_inline uint64_t yyjson_get_uint(yyjson_val *val)
Definition: yyjson.h:3569

Returns sint value, or 0 if the value is not sint type.

int64_t yyjson_get_sint(yyjson_val *val);
yyjson_get_sint
yyjson_api_inline int64_t yyjson_get_sint(yyjson_val *val)
Definition: yyjson.h:3573

Returns int value (uint may overflow), or 0 if the value is not uint or sint type.

int yyjson_get_int(yyjson_val *val);
yyjson_get_int
yyjson_api_inline int yyjson_get_int(yyjson_val *val)
Definition: yyjson.h:3577

Returns double value, or 0 if the value is not real type.

double yyjson_get_real(yyjson_val *val);
yyjson_get_real
yyjson_api_inline double yyjson_get_real(yyjson_val *val)
Definition: yyjson.h:3581

Returns the string value, or NULL if the value is not string type

const char *yyjson_get_str(yyjson_val *val);
yyjson_get_str
yyjson_api_inline const char * yyjson_get_str(yyjson_val *val)
Definition: yyjson.h:3585

Returns the string's length, or 0 if the value is not string type.

size_t yyjson_get_len(yyjson_val *val);
yyjson_get_len
yyjson_api_inline size_t yyjson_get_len(yyjson_val *val)
Definition: yyjson.h:3589

Returns whether the value is equals to a string.

bool yyjson_equals_str(yyjson_val *val, const char *str);

Same as `yyjson_equals_str(), but you can pass an explicit string length.

bool yyjson_equals_strn(yyjson_val *val, const char *str, size_t len);

## JSON Array API

Returns the property or child value of a JSON array.
This set of APIs also have version for mutable values, see `mutable and immutable` for details.

Returns the number of elements in this array, or 0 if the input is not an array.

size_t yyjson_arr_size(yyjson_val *arr);
yyjson_arr_size
yyjson_api_inline size_t yyjson_arr_size(yyjson_val *arr)
Definition: yyjson.h:3623

Returns the element at the specified position in this array, or NULL if array is empty or the index is out of bounds.
Note that this function takes a linear search time if array is not flat.

yyjson_val *yyjson_arr_get(yyjson_val *arr, size_t idx);
yyjson_arr_get
yyjson_api_inline yyjson_val * yyjson_arr_get(yyjson_val *arr, size_t idx)
Definition: yyjson.h:3627

Returns the first element of this array, or NULL if array is empty.

yyjson_val *yyjson_arr_get_first(yyjson_val *arr);
yyjson_arr_get_first
yyjson_api_inline yyjson_val * yyjson_arr_get_first(yyjson_val *arr)
Definition: yyjson.h:3642

Returns the last element of this array, or NULL if array is empty.
Note tha this function takes a linear search time if array is not flat.

yyjson_val *yyjson_arr_get_last(yyjson_val *arr);
yyjson_arr_get_last
yyjson_api_inline yyjson_val * yyjson_arr_get_last(yyjson_val *arr)
Definition: yyjson.h:3651

## JSON Array Iterator API

You can use two methods to traverse an array:

Sample code (iterator):

yyjson_val *arr; // this is your array
yyjson_val *val;
yyjson_arr_iter iter;
yyjson_arr_iter_init(arr, &iter);
while ((val = yyjson_arr_iter_next(&iter))) {
print(val);
}
yyjson_arr_iter_init
yyjson_api_inline bool yyjson_arr_iter_init(yyjson_val *arr, yyjson_arr_iter *iter)
Definition: yyjson.h:3679
yyjson_arr_iter_next
yyjson_api_inline yyjson_val * yyjson_arr_iter_next(yyjson_arr_iter *iter)
Definition: yyjson.h:3695
yyjson_arr_iter
Definition: yyjson.h:3673

Sample code (foreach):

yyjson_val *arr; // this is your array
size_t idx, max;
yyjson_val *val;
yyjson_arr_foreach(arr, idx, max, val) {
print(idx, val);
}
yyjson_arr_foreach
#define yyjson_arr_foreach(arr, idx, max, val)
Definition: yyjson.h:1440

There's also mutable version API to traverse an mutable array:

Sample code (mutable iterator):

yyjson_mut_val *arr; // this is your mutable array
yyjson_mut_val *val;
yyjson_mut_arr_iter iter;
yyjson_mut_arr_iter_init(arr, &iter);
while ((val = yyjson_mut_arr_iter_next(&iter))) {
if (val_is_unused(val)) {
// remove current value inside iteration
yyjson_mut_arr_iter_remove(&iter);
}
}
yyjson_mut_arr_iter_remove
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_iter_remove(yyjson_mut_arr_iter *iter)
Definition: yyjson.h:4331
yyjson_mut_arr_iter_next
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_iter_next(yyjson_mut_arr_iter *iter)
Definition: yyjson.h:4319
yyjson_mut_arr_iter_init
yyjson_api_inline bool yyjson_mut_arr_iter_init(yyjson_mut_val *arr, yyjson_mut_arr_iter *iter)
Definition: yyjson.h:4301
yyjson_mut_arr_iter
Definition: yyjson.h:4293

Sample code (mutable foreach):

yyjson_mut_val *arr; // this is your mutable array
size_t idx, max;
yyjson_mut_val *val;
yyjson_mut_arr_foreach(arr, idx, max, val) {
print(idx, val);
}
yyjson_mut_arr_foreach
#define yyjson_mut_arr_foreach(arr, idx, max, val)
Definition: yyjson.h:1989

## JSON Object API

Returns the property or child value of a JSON object.
This set of APIs also have version for mutable values, see `mutable and immutable` for details.

Returns the number of key-value pairs in this object, or 0 if input is not an object.

size_t yyjson_obj_size(yyjson_val *obj);
yyjson_obj_size
yyjson_api_inline size_t yyjson_obj_size(yyjson_val *obj)
Definition: yyjson.h:3712

Returns the value to which the specified key is mapped,
or NULL if this object contains no mapping for the key.
Note that this function takes a linear search time.

yyjson_val *yyjson_obj_get(yyjson_val *obj, const char *key);
yyjson_obj_get
yyjson_api_inline yyjson_val * yyjson_obj_get(yyjson_val *obj, const char *key)
Definition: yyjson.h:3716

Same as `yyjson_obj_get(), but you can pass an explicit string length.

yyjson_val *yyjson_obj_getn(yyjson_val *obj, const char *key, size_t key_len);
yyjson_obj_getn
yyjson_api_inline yyjson_val * yyjson_obj_getn(yyjson_val *obj, const char *key, size_t key_len)
Definition: yyjson.h:3721

If the order of object's key is known at compile-time, you can use this method to avoid searching the entire object:

// { "x":1, "y":2, "z":3 }
yyjson_val *obj = ...;
yyjson_obj_iter iter;
if (yyjson_obj_iter_init(obj, &iter)) {
yyjson_val *x = yyjson_obj_iter_get(&iter, "x");
yyjson_val *y = yyjson_obj_iter_get(&iter, "y");
yyjson_val *z = yyjson_obj_iter_get(&iter, "z");
}
yyjson_obj_iter_get
yyjson_api_inline yyjson_val * yyjson_obj_iter_get(yyjson_obj_iter *iter, const char *key)
Definition: yyjson.h:3783
yyjson_obj_iter_init
yyjson_api_inline bool yyjson_obj_iter_init(yyjson_val *obj, yyjson_obj_iter *iter)
Definition: yyjson.h:3752
yyjson_obj_iter
Definition: yyjson.h:3745

## JSON Object Iterator API

You can use two methods to traverse an object:

Sample code (iterator):

yyjson_val *obj; // this is your object
yyjson_val *key, *val;
yyjson_obj_iter iter;
yyjson_obj_iter_init(obj, &iter);
while ((key = yyjson_obj_iter_next(&iter))) {
val = yyjson_obj_iter_get_val(key);
print(key, val);
}
yyjson_obj_iter_get_val
yyjson_api_inline yyjson_val * yyjson_obj_iter_get_val(yyjson_val *key)
Definition: yyjson.h:3779
yyjson_obj_iter_next
yyjson_api_inline yyjson_val * yyjson_obj_iter_next(yyjson_obj_iter *iter)
Definition: yyjson.h:3769

Sample code (foreach):

yyjson_val *obj; // this is your object
size_t idx, max;
yyjson_val *key, *val;
yyjson_obj_foreach(obj, idx, max, key, val) {
print(key, val);
}
yyjson_obj_foreach
#define yyjson_obj_foreach(obj, idx, max, key, val)
Definition: yyjson.h:1597

There's also mutable version API to traverse an mutable object:

Sample code (mutable iterator):

yyjson_mut_val *obj; // this is your mutable object
yyjson_mut_val *key, *val;
yyjson_mut_obj_iter iter;
yyjson_mut_obj_iter_init(obj, &iter);
while ((key = yyjson_mut_obj_iter_next(&iter))) {
val = yyjson_mut_obj_iter_get_val(key);
if (key_is_unused(key)) {
// remove current key-value pair inside iteration
yyjson_mut_obj_iter_remove(&iter);
}
}
yyjson_mut_obj_iter_next
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_next(yyjson_mut_obj_iter *iter)
Definition: yyjson.h:4959
yyjson_mut_obj_iter_remove
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_remove(yyjson_mut_obj_iter *iter)
Definition: yyjson.h:4976
yyjson_mut_obj_iter_get_val
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_get_val(yyjson_mut_val *key)
Definition: yyjson.h:4971
yyjson_mut_obj_iter_init
yyjson_api_inline bool yyjson_mut_obj_iter_init(yyjson_mut_val *obj, yyjson_mut_obj_iter *iter)
Definition: yyjson.h:4941
yyjson_mut_obj_iter
Definition: yyjson.h:4933

Sample code (mutable foreach):

yyjson_mut_val *obj; // this is your mutable object
size_t idx, max;
yyjson_val *key, *val;
yyjson_obj_foreach(obj, idx, max, key, val) {
print(key, val);
}

## JSON Pointer

yyjson allows you to query JSON value with `JSON Pointer` (RFC 6901).

// pointer is a null-terminated string
yyjson_val *yyjson_get_pointer(yyjson_val *val, const char *ptr);
yyjson_val *yyjson_doc_get_pointer(yyjson_doc *doc, const char *ptr);
yyjson_mut_val *yyjson_mut_get_pointer(yyjson_mut_val *val, const char *ptr);
yyjson_mut_val *yyjson_mut_doc_get_pointer(yyjson_mut_doc *doc, const char *ptr);
// pointer with string length, allow NUL (Unicode U+0000) characters inside
yyjson_val *yyjson_get_pointern(yyjson_val *val, const char *ptr, size_t len);
yyjson_val *yyjson_doc_get_pointern(yyjson_doc *doc, const char *ptr, size_t len);
yyjson_mut_val *yyjson_mut_get_pointern(yyjson_mut_val *val, const char *ptr, size_t len);
yyjson_mut_val *yyjson_mut_doc_get_pointern(yyjson_mut_doc *doc, const char *ptr, size_t len);
yyjson_get_pointer
yyjson_api_inline yyjson_val * yyjson_get_pointer(yyjson_val *val, const char *ptr)
Definition: yyjson.h:5491
yyjson_mut_get_pointer
yyjson_api_inline yyjson_mut_val * yyjson_mut_get_pointer(yyjson_mut_val *val, const char *ptr)
Definition: yyjson.h:5517
yyjson_mut_doc_get_pointer
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_get_pointer(yyjson_mut_doc *doc, const char *ptr)
Definition: yyjson.h:5528
yyjson_mut_doc_get_pointern
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_get_pointern(yyjson_mut_doc *doc, const char *ptr, size_t len)
Definition: yyjson.h:5523
yyjson_doc_get_pointern
yyjson_api_inline yyjson_val * yyjson_doc_get_pointern(yyjson_doc *doc, const char *ptr, size_t len)
Definition: yyjson.h:5497
yyjson_get_pointern
yyjson_api_inline yyjson_val * yyjson_get_pointern(yyjson_val *val, const char *ptr, size_t len)
Definition: yyjson.h:5482
yyjson_mut_get_pointern
yyjson_api_inline yyjson_mut_val * yyjson_mut_get_pointern(yyjson_mut_val *val, const char *ptr, size_t len)
Definition: yyjson.h:5508
yyjson_doc_get_pointer
yyjson_api_inline yyjson_val * yyjson_doc_get_pointer(yyjson_doc *doc, const char *ptr)
Definition: yyjson.h:5503

For example, given the JSON document:

{
"size" : 3,
"users" : [
{"id": 1, "name": "Harry"},
{"id": 2, "name": "Ron"},
{"id": 3, "name": "Hermione"}
]
}

The following JSON strings evaluate to the accompanying values:

Pointer | Matched Value
--- | ---
`""` | `the whole document`
`"/size"` | `3`
`"/users/0"` | `{"id": 1, "name": "Harry"}`
`"/users/1/name"` | `"Ron"`
`"/no_match"` | NULL
`"no_slash"` | NULL

# Create JSON Document

You can use a `yyjson_mut_doc` to build your JSON document.

Notice that `yyjson_mut_doc` use a memory pool to hold all strings and values; the pool can only be created, grown or freed in its entirety. Thus `yyjson_mut_doc` is more suitable for write-once, than mutation of an existing document.

Sample code:

// Create a mutable document.
yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
// Create a `uint` value, the value's memory is held by doc.
yyjson_mut_val *val = yyjson_mut_uint(doc, 100);
// Create an array, the array's memory is held by doc.
yyjson_mut_val *arr1 = yyjson_mut_arr(doc);
yyjson_mut_val *arr2 = yyjson_mut_arr(doc);
// Add the value to arr1
yyjson_mut_arr_append(arr1, val);
// ❌ Wrong, the value is already added to another container.
yyjson_mut_arr_append(arr2, val);
// Free the memory of doc and all values which is created from this doc.
yyjson_mut_doc_free(doc);
yyjson_mut_doc_free
yyjson_api void yyjson_mut_doc_free(yyjson_mut_doc *doc)
yyjson_mut_uint
yyjson_api_inline yyjson_mut_val * yyjson_mut_uint(yyjson_mut_doc *doc, uint64_t num)
Definition: yyjson.h:4166
yyjson_mut_arr_append
yyjson_api_inline bool yyjson_mut_arr_append(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:4575

## Mutable Document API

Creates and returns a new mutable JSON document, returns NULL on error.
If allocator is NULL, the default allocator will be used. The `alc` is memory allocator, pass NULL if you don't need it, see `memory allocator` for details.

yyjson_mut_doc *yyjson_mut_doc_new(yyjson_alc *alc);

Delete the JSON document, free the memory of this doc (and all values created from this doc).

void yyjson_mut_doc_free(yyjson_mut_doc *doc);

Get or set the root value of this JSON document.

yyjson_mut_val *yyjson_mut_doc_get_root(yyjson_mut_doc *doc);
void yyjson_mut_doc_set_root(yyjson_mut_doc *doc, yyjson_mut_val *root);
yyjson_mut_doc_get_root
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_get_root(yyjson_mut_doc *doc)
Definition: yyjson.h:3930

Copies and returns a new mutable document from input, returns NULL on error.
The `alc` is memory allocator, pass NULL if you don't need it, see `memory allocator` for details.

yyjson_mut_doc *yyjson_doc_mut_copy(yyjson_doc *doc, yyjson_alc *alc);

Copies and returns a new mutable value from input, returns NULL on error.
The memory was managed by document. */

yyjson_mut_val *yyjson_val_mut_copy(yyjson_mut_doc *doc, yyjson_val *val);

## Mutable JSON Value Creation API

You can use these functions to create mutable JSON value,
The value's memory is held by the document.

Creates and returns a null value, returns NULL on error.

yyjson_mut_val *yyjson_mut_null(yyjson_mut_doc *doc);
yyjson_mut_null
yyjson_api_inline yyjson_mut_val * yyjson_mut_null(yyjson_mut_doc *doc)
Definition: yyjson.h:4121

Creates and returns a true value, returns NULL on error.

yyjson_mut_val *yyjson_mut_true(yyjson_mut_doc *doc);
yyjson_mut_true
yyjson_api_inline yyjson_mut_val * yyjson_mut_true(yyjson_mut_doc *doc)
Definition: yyjson.h:4132

Creates and returns a false value, returns NULL on error.

yyjson_mut_val *yyjson_mut_false(yyjson_mut_doc *doc);
yyjson_mut_false
yyjson_api_inline yyjson_mut_val * yyjson_mut_false(yyjson_mut_doc *doc)
Definition: yyjson.h:4143

Creates and returns a bool value, returns NULL on error.

yyjson_mut_val *yyjson_mut_bool(yyjson_mut_doc *doc, bool val);
yyjson_mut_bool
yyjson_api_inline yyjson_mut_val * yyjson_mut_bool(yyjson_mut_doc *doc, bool val)
Definition: yyjson.h:4154

Creates and returns an unsigned integer value, returns NULL on error.

yyjson_mut_val *yyjson_mut_uint(yyjson_mut_doc *doc, uint64_t num);

Creates and returns a signed integer value, returns NULL on error.

yyjson_mut_val *yyjson_mut_sint(yyjson_mut_doc *doc, int64_t num);
yyjson_mut_sint
yyjson_api_inline yyjson_mut_val * yyjson_mut_sint(yyjson_mut_doc *doc, int64_t num)
Definition: yyjson.h:4179

Creates and returns a signed integer value, returns NULL on error.

yyjson_mut_val *yyjson_mut_int(yyjson_mut_doc *doc, int64_t num);
yyjson_mut_int
yyjson_api_inline yyjson_mut_val * yyjson_mut_int(yyjson_mut_doc *doc, int64_t num)
Definition: yyjson.h:4192

Creates and returns an real number value, returns NULL on error.

yyjson_mut_val *yyjson_mut_real(yyjson_mut_doc *doc, double num);
yyjson_mut_real
yyjson_api_inline yyjson_mut_val * yyjson_mut_real(yyjson_mut_doc *doc, double num)
Definition: yyjson.h:4197

Creates and returns a string value, returns NULL on error.
The input value should be a valid UTF-8 encoded string with null-terminator.
Note that the input string is NOT copied.

yyjson_mut_val *yyjson_mut_str(yyjson_mut_doc *doc, const char *str);

Creates and returns a string value, returns NULL on error.
The input value should be a valid UTF-8 encoded string.
Note that the input string is NOT copied.

yyjson_mut_val *yyjson_mut_strn(yyjson_mut_doc *doc, const char *str, size_t len);

Creates and returns a string value, returns NULL on error.
The input value should be a valid UTF-8 encoded string with null-terminator.
The input string is copied and held by the document.

yyjson_mut_val *yyjson_mut_strcpy(yyjson_mut_doc *doc, const char *str);

Creates and returns a string value, returns NULL on error.
The input value should be a valid UTF-8 encoded string.
The input string is copied and held by the document.

yyjson_mut_val *yyjson_mut_strncpy(yyjson_mut_doc *doc, const char *str, size_t len);

## Mutable JSON Array Creation API

Creates and returns an empty mutable array, returns NULL on error.

yyjson_mut_val *yyjson_mut_arr(yyjson_mut_doc *doc);

Creates and returns a mutable array with c array.

yyjson_mut_val *yyjson_mut_arr_with_bool(yyjson_mut_doc *doc, bool *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_sint(yyjson_mut_doc *doc, int64_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_uint(yyjson_mut_doc *doc, uint64_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_real(yyjson_mut_doc *doc, double *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_sint8(yyjson_mut_doc *doc, int8_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_sint16(yyjson_mut_doc *doc, int16_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_sint32(yyjson_mut_doc *doc, int32_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_sint64(yyjson_mut_doc *doc, int64_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_uint8(yyjson_mut_doc *doc, uint8_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_uint16(yyjson_mut_doc *doc, uint16_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_uint32(yyjson_mut_doc *doc, uint32_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_uint64(yyjson_mut_doc *doc, uint64_t *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_float(yyjson_mut_doc *doc, float *vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_double(yyjson_mut_doc *doc, double *vals, size_t count);
// sample:
int vals[3] = {-1, 0, 1};
yyjson_mut_val *arr = yyjson_mut_arr_with_sint32(doc, vals, 3);
yyjson_mut_arr_with_sint
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_sint(yyjson_mut_doc *doc, const int64_t *vals, size_t count)
Definition: yyjson.h:4393
yyjson_mut_arr_with_uint8
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_uint8(yyjson_mut_doc *doc, const uint8_t *vals, size_t count)
Definition: yyjson.h:4440
yyjson_mut_arr_with_sint64
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_sint64(yyjson_mut_doc *doc, const int64_t *vals, size_t count)
Definition: yyjson.h:4432
yyjson_mut_arr_with_float
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_float(yyjson_mut_doc *doc, const float *vals, size_t count)
Definition: yyjson.h:4472
yyjson_mut_arr_with_sint32
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_sint32(yyjson_mut_doc *doc, const int32_t *vals, size_t count)
Definition: yyjson.h:4424
yyjson_mut_arr_with_real
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_real(yyjson_mut_doc *doc, const double *vals, size_t count)
Definition: yyjson.h:4403
yyjson_mut_arr_with_sint16
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_sint16(yyjson_mut_doc *doc, const int16_t *vals, size_t count)
Definition: yyjson.h:4416
yyjson_mut_arr_with_uint16
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_uint16(yyjson_mut_doc *doc, const uint16_t *vals, size_t count)
Definition: yyjson.h:4448
yyjson_mut_arr_with_uint64
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_uint64(yyjson_mut_doc *doc, const uint64_t *vals, size_t count)
Definition: yyjson.h:4464
yyjson_mut_arr_with_uint
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_uint(yyjson_mut_doc *doc, const uint64_t *vals, size_t count)
Definition: yyjson.h:4398
yyjson_mut_arr_with_sint8
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_sint8(yyjson_mut_doc *doc, const int8_t *vals, size_t count)
Definition: yyjson.h:4408
yyjson_mut_arr_with_uint32
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_uint32(yyjson_mut_doc *doc, const uint32_t *vals, size_t count)
Definition: yyjson.h:4456
yyjson_mut_arr_with_double
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_double(yyjson_mut_doc *doc, const double *vals, size_t count)
Definition: yyjson.h:4480
yyjson_mut_arr_with_bool
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_bool(yyjson_mut_doc *doc, const bool *vals, size_t count)
Definition: yyjson.h:4386

Creates and returns a mutable array with strings. The strings should be encoded as UTF-8.

yyjson_mut_val *yyjson_mut_arr_with_str(yyjson_mut_doc *doc, const char **vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_strn(yyjson_mut_doc *doc, const char **vals, const size_t *lens, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_strcpy(yyjson_mut_doc *doc, const char **vals, size_t count);
yyjson_mut_val *yyjson_mut_arr_with_strncpy(yyjson_mut_doc *doc, const char **vals, const size_t *lens, size_t count);
// sample:
const char strs[3] = {"Jan", "Feb", "Mar"};
yyjson_mut_val *arr = yyjson_mut_arr_with_str(doc, strs, 3);
yyjson_mut_arr_with_strn
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_strn(yyjson_mut_doc *doc, const char **vals, const size_t *lens, size_t count)
Definition: yyjson.h:4498
yyjson_mut_arr_with_strcpy
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_strcpy(yyjson_mut_doc *doc, const char **vals, size_t count)
Definition: yyjson.h:4508
yyjson_mut_arr_with_strncpy
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_strncpy(yyjson_mut_doc *doc, const char **vals, const size_t *lens, size_t count)
Definition: yyjson.h:4522
yyjson_mut_arr_with_str
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_str(yyjson_mut_doc *doc, const char **vals, size_t count)
Definition: yyjson.h:4488

## Mutable JSON Array Modification API

Inserts a value into an array at a given index, returns false on error.
Note that Tthis function takes a linear search time.

bool yyjson_mut_arr_insert(yyjson_mut_val *arr, yyjson_mut_val *val, size_t idx);
yyjson_mut_arr_insert
yyjson_api_inline bool yyjson_mut_arr_insert(yyjson_mut_val *arr, yyjson_mut_val *val, size_t idx)
Definition: yyjson.h:4544

Inserts a val at the end of the array, returns false on error.

bool yyjson_mut_arr_append(yyjson_mut_val *arr, yyjson_mut_val *val);

Inserts a val at the head of the array, returns false on error.

bool yyjson_mut_arr_prepend(yyjson_mut_val *arr, yyjson_mut_val *val);
yyjson_mut_arr_prepend
yyjson_api_inline bool yyjson_mut_arr_prepend(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:4594

Replaces a value at index and returns old value, returns NULL on error.
Note that this function takes a linear search time.

yyjson_mut_val *yyjson_mut_arr_replace(yyjson_mut_val *arr, size_t idx, yyjson_mut_val *val);
yyjson_mut_arr_replace
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_replace(yyjson_mut_val *arr, size_t idx, yyjson_mut_val *val)
Definition: yyjson.h:4613

Removes and returns a value at index, returns NULL on error.
Note that this function takes a linear search time.

yyjson_mut_val *yyjson_mut_arr_remove(yyjson_mut_val *arr, size_t idx);
yyjson_mut_arr_remove
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove(yyjson_mut_val *arr, size_t idx)
Definition: yyjson.h:4641

Removes and returns the first value in this array, returns NULL on error.

yyjson_mut_val *yyjson_mut_arr_remove_first(yyjson_mut_val *arr);
yyjson_mut_arr_remove_first
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove_first(yyjson_mut_val *arr)
Definition: yyjson.h:4665

Removes and returns the last value in this array, returns NULL on error.

yyjson_mut_val *yyjson_mut_arr_remove_last(yyjson_mut_val *arr);
yyjson_mut_arr_remove_last
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove_last(yyjson_mut_val *arr)
Definition: yyjson.h:4684

Removes all values within a specified range in the array.
Note that this function takes a linear search time.

bool yyjson_mut_arr_remove_range(yyjson_mut_val *arr, size_t idx, size_t len);
yyjson_mut_arr_remove_range
yyjson_api_inline bool yyjson_mut_arr_remove_range(yyjson_mut_val *arr, size_t idx, size_t len)
Definition: yyjson.h:4706

Removes all values in this array.

bool yyjson_mut_arr_clear(yyjson_mut_val *arr);
yyjson_mut_arr_clear
yyjson_api_inline bool yyjson_mut_arr_clear(yyjson_mut_val *arr)
Definition: yyjson.h:4728

## Mutable JSON Array Modification Convenience API

Adds a value at the end of this array, returns false on error.

bool yyjson_mut_arr_add_val(yyjson_mut_val *arr, yyjson_mut_val *val);
bool yyjson_mut_arr_add_null(yyjson_mut_doc *doc, yyjson_mut_val *arr);
bool yyjson_mut_arr_add_true(yyjson_mut_doc *doc, yyjson_mut_val *arr);
bool yyjson_mut_arr_add_false(yyjson_mut_doc *doc, yyjson_mut_val *arr);
bool yyjson_mut_arr_add_bool(yyjson_mut_doc *doc, yyjson_mut_val *arr, bool val);
bool yyjson_mut_arr_add_uint(yyjson_mut_doc *doc, yyjson_mut_val *arr, uint64_t num);
bool yyjson_mut_arr_add_sint(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num);
bool yyjson_mut_arr_add_int(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num);
bool yyjson_mut_arr_add_real(yyjson_mut_doc *doc, yyjson_mut_val *arr, double num);
bool yyjson_mut_arr_add_str(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str);
bool yyjson_mut_arr_add_strn(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str, size_t len);
bool yyjson_mut_arr_add_strcpy(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str);
bool yyjson_mut_arr_add_strncpy(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str, size_t len);
yyjson_mut_arr_add_str
yyjson_api_inline bool yyjson_mut_arr_add_str(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str)
Definition: yyjson.h:4836
yyjson_mut_arr_add_true
yyjson_api_inline bool yyjson_mut_arr_add_true(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:4768
yyjson_mut_arr_add_strncpy
yyjson_api_inline bool yyjson_mut_arr_add_strncpy(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str, size_t len)
Definition: yyjson.h:4866
yyjson_mut_arr_add_strcpy
yyjson_api_inline bool yyjson_mut_arr_add_strcpy(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str)
Definition: yyjson.h:4856
yyjson_mut_arr_add_bool
yyjson_api_inline bool yyjson_mut_arr_add_bool(yyjson_mut_doc *doc, yyjson_mut_val *arr, bool val)
Definition: yyjson.h:4786
yyjson_mut_arr_add_uint
yyjson_api_inline bool yyjson_mut_arr_add_uint(yyjson_mut_doc *doc, yyjson_mut_val *arr, uint64_t num)
Definition: yyjson.h:4796
yyjson_mut_arr_add_false
yyjson_api_inline bool yyjson_mut_arr_add_false(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:4777
yyjson_mut_arr_add_strn
yyjson_api_inline bool yyjson_mut_arr_add_strn(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str, size_t len)
Definition: yyjson.h:4846
yyjson_mut_arr_add_real
yyjson_api_inline bool yyjson_mut_arr_add_real(yyjson_mut_doc *doc, yyjson_mut_val *arr, double num)
Definition: yyjson.h:4826
yyjson_mut_arr_add_val
yyjson_api_inline bool yyjson_mut_arr_add_val(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:4754
yyjson_mut_arr_add_sint
yyjson_api_inline bool yyjson_mut_arr_add_sint(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num)
Definition: yyjson.h:4806
yyjson_mut_arr_add_null
yyjson_api_inline bool yyjson_mut_arr_add_null(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:4759

Creates and adds a new array at the end of the array.
Returns the new array, or NULL on error.

yyjson_mut_val *yyjson_mut_arr_add_arr(yyjson_mut_doc *doc, yyjson_mut_val *arr);
yyjson_mut_arr_add_arr
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_add_arr(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:4876

Creates and adds a new object at the end of the array.
Returns the new object, or NULL on error.

yyjson_mut_val *yyjson_mut_arr_add_obj(yyjson_mut_doc *doc, yyjson_mut_val *arr);
yyjson_mut_arr_add_obj
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_add_obj(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:4885

## Mutable JSON Object Creation API

Creates and returns a mutable object, returns NULL on error.

yyjson_mut_val *yyjson_mut_obj(yyjson_mut_doc *doc);
yyjson_mut_obj
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj(yyjson_mut_doc *doc)
Definition: yyjson.h:5026

Creates and returns a mutable object with keys and values,
returns NULL on error. The keys and values are NOT copied.
The strings should be encoded as UTF-8 with null-terminator.

yyjson_mut_val *yyjson_mut_obj_with_str(yyjson_mut_doc *doc,
const char **keys,
const char **vals,
size_t count);
// sample:
const char vkeys[] = {"name", "type", "id"};
const char *vals[] = {"Harry", "student", "888999"};
yyjson_mut_obj_with_str(doc, keys, vals, 3);
yyjson_mut_obj_with_str
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_with_str(yyjson_mut_doc *doc, const char **keys, const char **vals, size_t count)
Definition: yyjson.h:5037

Creates and returns a mutable object with key-value pairs and pair count,
returns NULL on error. The keys and values are NOT copied.
The strings should be encoded as UTF-8 with null-terminator.

yyjson_mut_val *yyjson_mut_obj_with_kv(yyjson_mut_doc *doc,
const char **kv_pairs,
size_t pair_count);
// sample:
const char *pairs[] = {"name", "Harry", "type", "student", "id", "888999"};
yyjson_mut_obj_with_kv(doc, pairs, 3);
yyjson_mut_obj_with_kv
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_with_kv(yyjson_mut_doc *doc, const char **kv_pairs, size_t pair_count)
Definition: yyjson.h:5068

## Mutable JSON Object Modification API

Adds a key-value pair at the end of the object. The key must be a string.
This function allows duplicated key in one object.

bool yyjson_mut_obj_add(yyjson_mut_val *obj, yyjson_mut_val *key,yyjson_mut_val *val);

Adds a key-value pair to the object, The key must be a string.
This function may remove all key-value pairs for the given key before add.
Note that this function takes a linear search time.

bool yyjson_mut_obj_put(yyjson_mut_val *obj, yyjson_mut_val *key, yyjson_mut_val *val);
yyjson_mut_obj_put
yyjson_api_inline bool yyjson_mut_obj_put(yyjson_mut_val *obj, yyjson_mut_val *key, yyjson_mut_val *val)
Definition: yyjson.h:5193

Removes key-value pair from the object with given key.
Note that this function takes a linear search time.

bool yyjson_mut_obj_remove(yyjson_mut_val *obj, yyjson_mut_val *key);
yyjson_mut_obj_remove
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove(yyjson_mut_val *obj, yyjson_mut_val *key)
Definition: yyjson.h:5231

Removes all key-value pairs in this object.

bool yyjson_mut_obj_clear(yyjson_mut_val *obj);
yyjson_mut_obj_clear
yyjson_api_inline bool yyjson_mut_obj_clear(yyjson_mut_val *obj)
Definition: yyjson.h:5260

## Mutable JSON Object Modification Convenience API

Adds a key-value pair at the end of the object. The key is not copied.
Note that these functions allow duplicated key in one object.

bool yyjson_mut_obj_add_null(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key);
bool yyjson_mut_obj_add_true(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key);
bool yyjson_mut_obj_add_false(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key);
bool yyjson_mut_obj_add_bool(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, bool val);
bool yyjson_mut_obj_add_uint(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, uint64_t val);
bool yyjson_mut_obj_add_sint(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, int64_t val);
bool yyjson_mut_obj_add_int(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, int64_t val);
bool yyjson_mut_obj_add_real(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, double val);
bool yyjson_mut_obj_add_str(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *val);
bool yyjson_mut_obj_add_strn(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *val, size_t len);
bool yyjson_mut_obj_add_strcpy(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *val);
bool yyjson_mut_obj_add_strncpy(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *val, size_t len);
yyjson_mut_obj_add_strncpy
yyjson_api_inline bool yyjson_mut_obj_add_strncpy(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *val, size_t len)
Definition: yyjson.h:5419
yyjson_mut_obj_add_sint
yyjson_api_inline bool yyjson_mut_obj_add_sint(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, int64_t val)
Definition: yyjson.h:5353
yyjson_mut_obj_add_strn
yyjson_api_inline bool yyjson_mut_obj_add_strn(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *val, size_t len)
Definition: yyjson.h:5394
yyjson_mut_obj_add_false
yyjson_api_inline bool yyjson_mut_obj_add_false(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:5326
yyjson_mut_obj_add_int
yyjson_api_inline bool yyjson_mut_obj_add_int(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, int64_t val)
Definition: yyjson.h:5363
yyjson_mut_obj_add_uint
yyjson_api_inline bool yyjson_mut_obj_add_uint(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, uint64_t val)
Definition: yyjson.h:5343
yyjson_mut_obj_add_null
yyjson_api_inline bool yyjson_mut_obj_add_null(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:5310
yyjson_mut_obj_add_true
yyjson_api_inline bool yyjson_mut_obj_add_true(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:5318
yyjson_mut_obj_add_str
yyjson_api_inline bool yyjson_mut_obj_add_str(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *val)
Definition: yyjson.h:5383
yyjson_mut_obj_add_real
yyjson_api_inline bool yyjson_mut_obj_add_real(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, double val)
Definition: yyjson.h:5373
yyjson_mut_obj_add_bool
yyjson_api_inline bool yyjson_mut_obj_add_bool(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, bool val)
Definition: yyjson.h:5334
yyjson_mut_obj_add_strcpy
yyjson_api_inline bool yyjson_mut_obj_add_strcpy(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *val)
Definition: yyjson.h:5406

Removes all key-value pairs for the given key.
Note that this function takes a linear search time.

bool yyjson_mut_obj_remove_str(yyjson_mut_val *obj, const char *key);
bool yyjson_mut_obj_remove_strn(yyjson_mut_val *obj, const char *key, size_t len);
yyjson_mut_obj_remove_str
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove_str(yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:5442
yyjson_mut_obj_remove_strn
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove_strn(yyjson_mut_val *obj, const char *key, size_t len)
Definition: yyjson.h:5447

## JSON Merge Patch

Creates and returns a merge-patched JSON value (RFC 7386). Returns NULL if the patch could not be applied. Specification and example: https://tools.ietf.org/html/rfc7386

yyjson_mut_val *yyjson_merge_patch(yyjson_mut_doc *doc,
yyjson_val *orig,
yyjson_val *patch);
yyjson_merge_patch
yyjson_api yyjson_mut_val * yyjson_merge_patch(yyjson_mut_doc *doc, yyjson_val *orig, yyjson_val *patch)

# Number Processing

## Number reader

yyjson has a built-in high-performance number reader,
it will parse numbers according to these rules by default:

- Read positive integer as `uint64_t`, if overflow, convert to `double`.
- Read negative integer as `int64_t`, if overflow, convert to `double`.
- Read floating-point number as `double` with correct rounding (no ulp error).
- If a `real` number overflow (infinity), it will report an error.
- If a number does not match the JSON standard, it will report an error.

You can use `YYJSON_READ_ALLOW_INF_AND_NAN` flag to allow `nan` and `inf` number/literal, see `reader flag` for details.

## Number writer

yyjson has a built-in high-performance number writer,
it will write numbers according to these rules by default:

- Write positive integer without sign.
- Write negative integer with a negative sign.
- Write floating-point number with ECMAScript format, but with the following changes:
  - If number is `Infinity` or `NaN`, report an error.
  - Keep the negative sign of 0.0 to preserve input information.
  - Remove positive sign of exponent part.
- Floating-point number writer should generate shortest correctly rounded decimal representation.

You can use `YYJSON_WRITE_ALLOW_INF_AND_NAN` flag to write inf/nan number as `Infinity` and `NaN` literals without error, but this is not standard JSON, see `writer flag` for details.

You can also use `YYJSON_WRITE_INF_AND_NAN_AS_NULL` to write inf/nan number as `null` without error.

# Text Processing

## Character Encoding

yyjson only supports UTF-8 encoding without BOM, as specified in RFC 8259:

> ‍JSON text exchanged between systems that are not part of a closed ecosystem MUST be encoded using UTF-8. Implementations MUST NOT add a byte order mark (U+FEFF) to the beginning of a networked-transmitted JSON text.

By default, yyjson performs a strict UTF-8 encoding validation on input strings. An error will be reported when an invalid character is encountered.

You could use `YYJSON_READ_ALLOW_INVALID_UNICODE` and `YYJSON_WRITE_ALLOW_INVALID_UNICODE` flag to allow invalid unicode encoding. However, you should be aware that the result value from yyjson may contain invalid characters, which can be used by other code and may pose security risks.

## NUL Character

yyjson supports the `NUL` character (also known as `null terminator`, or Unicode `U+0000`, ASCII `\0`).

When reading JSON, `\u0000` will be unescaped to `NUL`. If a string contains `NUL`, the length obtained with strlen() will be inaccurate, and you should use yyjson_get_len() to get the real length.

When building JSON, the input string is treated as null-terminated. If you need to pass in a string with `NUL` inside, you should use the API with the `n` suffix and pass in the real length.

For example:

// null-terminated string
yyjson_mut_str(doc, str);
yyjson_obj_get(obj, str);
// any string, with or without null terminator
yyjson_mut_strn(doc, str, len);
yyjson_obj_getn(obj, str, len);
// C++ string
std::string sstr = ...;
yyjson_obj_getn(obj, sstr.data(), sstr.length());

# Memory Allocator

yyjson does not call libc's memory allocation functions (malloc/realloc/free) directly. When memory allocation is required, yyjson's API takes a parameter named `alc` that allows the caller to pass in an allocator. If the `alc` is NULL, yyjson will use the default memory allocator, which is a simple wrapper of libc's functions.

Custom memory allocator allows you to take more control over memory allocation, here are a few examples:

## Single allocator for multiple JSON

If you need to parse multiple small JSON, you can use a single allocator with pre-allocated buffer to avoid frequent memory allocation.

Sample code:

// max data size for single JSON
size_t max_json_size = 64 * 1024;
// calculate the max memory usage for a single JSON
size_t buf_size = yyjson_read_max_memory_usage(max_json_size, 0);
// create a buffer for allocator
void *buf = malloc(buf_size);
// setup the allocator with buffer
yyjson_alc alc;
yyjson_alc_pool_init(&alc, buf, buf_size);
// read multiple JSON with single allocator
for(int i = 0, i < your_json_file_count; i++) {
const char *your_json_file_path = ...;
yyjson_doc *doc = yyjson_read_file(your_json_file_path, 0, &alc, NULL);
...
yyjson_doc_free(doc);
}
// free the buffer
free(buf);
yyjson_read_max_memory_usage
yyjson_api_inline size_t yyjson_read_max_memory_usage(size_t len, yyjson_read_flag flg)
Definition: yyjson.h:782

## Stack memory allocator

If the JSON is small enough, you can use stack memory to read or write it.

Sample code:

char buf[128 * 1024]; // stack buffer
yyjson_alc alc;
yyjson_alc_pool_init(&alc, buf, sizeof(buf));
yyjson_doc *doc = yyjson_read_opts(dat, len, 0, &alc, NULL);
...
yyjson_doc_free(doc); // this is optional, as the memory is on stack

## Use third-party allocator library

You can use a third-party high-performance memory allocator for yyjson,
such as jemalloc, tcmalloc, mimalloc.

Sample code:

// Use https://github.com/microsoft/mimalloc
#include <mimalloc.h>
static void *priv_malloc(void *ctx, size_t size) {
return mi_malloc(size);
}
static void *priv_realloc(void *ctx, void *ptr, size_t size) {
return mi_realloc(ptr, size);
}
static void priv_free(void *ctx, void *ptr) {
mi_free(ptr);
}
static const yyjson_alc PRIV_ALC = {
priv_malloc,
priv_realloc,
priv_free,
NULL
};
// Read with custom allocator
yyjson_doc *doc = yyjson_doc_read_opts(dat, len, 0, &PRIV_ALC, NULL);
...
yyjson_doc_free(doc);
// Write with custom allocator
yyjson_alc *alc = &PRIV_ALC;
char *json = yyjson_doc_write(doc, 0, alc, NULL, NULL);
...
alc->free(alc->ctx, json);

# Null Check

yyjson's public API will do `null check` for every input parameters to avoid crashes.

For example, when reading a JSON, you don't need to do null check or type check on each value:

yyjson_doc *doc = yyjson_read(NULL, 0, 0); // doc is NULL
yyjson_val *val = yyjson_doc_get_root(doc); // val is NULL
const char *str = yyjson_get_str(val); // str is NULL
if (!str) printf("err!");
yyjson_doc_free(doc); // do nothing

But if you are sure that a value is non-null, and the type is matched, you can use the `unsafe` prefix API to avoid the null check.

For example, when iterating over an array or object, the value and key must be non-null:

size_t idx, max;
yyjson_val *key, *val;
yyjson_obj_foreach(obj, idx, max, key, val) {
// this is a valid JSON, so the key must be a non-null string
if (unsafe_yyjson_equals_str(key, "id") &&
unsafe_yyjson_is_uint(val) &&
unsafe_yyjson_get_uint(val) == 1234) {
// found
}
}

# Thread Safe

yyjson does not use global variables, so if you can ensure that the input parameters of a function are immutable, then the function call is thread-safe.

`yyjson_doc` and `yyjson_val` is immutable and thread-safe,
`yyjson_mut_doc` and `yyjson_mut_val` is mutable and not thread-safe.

# Locale Dependent

yyjson is locale-independent.

However, there are some special conditions that you need to be aware of:

1. You use libc's `setlocale()` function to change locale.
2. Your environment does not use IEEE 754 floating-point (e.g. some IBM mainframes) or you explicitly specified the `YYJSON_DISABLE_FAST_FP_CONV` flag at build time.

When you meet both of these conditions, you should avoid call `setlocale()` while other thread is parsing JSON, otherwise an error may be returned for JSON floating point number parsing.