lib/yyjson-0.12.0/doc/doxygen/html/api.html
| yyjson 0.12.0
A high performance C JSON library. |
Loading...
Searching...
No Matches
API
This document contains all the API usage and examples for the yyjson library.
All public functions and structs are prefixed with yyjson_, and all constants are prefixed with YYJSON_.
The library have 2 types of data structures: immutable and mutable:
| Immutable | Mutable | |
|---|---|---|
| Document | yyjson_doc | yyjson_mut_doc |
| Value | yyjson_val | yyjson_mut_val |
When reading a JSON, yyjson returns immutable documents and values.
When building a JSON, yyjson creates mutable documents and values.
The document holds the 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](yyjson_8h.html#structyyjson mut doc) *doc, ...);
bool yyjson_is_str(yyjson_val *val);
bool yyjson_mut_is_str([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val);
yyjson_api_inline bool yyjson_is_str(yyjson_val *val)
Definition yyjson.h:5185
yyjson_api_inline char * yyjson_mut_write(const yyjson_mut_doc *doc, yyjson_write_flag flg, size_t *len)
Definition yyjson.h:1461
yyjson_api_inline char * yyjson_write(const yyjson_doc *doc, yyjson_write_flag flg, size_t *len)
Definition yyjson.h:1356
yyjson_api_inline bool yyjson_mut_is_str(yyjson_mut_val *val)
Definition yyjson.h:5756
Definition yyjson.h:4770
[yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc)
Definition yyjson.h:5638
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val)
Definition yyjson.h:5590
Definition yyjson.h:4765
The library also provides some functions to convert values between immutable and mutable:
// doc -> mut_doc
[yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *yyjson_doc_mut_copy(yyjson_doc *doc, ...);
// val -> mut_val
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_val_mut_copy(yyjson_val *val, ...);
// mut_doc -> doc
yyjson_doc *yyjson_mut_doc_imut_copy(yyjson_mut_doc *doc, ...);
// mut_val -> val
yyjson_doc *yyjson_mut_val_imut_copy(yyjson_mut_val *val, ...);
yyjson_api yyjson_mut_val * yyjson_val_mut_copy(yyjson_mut_doc *doc, yyjson_val *val)
yyjson_api yyjson_mut_doc * yyjson_doc_mut_copy(yyjson_doc *doc, const yyjson_alc *alc)
yyjson_api yyjson_doc * yyjson_mut_doc_imut_copy(yyjson_mut_doc *doc, const yyjson_alc *alc)
yyjson_api yyjson_doc * yyjson_mut_val_imut_copy(yyjson_mut_val *val, const yyjson_alc *alc)
The library supports strings with or without null-terminator ('\0').
When you need to use a string without a null-terminator or when you explicitly know the length of the string, you can use the function that ends with n, for example:
// null-terminator is required
bool yyjson_equals_str(yyjson_val *val, const char *str);
// null-terminator is optional
bool yyjson_equals_strn(yyjson_val *val, const char *str, size_t len);
yyjson_api_inline bool yyjson_equals_str(yyjson_val *val, const char *str)
Definition yyjson.h:5272
yyjson_api_inline bool yyjson_equals_strn(yyjson_val *val, const char *str, size_t len)
Definition yyjson.h:5280
When creating JSON, yyjson treats strings as constants for better performance. However, if 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_8h.html#structyyjson mut val) *yyjson_mut_str([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *str);
// reference only, null-terminator is optional
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_strn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *str, size_t len);
// copied, null-terminated is required
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_strcpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *str);
// copied, null-terminator is optional
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_strncpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *str, size_t len);
yyjson_api_inline yyjson_mut_val * yyjson_mut_strn(yyjson_mut_doc *doc, const char *str, size_t len)
Definition yyjson.h:6060
yyjson_api_inline yyjson_mut_val * yyjson_mut_strncpy(yyjson_mut_doc *doc, const char *str, size_t len)
Definition yyjson.h:6079
yyjson_api_inline yyjson_mut_val * yyjson_mut_strcpy(yyjson_mut_doc *doc, const char *str)
Definition yyjson.h:6066
yyjson_api_inline yyjson_mut_val * yyjson_mut_str(yyjson_mut_doc *doc, const char *str)
Definition yyjson.h:6055
The library provides 5 functions for reading JSON.
Each function accepts an input of UTF-8 data or a file,
returns a document if it successful or NULL if it fails.
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);
uint32_t yyjson_read_flag
Definition yyjson.h:723
yyjson_api_inline yyjson_doc * yyjson_read(const char *dat, size_t len, yyjson_read_flag flg)
Definition yyjson.h:983
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_api_inline void yyjson_doc_free(yyjson_doc *doc)
Definition yyjson.h:5130
The path is JSON file path. This should be a null-terminated string using the system's native encoding.
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,
const yyjson_alc *alc,
[yyjson_read_err](yyjson_8h.html#structyyjson read err) *err);
yyjson_api yyjson_doc * yyjson_read_file(const char *path, yyjson_read_flag flg, const yyjson_alc *alc, yyjson_read_err *err)
Definition yyjson.h:586
[yyjson_read_err](yyjson_8h.html#structyyjson read err)
Definition yyjson.h:879
Sample code:
yyjson_doc *doc = yyjson_read_file("/tmp/test.json", 0, NULL, NULL);
if (doc) {...}
yyjson_doc_free(doc);
The fp is file pointer. The data will be read from the current position of the FILE to the end.
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_fp(FILE *fp,
yyjson_read_flag flg,
const yyjson_alc *alc,
[yyjson_read_err](yyjson_8h.html#structyyjson read err) *err);
yyjson_api yyjson_doc * yyjson_read_fp(FILE *fp, yyjson_read_flag flg, const yyjson_alc *alc, yyjson_read_err *err)
Sample code:
FILE *fp = fdopen(fd, "rb"); // POSIX file descriptor (fd)
yyjson_doc *doc = yyjson_read_fp(fp, 0, NULL, NULL);
if (fp) fclose(fp);
if (doc) {...}
yyjson_doc_free(doc);
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,
const yyjson_alc *alc,
[yyjson_read_err](yyjson_8h.html#structyyjson read err) *err);
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_doc *doc = yyjson_read_opts((char *)dat, len, flg, NULL, NULL);
if (doc) {...}
yyjson_doc_free(doc);
static const yyjson_read_flag YYJSON_READ_ALLOW_INF_AND_NAN
Definition yyjson.h:757
static const yyjson_read_flag YYJSON_READ_ALLOW_COMMENTS
Definition yyjson.h:753
Reading a very large JSON document can freeze the program for a short while. If this is not acceptable, incremental reading can be used.
Incremental reading is recommended only for large documents and only when the program needs to be responsive. Incremental reading is slightly slower than yyjson_read() and yyjson_read_opts().
Note: The incremental JSON reader only supports standard JSON. Flags for non-standard features (e.g. comments, trailing commas) are ignored.
To read a large JSON document incrementally:
yyjson_incr_new() to create the state for incremental reading.yyjson_incr_read() repeatedly.yyjson_incr_free() to free the state.The buf should be a UTF-8 string, null-terminator is not required. You can pass a const string if you don't use the YYJSON_READ_INSITU flag.
The buf_len is the length of buf 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 function returns a new state, or NULL if flg is invalid or if a memory allocation error occurs.
yyjson_incr_state *yyjson_incr_new(char *buf, size_t buf_len, yyjson_read_flag flg, const yyjson_alc *alc);
struct yyjson_incr_state yyjson_incr_state
Definition yyjson.h:996
yyjson_api yyjson_incr_state * yyjson_incr_new(char *buf, size_t buf_len, yyjson_read_flag flg, const yyjson_alc *alc)
Performs incremental read of up to len bytes.
The state for incremental reading is created using yyjson_incr_new().
The len is the maximum number of bytes to read, counting from the start of the JSON data.
The err is a pointer to receive the error information. Required.
The function returns a document object when the reading is complete and NULL otherwise. If err->code is set to YYJSON_READ_ERROR_MORE, it indicates that parsing is not yet complete. Then, increase len by some kilobytes and call this function again. Continue increasing len until len == buf_len (the total length of the input buffer) or until an error other than YYJSON_READ_ERROR_MORE is returned.
Note: Parsing in very small increments is not efficient. An increment of several kilobytes or megabytes is recommended.
yyjson_doc *yyjson_incr_read(yyjson_incr_state *state, size_t len, yyjson_read_err *err);
yyjson_api yyjson_doc * yyjson_incr_read(yyjson_incr_state *state, size_t len, yyjson_read_err *err)
Free the state created by yyjson_incr_new().
void yyjson_incr_free(yyjson_incr_state *state);
yyjson_api void yyjson_incr_free(yyjson_incr_state *state)
const char *dat = your_file.bytes;
size_t len = your_file.size;
yyjson_read_flag flg = YYJSON_READ_NOFLAG;
yyjson_incr_state *state = yyjson_incr_new(dat, len, flg, NULL);
yyjson_doc *doc;
[yyjson_read_err](yyjson_8h.html#structyyjson read err) err;
size_t read_so_far = 0;
do {
read_so_far += 100000;
if (read_so_far > len)
read_so_far = len;
doc = yyjson_incr_read(state, read_so_far, &err);
if (err.code != YYJSON_READ_ERROR_MORE)
break;
} while (read_so_far < len);
yyjson_incr_free(state);
if (doc != NULL) { ... }
yyjson_doc_free(doc);
static const yyjson_read_code YYJSON_READ_ERROR_MORE
Definition yyjson.h:876
yyjson_read_code code
Definition yyjson.h:881
static const yyjson_read_flag YYJSON_READ_NOFLAG
Definition yyjson.h:733
When reading JSON fails and you need error information, you can pass a yyjson_read_err pointer to the yyjson_read_xxx() functions to receive the error details.
Sample code:
char *dat = ...;
size_t dat_len = ...;
[yyjson_read_err](yyjson_8h.html#structyyjson read err) err;
yyjson_doc *doc = yyjson_read_opts(dat, dat_len, 0, NULL, &err);
if (!doc) {
printf("read error: %s, code: %u at byte position: %lu\n",
// printed:
// read error: trailing comma is not allowed, code: 7, at byte position: 40
}
yyjson_doc_free(doc);
size_t pos
Definition yyjson.h:885
const char * msg
Definition yyjson.h:883
The pos in the error information indicates the byte position where the error occurred. If you need the line and column number of the error, you can use the yyjson_locate_pos() function. Note that the line and column start from 1, while character starts from 0. All values are calculated based on Unicode characters to ensure compatibility with various text editors.
Sample code:
char *dat = ...;
size_t dat_len = ...;
[yyjson_read_err](yyjson_8h.html#structyyjson read err) err = ...;
size_t line, col, chr;
if (yyjson_locate_pos(dat, dat_len, err.pos, &line, &col, &chr)) {
printf("error at line: %lu, column: %lu, character index: %lu\n",
line, col, chr);
// printed:
// error at line: 3, column: 5, character index: 32
}
yyjson_api bool yyjson_locate_pos(const char *str, size_t len, size_t pos, size_t *line, size_t *col, size_t *chr)
The library provides a set of flags for JSON reader.
You can use a single flag, or combine multiple flags with bitwise | operator.
Non-standard flags (such as YYJSON_READ_JSON5) have no performance impact when reading standard JSON input.
This is the default flag for JSON reader (RFC-8259 or ECMA-404 compliant):
uint64_t.int64_t.double with correct rounding.uint64_t or int64_t as double.Inf and NaN literals.Read the input data in-situ.
This option allows the reader to modify and use the input data to store string values, which can slightly improve reading speed. However, the caller must ensure that the input data is held until the document is freed. The input data must be padded with at least YYJSON_PADDING_SIZE bytes. For example: [1,2] should be [1,2]\0\0\0\0, input length should be 5.
Sample code:
size_t dat_len = ...;
char *buf = malloc(dat_len + YYJSON_PADDING_SIZE); // create a buffer larger than (len + 4)
read_from_socket(buf, ...);
memset(buf + file_size, 0, YYJSON_PADDING_SIZE); // 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.
static const yyjson_read_flag YYJSON_READ_INSITU
Definition yyjson.h:741
#define YYJSON_PADDING_SIZE
Definition yyjson.h:572
Stop parsing when reaching the end of a JSON document instead of issues an error if there's additional content after it.
This option is useful for parsing small pieces of JSON within 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_api_inline size_t yyjson_doc_get_read_size(yyjson_doc *doc)
Definition yyjson.h:5122
static const yyjson_read_flag YYJSON_READ_STOP_WHEN_DONE
Definition yyjson.h:746
Allow a single trailing comma at the end of an object or array (non-standard), for example:
{
"a": 1,
"b": 2,
}
[
"a",
"b",
]
Allow C-style single-line and multi-line comments (non-standard), for example:
{
"name": "Harry", // single-line comment
"id": /* multi-line comment */ 123
}
Allow nan/inf number or case-insensitive literal (non-standard), for example:
{
"large": 123e999,
"nan1": NaN,
"nan2": nan,
"inf1": Inf,
"inf2": -Infinity
}
Read all numbers as raw strings without parsing.
This flag is useful if you want to handle number parsing yourself. You can use the following 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_api_inline bool yyjson_is_raw(yyjson_val *val)
Definition yyjson.h:5145
yyjson_api_inline const char * yyjson_get_raw(yyjson_val *val)
Definition yyjson.h:5236
yyjson_api_inline size_t yyjson_get_len(yyjson_val *val)
Definition yyjson.h:5268
Read big numbers as raw strings.
This flag is useful if you want to parse these big numbers yourself. These big numbers include integers that cannot be represented by int64_t and uint64_t, and floating-point numbers that cannot be represented by finite double.
Note that this flag will be overridden by YYJSON_READ_NUMBER_AS_RAW flag.
Allow reading invalid unicode when parsing string values (non-standard), for example:
"\x80xyz"
"\xF0\x81\x81\x81"
This flag permits invalid characters to appear in the string values, but it still reports errors for invalid escape sequences. It does not impact the performance of correctly encoded strings.
_ Warning _: when using this option, be aware that strings within JSON values may contain incorrect encoding, so you need to handle these strings carefully to avoid security risks.
Allow UTF-8 BOM and skip it before parsing if any (non-standard).
Allow extended number formats (non-standard):
0x7B..123, 123..+123.Allow extended escape sequences in strings (non-standard):
\a, \e, \v, \', \?, \0.\xNN, such as \x7B.\1-\9 will still trigger an error.Allow extended whitespace characters (non-standard):
\v and form feed \f.\u2028 and paragraph separator \u2029.\xA0.\uFEFF.Allow strings enclosed in single quotes (non-standard), such as 'ab'.
Allow object keys without quotes (non-standard), such as {a:1,b:2}. This extends the ECMAScript IdentifierName rule by allowing any non-whitespace character with code point above U+007F.
Allow JSON5 format, see: https://json5.org.
This flag supports all JSON5 features with some additional extensions:
\a, \e).NaN, Inf and Infinity literals.For example:
{
/* JSON5 example */
id: 123,
name: 'Harry',
color: 0x66CCFF,
min: .001,
max: Inf,
data: '\x00\xAA\xFF',
}
The library provides 4 sets of functions for writing JSON.
Each function accepts an input of JSON document or root value, and returns a UTF-8 string or file.
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 (not including the null-terminator), 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.
// doc -> str
char *yyjson_write(const yyjson_doc *doc, yyjson_write_flag flg, size_t *len);
// mut_doc -> str
char *yyjson_mut_write(const [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, yyjson_write_flag flg, size_t *len);
// val -> str
char *yyjson_val_write(const yyjson_val *val, yyjson_write_flag flg, size_t *len);
// mut_val -> str
char *yyjson_mut_val_write(const [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, yyjson_write_flag flg, size_t *len);
yyjson_api_inline char * yyjson_val_write(const yyjson_val *val, yyjson_write_flag flg, size_t *len)
Definition yyjson.h:1567
yyjson_api_inline char * yyjson_mut_val_write(const yyjson_mut_val *val, yyjson_write_flag flg, size_t *len)
Definition yyjson.h:1670
uint32_t yyjson_write_flag
Definition yyjson.h:1155
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);
static const yyjson_write_flag YYJSON_WRITE_PRETTY
Definition yyjson.h:1165
Sample code 2:
[yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc = yyjson_mut_doc_new(NULL);
[yyjson_mut_val](yyjson_8h.html#structyyjson 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_api_inline void yyjson_mut_doc_set_root(yyjson_mut_doc *doc, yyjson_mut_val *root)
Definition yyjson.h:5705
yyjson_api_inline bool yyjson_mut_arr_add_int(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num)
Definition yyjson.h:6646
yyjson_api yyjson_mut_doc * yyjson_mut_doc_new(const yyjson_alc *alc)
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr(yyjson_mut_doc *doc)
Definition yyjson.h:6194
The path is output JSON file path. This should be a null-terminated string using the system's native encoding. 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.
// doc -> file
bool yyjson_write_file(const char *path, const yyjson_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, [yyjson_write_err](yyjson_8h.html#structyyjson write err) *err);
// mut_doc -> file
bool yyjson_mut_write_file(const char *path, const [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err);
// val -> file
bool yyjson_val_write_file(const char *path, const yyjson_val *val, yyjson_write_flag flg, const yyjson_alc *alc, [yyjson_write_err](yyjson_8h.html#structyyjson write err) *err);
// mut_val -> file
bool yyjson_mut_val_write_file(const char *path, const [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err);
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_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_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_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](yyjson_8h.html#structyyjson write err)
Definition yyjson.h:1247
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");
The fp is output file pointer, The data will be written to the current position of the file.
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.
// doc -> file
bool yyjson_write_fp(FILE *fp, const yyjson_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, [yyjson_write_err](yyjson_8h.html#structyyjson write err) *err);
// mut_doc -> file
bool yyjson_mut_write_fp(FILE *fp, const [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err);
// val -> file
bool yyjson_val_write_fp(FILE *fp, const yyjson_val *val, yyjson_write_flag flg, const yyjson_alc *alc, [yyjson_write_err](yyjson_8h.html#structyyjson write err) *err);
// mut_val -> file
bool yyjson_mut_val_write_fp(FILE *fp, const [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err);
yyjson_api bool yyjson_write_fp(FILE *fp, const yyjson_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_api bool yyjson_val_write_fp(FILE *fp, const yyjson_val *val, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_api bool yyjson_mut_write_fp(FILE *fp, const yyjson_mut_doc *doc, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
yyjson_api bool yyjson_mut_val_write_fp(FILE *fp, const yyjson_mut_val *val, yyjson_write_flag flg, const yyjson_alc *alc, yyjson_write_err *err)
Sample code:
FILE *fp = fdopen(fd, "wb"); // POSIX file descriptor (fd)
bool suc = yyjson_write_fp(fp, doc, YYJSON_WRITE_PRETTY, NULL, NULL);
if (fp) fclose(fp);
if (suc) printf("OK");
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 (not including the null-terminator), 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](yyjson_8h.html#structyyjson write err) *err);
char *yyjson_mut_write_opts(const [yyjson_mut_doc](yyjson_8h.html#structyyjson 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](yyjson_8h.html#structyyjson write err) *err);
char *yyjson_mut_val_write_opts(const [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, yyjson_write_flag flg, const yyjson_alc *alc, size_t *len, yyjson_write_err *err);
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_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_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_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](yyjson_8h.html#structyyjson 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);
}
void(* free)(void *ctx, void *ptr)
Definition yyjson.h:592
const char * msg
Definition yyjson.h:1251
yyjson_api bool yyjson_alc_pool_init(yyjson_alc *alc, void *buf, size_t size)
static const yyjson_write_flag YYJSON_WRITE_ESCAPE_UNICODE
Definition yyjson.h:1168
yyjson_write_code code
Definition yyjson.h:1249
void * ctx
Definition yyjson.h:594
The library provides a set of flags for JSON writer.
You can use a single flag, or combine multiple flags with bitwise | operator.
This is the default flag for JSON writer:
inf or nan number.Writes JSON with a pretty format uing a 4-space indent.
Writes JSON with a pretty format uing a 2-space indent. This flag will override YYJSON_WRITE_PRETTY flag.
Escape unicode as \uXXXX, making the output ASCII-only, for example:
["Alizée, 😊"]
["Aliz\u00E9e, \uD83D\uDE0A"]
Escapes the forward slash character / as \/, for example:
Writes inf/nan numbers as Infinity and NaN literals instead of reporting errors.
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}
Writes inf/nan numbers as null literals instead of reporting errors.
This flag will override YYJSON_WRITE_ALLOW_INF_AND_NAN flag, for example:
{"not_a_number":null,"large_number":null}
Allows invalid unicode when encoding string values.
Invalid characters within string values will be copied byte by byte. If YYJSON_WRITE_ESCAPE_UNICODE flag is also set, invalid characters will be escaped as \uFFFD (replacement character).
This flag does not affect the performance of correctly encoded string.
Adds a newline character \n at the end of the JSON. This can be helpful for text editors or NDJSON.
Write floating-point numbers using single-precision (float). This casts double to float before serialization. This will produce shorter output, but may lose some precision. This flag is ignored if YYJSON_WRITE_FP_TO_FIXED(prec) is also used.
Write floating-point number using fixed-point notation. This is similar to ECMAScript Number.prototype.toFixed(prec), but with trailing zeros removed. The prec ranges from 1 to 15. This will produce shorter output but may lose some precision.
You can access the content of a document with the following functions:
// Get the root value of this JSON document.
yyjson_val *yyjson_doc_get_root(yyjson_doc *doc);
// Get how many bytes are read when parsing JSON.
// e.g. "[1,2,3]" returns 7.
size_t yyjson_doc_get_read_size(yyjson_doc *doc);
// Get total value count in this JSON document.
// e.g. "[1,2,3]" returns 4 (1 array and 3 numbers).
size_t yyjson_doc_get_val_count(yyjson_doc *doc);
yyjson_api_inline size_t yyjson_doc_get_val_count(yyjson_doc *doc)
Definition yyjson.h:5126
yyjson_api_inline yyjson_val * yyjson_doc_get_root(yyjson_doc *doc)
Definition yyjson.h:5118
A document holds all the memory for its internal values and strings. When you no longer need it, you should release the document and free up all the memory:
// Free the document; if NULL is passed in, do nothing.
void yyjson_doc_free(yyjson_doc *doc);
Each JSON Value has a type and subtype, as specified in the table:
| Type | Subtype | |
|---|---|---|
| YYJSON_TYPE_NONE | Invalid value | |
| YYJSON_TYPE_RAW | Raw string | |
| YYJSON_TYPE_NULL | null literal | |
| YYJSON_TYPE_BOOL | YYJSON_SUBTYPE_FALSE | false literal |
| YYJSON_TYPE_BOOL | YYJSON_SUBTYPE_TRUE | true literal |
| YYJSON_TYPE_NUM | YYJSON_SUBTYPE_UINT | uint64_t nummer |
| YYJSON_TYPE_NUM | YYJSON_SUBTYPE_SINT | int64_t number |
| YYJSON_TYPE_NUM | YYJSON_SUBTYPE_REAL | double number |
| YYJSON_TYPE_STR | String value | |
| YYJSON_TYPE_STR | YYJSON_SUBTYPE_NOESC | String value, no-escape |
| YYJSON_TYPE_ARR | Array value | |
| YYJSON_TYPE_OBJ | Object value |
YYJSON_TYPE_NONE means invalid value, it does not appear when the JSON is successfully parsed.YYJSON_TYPE_RAW only appears when the corresponding flag YYJSON_READ_XXX_AS_RAW is used.YYJSON_SUBTYPE_NOESC is used to optimize the writing speed of strings that do not need to be escaped. This subtype is used internally, and the user does not need to handle it.The following functions can be used to determine the type of a JSON value.
// Returns the type and subtype of a JSON value.
// Returns 0 if the input is NULL.
yyjson_type yyjson_get_type(yyjson_val *val);
yyjson_subtype yyjson_get_subtype(yyjson_val *val);
// Returns value's tag, see Data Structures doc for details.
uint8_t yyjson_get_tag(yyjson_val *val);
// returns type description, such as:
// "null", "string", "array", "object", "true", "false",
// "uint", "sint", "real", "unknown"
const char *yyjson_get_type_desc(yyjson_val *val);
// Returns true if the JSON value is specified type.
// Returns false if the input is NULL or not the specified type.
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/false
bool yyjson_is_uint(yyjson_val *val); // uint64_t
bool yyjson_is_sint(yyjson_val *val); // int64_t
bool yyjson_is_int(yyjson_val *val); // uint64_t/int64_t
bool yyjson_is_real(yyjson_val *val); // double
bool yyjson_is_num(yyjson_val *val); // uint64_t/int64_t/double
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/object
bool yyjson_is_raw(yyjson_val *val); // raw string
uint8_t yyjson_subtype
Definition yyjson.h:538
yyjson_api_inline bool yyjson_is_ctn(yyjson_val *val)
Definition yyjson.h:5197
yyjson_api_inline uint8_t yyjson_get_tag(yyjson_val *val)
Definition yyjson.h:5215
yyjson_api_inline bool yyjson_is_bool(yyjson_val *val)
Definition yyjson.h:5161
yyjson_api_inline bool yyjson_is_real(yyjson_val *val)
Definition yyjson.h:5177
yyjson_api_inline const char * yyjson_get_type_desc(yyjson_val *val)
Definition yyjson.h:5219
uint8_t yyjson_type
Definition yyjson.h:519
yyjson_api_inline bool yyjson_is_int(yyjson_val *val)
Definition yyjson.h:5173
yyjson_api_inline bool yyjson_is_true(yyjson_val *val)
Definition yyjson.h:5153
yyjson_api_inline bool yyjson_is_false(yyjson_val *val)
Definition yyjson.h:5157
yyjson_api_inline yyjson_subtype yyjson_get_subtype(yyjson_val *val)
Definition yyjson.h:5211
yyjson_api_inline yyjson_type yyjson_get_type(yyjson_val *val)
Definition yyjson.h:5207
yyjson_api_inline bool yyjson_is_null(yyjson_val *val)
Definition yyjson.h:5149
yyjson_api_inline bool yyjson_is_sint(yyjson_val *val)
Definition yyjson.h:5169
yyjson_api_inline bool yyjson_is_uint(yyjson_val *val)
Definition yyjson.h:5165
yyjson_api_inline bool yyjson_is_arr(yyjson_val *val)
Definition yyjson.h:5189
yyjson_api_inline bool yyjson_is_num(yyjson_val *val)
Definition yyjson.h:5181
yyjson_api_inline bool yyjson_is_obj(yyjson_val *val)
Definition yyjson.h:5193
The following functions can be used to get the contents of the JSON value.
// Returns the raw string, or NULL if val is not raw type.
const char *yyjson_get_raw(yyjson_val *val);
// Returns bool value, or false if val is not bool type.
bool yyjson_get_bool(yyjson_val *val);
// Returns uint64_t value, or 0 if val is not uint type.
uint64_t yyjson_get_uint(yyjson_val *val);
// Returns int64_t value, or 0 if val is not sint type.
int64_t yyjson_get_sint(yyjson_val *val);
// Returns int value (may overflow), or 0 if val is not uint/sint type.
int yyjson_get_int(yyjson_val *val);
// Returns double value, or 0 if val is not real type.
double yyjson_get_real(yyjson_val *val);
// Returns double value (typecast), or 0 if val is not uint/sint/real type.
double yyjson_get_num(yyjson_val *val);
// Returns the string value, or NULL if val is not string type.
const char *yyjson_get_str(yyjson_val *val);
// Returns the content length (string length in bytes, array size,
// object size), or 0 if the value does not contains length data.
size_t yyjson_get_len(yyjson_val *val);
// Returns whether the value is equals to a string.
// Returns false if input is NULL or val is not string.
bool yyjson_equals_str(yyjson_val *val, const char *str);
bool yyjson_equals_strn(yyjson_val *val, const char *str, size_t len);
yyjson_api_inline int yyjson_get_int(yyjson_val *val)
Definition yyjson.h:5252
yyjson_api_inline double yyjson_get_real(yyjson_val *val)
Definition yyjson.h:5256
yyjson_api_inline const char * yyjson_get_str(yyjson_val *val)
Definition yyjson.h:5264
yyjson_api_inline bool yyjson_get_bool(yyjson_val *val)
Definition yyjson.h:5240
yyjson_api_inline uint64_t yyjson_get_uint(yyjson_val *val)
Definition yyjson.h:5244
yyjson_api_inline double yyjson_get_num(yyjson_val *val)
Definition yyjson.h:5260
yyjson_api_inline int64_t yyjson_get_sint(yyjson_val *val)
Definition yyjson.h:5248
The following functions can be used to modify the content of a JSON value.
Warning: For immutable documents, these functions will break the immutable convention, you should use this set of APIs with caution (e.g. make sure the document is only accessed in a single thread).
// Set the value to new type and content.
// Returns false if input is NULL or val is object or array.
bool yyjson_set_raw(yyjson_val *val, const char *raw, size_t len);
bool yyjson_set_null(yyjson_val *val);
bool yyjson_set_bool(yyjson_val *val, bool num);
bool yyjson_set_uint(yyjson_val *val, uint64_t num);
bool yyjson_set_sint(yyjson_val *val, int64_t num);
bool yyjson_set_int(yyjson_val *val, int num);
bool yyjson_set_float(yyjson_val *val, float num);
bool yyjson_set_double(yyjson_val *val, double num);
bool yyjson_set_real(yyjson_val *val, double num);
// The string is not copied, should be held by caller.
bool yyjson_set_str(yyjson_val *val, const char *str);
bool yyjson_set_strn(yyjson_val *val, const char *str, size_t len);
yyjson_api_inline bool yyjson_set_null(yyjson_val *val)
Definition yyjson.h:5303
yyjson_api_inline bool yyjson_set_raw(yyjson_val *val, const char *raw, size_t len)
Definition yyjson.h:5296
yyjson_api_inline bool yyjson_set_uint(yyjson_val *val, uint64_t num)
Definition yyjson.h:5315
yyjson_api_inline bool yyjson_set_str(yyjson_val *val, const char *str)
Definition yyjson.h:5363
yyjson_api_inline bool yyjson_set_strn(yyjson_val *val, const char *str, size_t len)
Definition yyjson.h:5370
yyjson_api_inline bool yyjson_set_float(yyjson_val *val, float num)
Definition yyjson.h:5333
yyjson_api_inline bool yyjson_set_real(yyjson_val *val, double num)
Definition yyjson.h:5345
yyjson_api_inline bool yyjson_set_double(yyjson_val *val, double num)
Definition yyjson.h:5339
yyjson_api_inline bool yyjson_set_sint(yyjson_val *val, int64_t num)
Definition yyjson.h:5321
yyjson_api_inline bool yyjson_set_bool(yyjson_val *val, bool num)
Definition yyjson.h:5309
yyjson_api_inline bool yyjson_set_int(yyjson_val *val, int num)
Definition yyjson.h:5327
The following functions can be used to access a JSON array.
Note that accessing elements by index may take a linear search time. Therefore, if you need to iterate through an array, it is recommended to use the iterator API.
// Returns the number of elements in this array.
// Returns 0 if the input is not an array.
size_t yyjson_arr_size(yyjson_val *arr);
// Returns the element at the specified position (linear search time).
// Returns NULL if the index is out of bounds, or input is not an array.
yyjson_val *yyjson_arr_get(yyjson_val *arr, size_t idx);
// Returns the first element of this array (constant time).
// Returns NULL if array is empty or intput is not an array.
yyjson_val *yyjson_arr_get_first(yyjson_val *arr);
// Returns the last element of this array (linear search time).
// Returns NULL if array is empty or intput is not an array.
yyjson_val *yyjson_arr_get_last(yyjson_val *arr);
yyjson_api_inline size_t yyjson_arr_size(yyjson_val *arr)
Definition yyjson.h:5390
yyjson_api_inline yyjson_val * yyjson_arr_get_last(yyjson_val *arr)
Definition yyjson.h:5418
yyjson_api_inline yyjson_val * yyjson_arr_get(yyjson_val *arr, size_t idx)
Definition yyjson.h:5394
yyjson_api_inline yyjson_val * yyjson_arr_get_first(yyjson_val *arr)
Definition yyjson.h:5409
There are two ways to traverse an array:
Sample code 1 (iterator API):
yyjson_val *arr; // the array to be traversed
yyjson_val *val;
[yyjson_arr_iter](yyjson_8h.html#structyyjson arr iter) iter = yyjson_arr_iter_with(arr);
while ((val = yyjson_arr_iter_next(&iter))) {
your_func(val);
}
yyjson_api_inline yyjson_arr_iter yyjson_arr_iter_with(yyjson_val *arr)
Definition yyjson.h:5452
yyjson_api_inline yyjson_val * yyjson_arr_iter_next(yyjson_arr_iter *iter)
Definition yyjson.h:5462
[yyjson_arr_iter](yyjson_8h.html#structyyjson arr iter)
Definition yyjson.h:1990
Sample code 2 (foreach macro):
yyjson_val *arr; // the array to be traversed
size_t idx, max;
yyjson_val *val;
yyjson_arr_foreach(arr, idx, max, val) {
your_func(idx, val);
}
#define yyjson_arr_foreach(arr, idx, max, val)
Definition yyjson.h:2046
There's also mutable version API to traverse an mutable array:
Sample code 1 (mutable iterator API):
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr; // the array to be traversed
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val;
[yyjson_mut_arr_iter](yyjson_8h.html#structyyjson mut arr__iter) iter = yyjson_mut_arr_iter_with(arr);
while ((val = yyjson_mut_arr_iter_next(&iter))) {
if (your_val_is_unused(val)) {
// you can remove current value inside iteration
yyjson_mut_arr_iter_remove(&iter);
}
}
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_iter_remove(yyjson_mut_arr_iter *iter)
Definition yyjson.h:6171
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_iter_next(yyjson_mut_arr_iter *iter)
Definition yyjson.h:6159
yyjson_api_inline yyjson_mut_arr_iter yyjson_mut_arr_iter_with(yyjson_mut_val *arr)
Definition yyjson.h:6148
[yyjson_mut_arr_iter](yyjson_8h.html#structyyjson mut arr__iter)
Definition yyjson.h:2711
Sample code 2 (mutable foreach macro):
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr; // the array to be traversed
size_t idx, max;
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val;
yyjson_mut_arr_foreach(arr, idx, max, val) {
your_func(idx, val);
}
#define yyjson_mut_arr_foreach(arr, idx, max, val)
Definition yyjson.h:2781
The following functions can be used to access a JSON object.
Note that accessing elements by key may take a linear search time. Therefore, if you need to iterate through an object, it is recommended to use the iterator API.
// Returns the number of key-value pairs in this object.
// Returns 0 if input is not an object.
size_t yyjson_obj_size(yyjson_val *obj);
// Returns the value to which the specified key is mapped.
// Returns NULL if this object contains no mapping for the key.
yyjson_val *yyjson_obj_get(yyjson_val *obj, const char *key);
yyjson_val *yyjson_obj_getn(yyjson_val *obj, const char *key, size_t key_len);
// If the order of object's key is known at compile-time,
// you can use this method to avoid searching the entire object.
// e.g. { "x":1, "y":2, "z":3 }
yyjson_val *obj = ...;
[yyjson_obj_iter](yyjson_8h.html#structyyjson obj iter) iter = yyjson_obj_iter_with(obj);
yyjson_val *x = yyjson_obj_iter_get(&iter, "x");
yyjson_val *z = yyjson_obj_iter_get(&iter, "z");
yyjson_api_inline yyjson_val * yyjson_obj_get(yyjson_val *obj, const char *key)
Definition yyjson.h:5483
yyjson_api_inline yyjson_val * yyjson_obj_iter_get(yyjson_obj_iter *iter, const char *key)
Definition yyjson.h:5545
yyjson_api_inline yyjson_val * yyjson_obj_getn(yyjson_val *obj, const char *key, size_t key_len)
Definition yyjson.h:5488
yyjson_api_inline yyjson_obj_iter yyjson_obj_iter_with(yyjson_val *obj)
Definition yyjson.h:5521
yyjson_api_inline size_t yyjson_obj_size(yyjson_val *obj)
Definition yyjson.h:5479
[yyjson_obj_iter](yyjson_8h.html#structyyjson obj iter)
Definition yyjson.h:2114
There are two ways to traverse an object:
Sample code 1 (iterator API):
yyjson_val *obj; // the object to be traversed
yyjson_val *key, *val;
[yyjson_obj_iter](yyjson_8h.html#structyyjson obj iter) iter = yyjson_obj_iter_with(obj);
while ((key = yyjson_obj_iter_next(&iter))) {
val = yyjson_obj_iter_get_val(key);
your_func(key, val);
}
yyjson_api_inline yyjson_val * yyjson_obj_iter_get_val(yyjson_val *key)
Definition yyjson.h:5541
yyjson_api_inline yyjson_val * yyjson_obj_iter_next(yyjson_obj_iter *iter)
Definition yyjson.h:5531
Sample code 2 (foreach macro):
yyjson_val *obj; // this is your object
size_t idx, max;
yyjson_val *key, *val;
yyjson_obj_foreach(obj, idx, max, key, val) {
your_func(key, val);
}
#define yyjson_obj_foreach(obj, idx, max, key, val)
Definition yyjson.h:2217
There's also mutable version API to traverse an mutable object:
Sample code 1 (mutable iterator API):
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj; // the object to be traversed
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *key, *val;
[yyjson_mut_obj_iter](yyjson_8h.html#structyyjson mut obj__iter) iter = yyjson_mut_obj_iter_with(obj);
while ((key = yyjson_mut_obj_iter_next(&iter))) {
val = yyjson_mut_obj_iter_get_val(key);
if (your_key_is_unused(key)) {
// you can remove current kv pair inside iteration
yyjson_mut_obj_iter_remove(&iter);
}
}
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_next(yyjson_mut_obj_iter *iter)
Definition yyjson.h:6804
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_remove(yyjson_mut_obj_iter *iter)
Definition yyjson.h:6821
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_get_val(yyjson_mut_val *key)
Definition yyjson.h:6816
yyjson_api_inline yyjson_mut_obj_iter yyjson_mut_obj_iter_with(yyjson_mut_val *obj)
Definition yyjson.h:6793
[yyjson_mut_obj_iter](yyjson_8h.html#structyyjson mut obj__iter)
Definition yyjson.h:3537
Sample code 2 (mutable foreach macro):
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj; // the object to be traversed
size_t idx, max;
yyjson_val *key, *val;
yyjson_obj_foreach(obj, idx, max, key, val) {
your_func(key, val);
}
The yyjson_mut_doc and related APIs are used to build JSON documents.
Please note that yyjson_mut_doc uses a memory pool to hold all strings and values. The pool can only be created, grown, or freed in its entirety. Therefore, yyjson_mut_doc is more suitable for write-once than mutation of an existing document.
JSON objects and arrays are composed of linked lists, so each yyjson_mut_val can only be added to one object or array.
Sample code:
// Build this JSON:
// {
// "page": 123,
// "names": ["Harry", "Ron", "Hermione"]
// }
// Create a mutable document.
[yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc = yyjson_mut_doc_new(NULL);
// Create an object, the value's memory is held by doc.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *root = yyjson_mut_obj(doc);
// Create key and value, add to the root object.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *key = yyjson_mut_str(doc, "page");
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *num = yyjson_mut_int(doc, 123);
yyjson_mut_obj_add(root, key, num);
// Create 3 string value, add to the array object.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *names = yyjson_mut_arr(doc);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *name1 = yyjson_mut_str(doc, "Harry");
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *name2 = yyjson_mut_str(doc, "Ron");
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *name3 = yyjson_mut_str(doc, "Hermione");
yyjson_mut_arr_append(names, name1);
yyjson_mut_arr_append(names, name2);
yyjson_mut_arr_append(names, name3);
yyjson_mut_obj_add(root, yyjson_mut_str(doc, "names"), names);
// ❌ Wrong! the value is already added to another container.
yyjson_mut_obj_add(root, key, name1);
// Set the document's root value.
yyjson_mut_doc_set_root(doc, root);
// Write to JSON string
const char *json = yyjson_mut_write(doc, 0, NULL);
// Free the memory of doc and all values which is created from this doc.
yyjson_mut_doc_free(doc);
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj(yyjson_mut_doc *doc)
Definition yyjson.h:6870
yyjson_api void yyjson_mut_doc_free(yyjson_mut_doc *doc)
yyjson_api_inline yyjson_mut_val * yyjson_mut_int(yyjson_mut_doc *doc, int64_t num)
Definition yyjson.h:6035
yyjson_api_inline bool yyjson_mut_obj_add(yyjson_mut_val *obj, yyjson_mut_val *key, yyjson_mut_val *val)
Definition yyjson.h:7024
yyjson_api_inline bool yyjson_mut_arr_append(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition yyjson.h:6405
The following functions are used to create, modify, copy, and destroy a JSON document.
// Creates and returns a new mutable JSON document.
// Returns NULL on error (e.g. memory allocation failure).
// If alc is NULL, the default allocator will be used.
[yyjson_mut_doc](yyjson_8h.html#structyyjson 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](yyjson_8h.html#structyyjson mut doc) *doc);
// Set the internal memory pool size (string length and value count).
// It can be used to reserve memory for the next string and value creation.
bool yyjson_mut_doc_set_str_pool_size([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, size_t len);
bool yyjson_mut_doc_set_val_pool_size([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, size_t count);
// Get or set the root value of this JSON document.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_get_root([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
void yyjson_mut_doc_set_root([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *root);
// Copies and returns a new mutable document/value from input.
// Returns NULL on error (e.g. memory allocation failure).
// doc -> mut_doc
[yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *yyjson_doc_mut_copy(yyjson_doc *doc, const yyjson_alc *alc);
// val -> mut_val
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_val_mut_copy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, yyjson_val *val);
// mut_doc -> mut_doc
[yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *yyjson_mut_doc_mut_copy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const yyjson_alc *alc);
// mut_val -> mut_val
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_val_mut_copy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val);
// mut_doc -> doc
yyjson_doc *yyjson_mut_doc_imut_copy(yyjson_mut_doc *doc, yyjson_alc *alc);
// mut_val -> doc
yyjson_doc *yyjson_mut_val_imut_copy(yyjson_mut_val *val, yyjson_alc *alc);
yyjson_api yyjson_mut_val * yyjson_mut_val_mut_copy(yyjson_mut_doc *doc, yyjson_mut_val *val)
yyjson_api yyjson_mut_doc * yyjson_mut_doc_mut_copy(yyjson_mut_doc *doc, const yyjson_alc *alc)
yyjson_mut_doc_set_val_pool_size
yyjson_api bool yyjson_mut_doc_set_val_pool_size(yyjson_mut_doc *doc, size_t count)
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_get_root(yyjson_mut_doc *doc)
Definition yyjson.h:5701
yyjson_mut_doc_set_str_pool_size
yyjson_api bool yyjson_mut_doc_set_str_pool_size(yyjson_mut_doc *doc, size_t len)
The following functions are used to create mutable JSON value, the value's memory is held by the document.
// Creates and returns a new value, returns NULL on error.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_null([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_true([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_false([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_bool([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, bool val);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_uint([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, uint64_t num);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_sint([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, int64_t num);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_int([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, int64_t num);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_float([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, float num);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_double([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, double num);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_real([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, double num);
// Creates a string value, the input string is NOT copied.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_str([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *str);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_strn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *str, size_t len);
// Creates a string value, the input string is copied and held by the document.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_strcpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *str);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_strncpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *str, size_t len);
yyjson_api_inline yyjson_mut_val * yyjson_mut_true(yyjson_mut_doc *doc)
Definition yyjson.h:6012
yyjson_api_inline yyjson_mut_val * yyjson_mut_real(yyjson_mut_doc *doc, double num)
Definition yyjson.h:6050
yyjson_api_inline yyjson_mut_val * yyjson_mut_false(yyjson_mut_doc *doc)
Definition yyjson.h:6016
yyjson_api_inline yyjson_mut_val * yyjson_mut_float(yyjson_mut_doc *doc, float num)
Definition yyjson.h:6040
yyjson_api_inline yyjson_mut_val * yyjson_mut_bool(yyjson_mut_doc *doc, bool val)
Definition yyjson.h:6020
yyjson_api_inline yyjson_mut_val * yyjson_mut_null(yyjson_mut_doc *doc)
Definition yyjson.h:6008
yyjson_api_inline yyjson_mut_val * yyjson_mut_uint(yyjson_mut_doc *doc, uint64_t num)
Definition yyjson.h:6025
yyjson_api_inline yyjson_mut_val * yyjson_mut_double(yyjson_mut_doc *doc, double num)
Definition yyjson.h:6045
yyjson_api_inline yyjson_mut_val * yyjson_mut_sint(yyjson_mut_doc *doc, int64_t num)
Definition yyjson.h:6030
The following functions are used to create mutable JSON array.
// Creates and returns an empty mutable array, returns NULL on error.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
// Creates and returns a mutable array with c array.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_bool([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, bool *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_sint([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, int64_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_uint([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, uint64_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_real([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, double *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_sint8([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, int8_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_sint16([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, int16_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_sint32([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, int32_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_sint64([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, int64_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_uint8([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, uint8_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_uint16([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, uint16_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_uint32([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, uint32_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_uint64([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, uint64_t *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_float([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, float *vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_double([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, double *vals, size_t count);
// sample code:
int vals[3] = {-1, 0, 1};
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr = yyjson_mut_arr_with_sint32(doc, vals, 3);
// Creates and returns a mutable array with strings,
// the strings should be encoded as UTF-8.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_str([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char **vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_strn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char **vals, const size_t *lens, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_strcpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char **vals, size_t count);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_with_strncpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char **vals, const size_t *lens, size_t count);
// sample code:
const char strs[3] = {"Jan", "Feb", "Mar"};
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr = yyjson_mut_arr_with_str(doc, strs, 3);
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:6233
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:6278
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:6271
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:6328
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_float(yyjson_mut_doc *doc, const float *vals, size_t count)
Definition yyjson.h:6306
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:6264
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_real(yyjson_mut_doc *doc, const double *vals, size_t count)
Definition yyjson.h:6243
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:6257
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:6285
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_strcpy(yyjson_mut_doc *doc, const char **vals, size_t count)
Definition yyjson.h:6337
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:6299
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:6238
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:6250
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:6292
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_double(yyjson_mut_doc *doc, const double *vals, size_t count)
Definition yyjson.h:6313
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:6351
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_str(yyjson_mut_doc *doc, const char **vals, size_t count)
Definition yyjson.h:6320
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_bool(yyjson_mut_doc *doc, const bool *vals, size_t count)
Definition yyjson.h:6226
The following functions are used to modify the contents of a JSON array.
// Inserts a value into an array at a given index.
// Returns false on error (e.g. out of bounds).
// Note that this function takes a linear search time.
bool yyjson_mut_arr_insert([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, size_t idx);
// Inserts a val at the end of the array, returns false on error.
bool yyjson_mut_arr_append([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val);
// Inserts a val at the head of the array, returns false on error.
bool yyjson_mut_arr_prepend([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val);
// 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_8h.html#structyyjson mut val) *yyjson_mut_arr_replace([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, size_t idx, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val);
// Removes and returns a value at index, returns NULL on error.
// Note that this function takes a linear search time.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_remove([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, size_t idx);
// Removes and returns the first value in this array, returns NULL on error.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_remove_first([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr);
// Removes and returns the last value in this array, returns NULL on error.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_remove_last([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr);
// 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](yyjson_8h.html#structyyjson mut val) *arr, size_t idx, size_t len);
// Removes all values in this array.
bool yyjson_mut_arr_clear([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr);
// Convenience API:
// Adds a value at the end of this array, returns false on error.
bool yyjson_mut_arr_add_val([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val);
bool yyjson_mut_arr_add_null([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr);
bool yyjson_mut_arr_add_true([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr);
bool yyjson_mut_arr_add_false([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr);
bool yyjson_mut_arr_add_bool([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, bool val);
bool yyjson_mut_arr_add_uint([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, uint64_t num);
bool yyjson_mut_arr_add_sint([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, int64_t num);
bool yyjson_mut_arr_add_int([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, int64_t num);
bool yyjson_mut_arr_add_float([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, float num);
bool yyjson_mut_arr_add_double([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, double num);
bool yyjson_mut_arr_add_real([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, double num);
bool yyjson_mut_arr_add_str([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, const char *str);
bool yyjson_mut_arr_add_strn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, const char *str, size_t len);
bool yyjson_mut_arr_add_strcpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, const char *str);
bool yyjson_mut_arr_add_strncpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr, const char *str, size_t len);
// Convenience API:
// Creates and adds a new array at the end of the array.
// Returns the new array, or NULL on error.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_add_arr([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr);
// Convenience API:
// Creates and adds a new object at the end of the array.
// Returns the new object, or NULL on error.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_arr_add_obj([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *arr);
yyjson_api_inline bool yyjson_mut_arr_add_str(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str)
Definition yyjson.h:6686
yyjson_api_inline bool yyjson_mut_arr_add_true(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition yyjson.h:6598
yyjson_api_inline bool yyjson_mut_arr_prepend(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition yyjson.h:6424
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:6716
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove(yyjson_mut_val *arr, size_t idx)
Definition yyjson.h:6471
yyjson_api_inline bool yyjson_mut_arr_clear(yyjson_mut_val *arr)
Definition yyjson.h:6558
yyjson_api_inline bool yyjson_mut_arr_add_strcpy(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str)
Definition yyjson.h:6706
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_replace(yyjson_mut_val *arr, size_t idx, yyjson_mut_val *val)
Definition yyjson.h:6443
yyjson_api_inline bool yyjson_mut_arr_add_double(yyjson_mut_doc *doc, yyjson_mut_val *arr, double num)
Definition yyjson.h:6666
yyjson_api_inline bool yyjson_mut_arr_add_bool(yyjson_mut_doc *doc, yyjson_mut_val *arr, bool val)
Definition yyjson.h:6616
yyjson_api_inline bool yyjson_mut_arr_add_uint(yyjson_mut_doc *doc, yyjson_mut_val *arr, uint64_t num)
Definition yyjson.h:6626
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_add_arr(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition yyjson.h:6726
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove_last(yyjson_mut_val *arr)
Definition yyjson.h:6514
yyjson_api_inline bool yyjson_mut_arr_add_false(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition yyjson.h:6607
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:6696
yyjson_api_inline bool yyjson_mut_arr_add_real(yyjson_mut_doc *doc, yyjson_mut_val *arr, double num)
Definition yyjson.h:6676
yyjson_api_inline bool yyjson_mut_arr_add_float(yyjson_mut_doc *doc, yyjson_mut_val *arr, float num)
Definition yyjson.h:6656
yyjson_api_inline bool yyjson_mut_arr_add_val(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition yyjson.h:6584
yyjson_api_inline bool yyjson_mut_arr_add_sint(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num)
Definition yyjson.h:6636
yyjson_api_inline bool yyjson_mut_arr_remove_range(yyjson_mut_val *arr, size_t idx, size_t len)
Definition yyjson.h:6536
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_add_obj(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition yyjson.h:6735
yyjson_api_inline bool yyjson_mut_arr_insert(yyjson_mut_val *arr, yyjson_mut_val *val, size_t idx)
Definition yyjson.h:6374
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove_first(yyjson_mut_val *arr)
Definition yyjson.h:6495
yyjson_api_inline bool yyjson_mut_arr_add_null(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition yyjson.h:6589
The following functions are used to create mutable JSON object.
// Creates and returns a mutable object, returns NULL on error.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_obj([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
// 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_8h.html#structyyjson mut val) *yyjson_mut_obj_with_str([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc,
const char **keys,
const char **vals,
size_t count);
// sample code:
const char keys[] = {"name", "type", "id"};
const char *vals[] = {"Harry", "student", "123456"};
yyjson_mut_obj_with_str(doc, keys, vals, 3);
// Creates and returns a mutable object with key-value pairs,
// 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_8h.html#structyyjson mut val) *yyjson_mut_obj_with_kv([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc,
const char **kv_pairs,
size_t pair_count);
// sample code:
const char *pairs[] = {"name", "Harry", "type", "student", "id", "123456"};
yyjson_mut_obj_with_kv(doc, pairs, 3);
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:6881
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:6912
The following functions are used to modify the contents of a JSON object.
// Adds a key-value pair at the end of the object.
// The key must be a string value.
// This function allows duplicated key in one object.
bool yyjson_mut_obj_add([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *key,[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val);
// Adds a key-value pair to the object.
// The key must be a string value.
// 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](yyjson_8h.html#structyyjson mut val) *obj, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *key, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val);
// Removes key-value pair from the object with a given key.
// Note that this function takes a linear search time.
bool yyjson_mut_obj_remove([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *key);
// Removes all key-value pairs in this object.
bool yyjson_mut_obj_clear([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj);
// 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](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key);
bool yyjson_mut_obj_add_true([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key);
bool yyjson_mut_obj_add_false([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key);
bool yyjson_mut_obj_add_bool([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, bool val);
bool yyjson_mut_obj_add_uint([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, uint64_t val);
bool yyjson_mut_obj_add_sint([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, int64_t val);
bool yyjson_mut_obj_add_int([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, int64_t val);
bool yyjson_mut_obj_add_float([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, float val);
bool yyjson_mut_obj_add_double([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, double val);
bool yyjson_mut_obj_add_real([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, double val);
bool yyjson_mut_obj_add_str([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, const char *val);
bool yyjson_mut_obj_add_strn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, const char *val, size_t len);
bool yyjson_mut_obj_add_strcpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, const char *val);
bool yyjson_mut_obj_add_strncpy([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, const char *val, size_t len);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_obj_add_arr([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *_key);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_obj_add_obj([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *_key);
// Convenience API:
// 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](yyjson_8h.html#structyyjson mut val) *obj, const char *key);
bool yyjson_mut_obj_remove_strn([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, size_t len);
// Convenience API:
// Replaces all matching keys with the new key.
// Returns true if at least one key was renamed.
// This function takes a linear search time.
yyjson_api_inline bool yyjson_mut_obj_rename_key([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, const char *new_key);
yyjson_api_inline bool yyjson_mut_obj_rename_keyn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *obj, const char *key, size_t len, const char *new_key, size_t new_len);
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_add_arr(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition yyjson.h:7281
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:7268
yyjson_api_inline bool yyjson_mut_obj_add_double(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, double val)
Definition yyjson.h:7215
yyjson_api_inline bool yyjson_mut_obj_rename_keyn(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, size_t len, const char *new_key, size_t new_len)
Definition yyjson.h:7339
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:7194
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:7243
yyjson_api_inline bool yyjson_mut_obj_add_false(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition yyjson.h:7174
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:7201
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:7187
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove_str(yyjson_mut_val *obj, const char *key)
Definition yyjson.h:7307
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove(yyjson_mut_val *obj, yyjson_mut_val *key)
Definition yyjson.h:7083
#define yyjson_api_inline
Definition yyjson.h:340
yyjson_api_inline bool yyjson_mut_obj_add_null(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition yyjson.h:7162
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_add_obj(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition yyjson.h:7289
yyjson_api_inline bool yyjson_mut_obj_add_true(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition yyjson.h:7168
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:7229
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:7222
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:7180
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:7255
yyjson_api_inline bool yyjson_mut_obj_put(yyjson_mut_val *obj, yyjson_mut_val *key, yyjson_mut_val *val)
Definition yyjson.h:7035
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove_strn(yyjson_mut_val *obj, const char *key, size_t len)
Definition yyjson.h:7312
yyjson_api_inline bool yyjson_mut_obj_rename_key(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, const char *new_key)
Definition yyjson.h:7330
yyjson_api_inline bool yyjson_mut_obj_add_float(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key, float val)
Definition yyjson.h:7208
yyjson_api_inline bool yyjson_mut_obj_clear(yyjson_mut_val *obj)
Definition yyjson.h:7109
The library supports querying JSON values using JSON Pointer (RFC 6901).
// JSON pointer is a null-terminated string.
yyjson_val *yyjson_ptr_get(yyjson_val *val, const char *ptr);
yyjson_val *yyjson_doc_ptr_get(yyjson_doc *doc, const char *ptr);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_get([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_get([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr);
// JSON pointer with string length, allow NUL (Unicode U+0000) characters inside.
yyjson_val *yyjson_ptr_getn(yyjson_val *val, const char *ptr, size_t len);
yyjson_val *yyjson_doc_ptr_getn(yyjson_doc *doc, const char *ptr, size_t len);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_getn([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_getn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len);
// JSON pointer with string length, context and error information.
yyjson_val *yyjson_ptr_getx(yyjson_val *val, const char *ptr, size_t len, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
yyjson_val *yyjson_doc_ptr_getx(yyjson_doc *doc, const char *ptr, size_t len, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_getx([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_getx([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_getn(yyjson_mut_doc *doc, const char *ptr, size_t len)
Definition yyjson.h:7479
yyjson_api_inline yyjson_val * yyjson_ptr_getx(yyjson_val *val, const char *ptr, size_t len, yyjson_ptr_err *err)
Definition yyjson.h:7455
yyjson_api_inline yyjson_val * yyjson_doc_ptr_getx(yyjson_doc *doc, const char *ptr, size_t len, yyjson_ptr_err *err)
Definition yyjson.h:7422
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_get(yyjson_mut_doc *doc, const char *ptr)
Definition yyjson.h:7473
yyjson_api_inline yyjson_val * yyjson_doc_ptr_getn(yyjson_doc *doc, const char *ptr, size_t len)
Definition yyjson.h:7417
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_getx(yyjson_mut_doc *doc, const char *ptr, size_t len, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7485
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_getn(yyjson_mut_val *val, const char *ptr, size_t len)
Definition yyjson.h:7517
yyjson_api_inline yyjson_val * yyjson_ptr_get(yyjson_val *val, const char *ptr)
Definition yyjson.h:7444
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_get(yyjson_mut_val *val, const char *ptr)
Definition yyjson.h:7511
yyjson_api_inline yyjson_val * yyjson_doc_ptr_get(yyjson_doc *doc, const char *ptr)
Definition yyjson.h:7411
yyjson_api_inline yyjson_val * yyjson_ptr_getn(yyjson_val *val, const char *ptr, size_t len)
Definition yyjson.h:7450
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_getx(yyjson_mut_val *val, const char *ptr, size_t len, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7523
[yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx)
Definition yyjson.h:4120
[yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err)
Definition yyjson.h:4092
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 |
"/" | NULL (match to empty key: root[""]) |
yyjson_doc *doc = ...;
yyjson_val *val = yyjson_doc_ptr_get(doc, "/users/1/name");
printf("%s\n", yyjson_get_str(val)); // Ron
[yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) err;
yyjson_val *val2 = yyjson_doc_ptr_getx(doc, "/", 1, &err);
if (!val2) printf("err %d: %s\n", err.code, err.msg); // err 3: cannot be resolved
const char * msg
Definition yyjson.h:4096
yyjson_ptr_code code
Definition yyjson.h:4094
The library also supports modifying JSON values using JSON Pointer.
// Add or insert a new value.
bool yyjson_mut_ptr_add([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
bool yyjson_mut_ptr_addn([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
bool yyjson_mut_ptr_addx([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, bool create_parent, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
bool yyjson_mut_doc_ptr_add([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val);
bool yyjson_mut_doc_ptr_addn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val);
bool yyjson_mut_doc_ptr_addx([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, bool create_parent, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
// Set a new value (add if it doesn't exist, replace if it does).
bool yyjson_mut_ptr_set([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
bool yyjson_mut_ptr_setn([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc);
bool yyjson_mut_ptr_setx([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, [yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, bool create_parent, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
bool yyjson_mut_doc_ptr_set([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val);
bool yyjson_mut_doc_ptr_setn([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val);
bool yyjson_mut_doc_ptr_setx([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, bool create_parent, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
// Replace an existing value.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_replace([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_replacen([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_replacex([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_replace([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_replacen([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_replacex([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len, [yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *new_val, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
// Remove an existing value.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_remove([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_removen([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_ptr_removex([yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val, const char *ptr, size_t len, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_remove([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_removen([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_doc_ptr_removex([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc, const char *ptr, size_t len, [yyjson_ptr_ctx](yyjson_8h.html#structyyjson ptr ctx) *ctx, [yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) *err);
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_remove(yyjson_mut_doc *doc, const char *ptr)
Definition yyjson.h:7831
yyjson_api_inline bool yyjson_mut_ptr_setx(yyjson_mut_val *val, const char *ptr, size_t len, yyjson_mut_val *new_val, yyjson_mut_doc *doc, bool create_parent, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7725
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_replace(yyjson_mut_doc *doc, const char *ptr, yyjson_mut_val *new_val)
Definition yyjson.h:7754
yyjson_api_inline bool yyjson_mut_doc_ptr_setn(yyjson_mut_doc *doc, const char *ptr, size_t len, yyjson_mut_val *new_val)
Definition yyjson.h:7654
yyjson_api_inline bool yyjson_mut_ptr_addx(yyjson_mut_val *val, const char *ptr, size_t len, yyjson_mut_val *new_val, yyjson_mut_doc *doc, bool create_parent, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7621
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_removex(yyjson_mut_doc *doc, const char *ptr, size_t len, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7842
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_removen(yyjson_mut_val *val, const char *ptr, size_t len)
Definition yyjson.h:7876
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_replacex(yyjson_mut_val *val, const char *ptr, size_t len, yyjson_mut_val *new_val, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7809
yyjson_api_inline bool yyjson_mut_doc_ptr_setx(yyjson_mut_doc *doc, const char *ptr, size_t len, yyjson_mut_val *new_val, bool create_parent, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7660
yyjson_api_inline bool yyjson_mut_ptr_set(yyjson_mut_val *val, const char *ptr, yyjson_mut_val *new_val, yyjson_mut_doc *doc)
Definition yyjson.h:7710
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_removen(yyjson_mut_doc *doc, const char *ptr, size_t len)
Definition yyjson.h:7837
yyjson_api_inline bool yyjson_mut_doc_ptr_addn(yyjson_mut_doc *doc, const char *ptr, size_t len, yyjson_mut_val *new_val)
Definition yyjson.h:7552
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_removex(yyjson_mut_val *val, const char *ptr, size_t len, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7882
yyjson_api_inline bool yyjson_mut_doc_ptr_set(yyjson_mut_doc *doc, const char *ptr, yyjson_mut_val *new_val)
Definition yyjson.h:7647
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_replacen(yyjson_mut_doc *doc, const char *ptr, size_t len, yyjson_mut_val *new_val)
Definition yyjson.h:7760
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_remove(yyjson_mut_val *val, const char *ptr)
Definition yyjson.h:7870
yyjson_api_inline bool yyjson_mut_ptr_addn(yyjson_mut_val *val, const char *ptr, size_t len, yyjson_mut_val *new_val, yyjson_mut_doc *doc)
Definition yyjson.h:7614
yyjson_api_inline bool yyjson_mut_ptr_add(yyjson_mut_val *val, const char *ptr, yyjson_mut_val *new_val, yyjson_mut_doc *doc)
Definition yyjson.h:7606
yyjson_api_inline bool yyjson_mut_ptr_setn(yyjson_mut_val *val, const char *ptr, size_t len, yyjson_mut_val *new_val, yyjson_mut_doc *doc)
Definition yyjson.h:7718
yyjson_api_inline bool yyjson_mut_doc_ptr_addx(yyjson_mut_doc *doc, const char *ptr, size_t len, yyjson_mut_val *new_val, bool create_parent, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7559
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_replace(yyjson_mut_val *val, const char *ptr, yyjson_mut_val *new_val)
Definition yyjson.h:7798
yyjson_api_inline bool yyjson_mut_doc_ptr_add(yyjson_mut_doc *doc, const char *ptr, yyjson_mut_val *new_val)
Definition yyjson.h:7545
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_replacex(yyjson_mut_doc *doc, const char *ptr, size_t len, yyjson_mut_val *new_val, yyjson_ptr_ctx *ctx, yyjson_ptr_err *err)
Definition yyjson.h:7765
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_replacen(yyjson_mut_val *val, const char *ptr, size_t len, yyjson_mut_val *new_val)
Definition yyjson.h:7804
For example:
[yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc = ...;
// doc: {"a":0,"b":[1,2,3]}
yyjson_mut_doc_ptr_set(doc, "/a", yyjson_mut_int(doc, 9));
// now: {"a":9,"b":[1,2,3]}
yyjson_mut_doc_ptr_add(doc, "/b/-", yyjson_mut_int(doc, 4));
// now: {"a":9,"b":[1,2,3,4]}
yyjson_mut_doc_ptr_remove(doc, "/b");
// now: {"a":9}
All the above functions ending with x can be used to get the result context ctx, and the error message err. For example:
// doc: {"a":0,"b":[null,2,3]}
[yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc = ...;
// get error code and message
[yyjson_ptr_err](yyjson_8h.html#structyyjson ptr err) err;
yyjson_mut_doc_ptr_setx(doc, "/b/99", 4, yyjson_mut_int(doc, 99), true, NULL, &err);
if (err.code) printf("err: %s\n", err.msg); // err: cannot resolve
// get target value's context
// perform some operations without re-parsing the JSON Pointer
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *val = yyjson_mut_doc_ptr_getx(doc, "/b/0", 4, &ctx, &err);
if (yyjson_mut_is_null(val)) yyjson_ptr_ctx_remove(&ctx);
// now: {"a":0,"b":[2,3]}
yyjson_api_inline bool yyjson_mut_is_null(yyjson_mut_val *val)
Definition yyjson.h:5720
yyjson_api_inline bool yyjson_ptr_ctx_remove(yyjson_ptr_ctx *ctx)
Definition yyjson.h:7991
The library supports JSON Patch (RFC 6902). Specification and example: https://tools.ietf.org/html/rfc6902
// Creates and returns a patched JSON value.
// Returns NULL if the patch could not be applied.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_patch([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc,
yyjson_val *orig,
yyjson_val *patch,
[yyjson_patch_err](yyjson_8h.html#structyyjson patch err) *err);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_patch([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc,
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *orig,
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *patch,
[yyjson_patch_err](yyjson_8h.html#structyyjson patch err) *err);
yyjson_api yyjson_mut_val * yyjson_patch(yyjson_mut_doc *doc, yyjson_val *orig, yyjson_val *patch, yyjson_patch_err *err)
yyjson_api yyjson_mut_val * yyjson_mut_patch(yyjson_mut_doc *doc, yyjson_mut_val *orig, yyjson_mut_val *patch, yyjson_patch_err *err)
[yyjson_patch_err](yyjson_8h.html#structyyjson patch err)
Definition yyjson.h:4680
The library supports JSON Merge Patch (RFC 7386). Specification and example: https://tools.ietf.org/html/rfc7386
// Creates and returns a merge-patched JSON value.
// Returns NULL if the patch could not be applied.
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_merge_patch([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc,
yyjson_val *orig,
yyjson_val *patch);
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *yyjson_mut_merge_patch([yyjson_mut_doc](yyjson_8h.html#structyyjson mut doc) *doc,
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *orig,
[yyjson_mut_val](yyjson_8h.html#structyyjson mut val) *patch);
yyjson_api yyjson_mut_val * yyjson_merge_patch(yyjson_mut_doc *doc, yyjson_val *orig, yyjson_val *patch)
yyjson_api yyjson_mut_val * yyjson_mut_merge_patch(yyjson_mut_doc *doc, yyjson_mut_val *orig, yyjson_mut_val *patch)
The library has a built-in high-performance number reader,
it will read numbers according to these rules by default:
uint64_t. If an overflow occurs, it is converted to double.int64_t. If an overflow occurs, it is converted to double.double with correct rounding.double number overflow (reaches infinity), an error is reported.There are 3 flags that can be used to adjust the number parsing strategy:
YYJSON_READ_ALLOW_INF_AND_NAN: read nan/inf number or literal as double (non-standard).YYJSON_READ_NUMBER_AS_RAW: read all numbers as raw strings without parsing.YYJSON_READ_BIGNUM_AS_RAW: read big numbers (overflow or infinity) as raw strings without parsing.See the Reader flag section for more details.
The library has a built-in high-performance number writer,
it will write numbers according to these rules by default:
Positive integers are written without a sign.
Negative integers are written with a negative sign.
Floating-point numbers are written using the ECMAScript format, with the following modifications:
Infinity or NaN, an error is reported.-0.0 is preserved to maintain input information.The floating-point number writer will generate the shortest correctly rounded decimal representation.
There are several flags that can be used to adjust the number writing strategy:
YYJSON_WRITE_ALLOW_INF_AND_NAN writes inf/nan numbers as Infinity and NaN literals without error (non-standard).YYJSON_WRITE_INF_AND_NAN_AS_NULL writes inf/nan numbers as null literal.YYJSON_WRITE_FP_TO_FLOAT writes real numbers as float instead of double.YYJSON_WRITE_FP_TO_FIXED(prec) writes real numbers using fixed-point notation.See the Writer flag section for more details.
There are also some helper functions to control the output format of individual values:
yyjson_set_fp_to_float(yyjson_val *val, bool fpt) and yyjson_mut_set_fp_to_float(yyjson_mut_val *val, bool flt) write this real number with float or double precision.yyjson_set_fp_to_fixed(yyjson_val *val, int prec) and yyjson_mut_set_fp_to_fixed(yyjson_mut_val *val, int prec) write this real number using fixed-point notation, the prec should be in the range of 1 to 15.There are also two utility functions provide direct access to the library's internal number conversion logic.
They are intended for standalone use and typically do not allocate memory.
// parse a number from strin
const char *yyjson_read_number(const char *dat,
yyjson_val *val,
yyjson_read_flag flg,
const yyjson_alc *alc,
[yyjson_read_err](yyjson_8h.html#structyyjson read err) *err);
// write a number to string
char *yyjson_write_number(const yyjson_val *val, char *buf);
yyjson_api char * yyjson_write_number(const yyjson_val *val, char *buf)
yyjson_api const char * yyjson_read_number(const char *dat, yyjson_val *val, yyjson_read_flag flg, const yyjson_alc *alc, yyjson_read_err *err)
By default, this library supports UTF-8 encoding without a 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.
This library performs strict UTF-8 encoding validation on input strings by default. If an invalid character is encountered, an error will be reported.
To allow a BOM, use the YYJSON_READ_ALLOW_BOM or YYJSON_READ_ALLOW_EXT_WHITESPACE flags.
To allow invalid Unicode encoding, use the YYJSON_READ_ALLOW_INVALID_UNICODE and YYJSON_WRITE_ALLOW_INVALID_UNICODE flags. Note: Enabling these flags may result in yyjson producing values that contain invalid characters, which could be processed by other code and potentially introduce security risks.
To mark a string as not requiring escaping during JSON writing, use yyjson_set_str_noesc(yyjson_val *val, bool noesc) or yyjson_mut_set_str_noesc(yyjson_mut_val *val, bool noesc). This can improve string-writing performance and preserve the original string bytes.
This library supports the NUL character (also known as the null terminator, or Unicode U+0000, ASCII \0) inside strings.
When reading JSON, \u0000 will be unescaped to NUL character. If a string contains the NUL character, the length obtained with strlen() will be inaccurate, and you should use yyjson_get_len() to get the actual length.
When building JSON, the input string is treated as null-terminated by default. If you need to pass in a string that contains the NUL character, you should use the API with the n suffix and provide the actual length of the string.
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());
The library does not directly call libc's memory allocation functions (malloc/realloc/free). Instead, 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.
Using a custom memory allocator allows you to have more control over memory allocation, here are a few examples:
If you need to parse multiple small JSON one by one, you can use a single allocator to avoid multiple memory allocations.
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 using one 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_api_inline size_t yyjson_read_max_memory_usage(size_t len, yyjson_read_flag flg)
Definition yyjson.h:1090
If you are not sure about the amount of memory required to process JSON, you can use the dynamic allocator.
// create a dynamic allocator
yyjson_alc *alc = yyjson_alc_dyn_new();
// read multiple JSON using one 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 allocator
yyjson_alc_dyn_free(alc);
yyjson_api yyjson_alc * yyjson_alc_dyn_new(void)
yyjson_api void yyjson_alc_dyn_free(yyjson_alc *alc)
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
You can use a third-party high-performance memory allocator for yyjson, such as jemalloc, tcmalloc, mimalloc. You can also refer to the following code to implement your own allocator.
Sample code:
// Use https://github.com/microsoft/mimalloc
#include <mimalloc.h>
// same as malloc(size)
static void *priv_malloc(void *ctx, size_t size) {
return mi_malloc(size);
}
// same as realloc(ptr, size)
// old_size is the size of the originally allocated memory
static void *priv_realloc(void *ctx, void *ptr, size_t old_size, size_t size) {
return mi_realloc(ptr, size);
}
// same as free(ptr)
static void priv_free(void *ctx, void *ptr) {
mi_free(ptr);
}
// the allocator object
static const yyjson_alc PRIV_ALC = {
priv_malloc,
priv_realloc,
priv_free,
NULL // ctx which will be passed into the functions above
};
// 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);
Most functions in the library use fixed-size stack memory. This includes functions for JSON reading and writing, as well as JSON Pointer handling.
However, a few functions use recursion and may cause a stack overflow if the object level is too deep. These functions are marked with the following warning in the header file:
WarningThis function is recursive and may cause a stack overflow if the object level is too deep.
The library's public APIs perform a null check for every input parameter to prevent crashes.
For example, when reading a JSON, you don't need to perform null checks or type checks 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
However, if you are certain that a value is non-null and matches the expected type, 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 valid string
if (unsafe_yyjson_equals_str(key, "id") &&
unsafe_yyjson_is_uint(val) &&
unsafe_yyjson_get_uint(val) == 1234) {
...
}
}
The library does not use global variables. Therefore, if you can ensure that the input parameters of a function are thread-safe, then the function calls are also thread-safe.
In general, yyjson_doc and yyjson_val are immutable and thread-safe, while yyjson_mut_doc and yyjson_mut_val are mutable and not thread-safe.
The library is designed to be locale-independent.
However, there are certain conditions that you should be aware of:
setlocale() function to change the locale.YYJSON_DISABLE_FAST_FP_CONV during build, in such case yyjson will use strtod() to parse floating-point numbers.If both of these conditions are met, it is recommended to avoid calling setlocale() while another thread is parsing JSON. Otherwise, an error may be returned during JSON floating-point number parsing.