This document contains all the API usage and examples for the yyjson library.
API Design
API prefix
All public functions and structs are prefixed with yyjson_
, and all constants are prefixed with YYJSON_
.
API for immutable/mutable data
The library have 2 types of data structures: immutable and mutable:
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:
yyjson_api_inline bool yyjson_is_str(yyjson_val *val)
Definition: yyjson.h:4888
yyjson_api_inline char * yyjson_mut_write(const yyjson_mut_doc *doc, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1343
yyjson_api_inline char * yyjson_write(const yyjson_doc *doc, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1239
yyjson_api_inline bool yyjson_mut_is_str(yyjson_mut_val *val)
Definition: yyjson.h:5429
Definition: yyjson.h:4501
Definition: yyjson.h:5311
Definition: yyjson.h:5263
Definition: yyjson.h:4496
The library also provides some functions to convert values between immutable and mutable:
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)
API for string
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:
yyjson_api_inline bool yyjson_equals_str(yyjson_val *val, const char *str)
Definition: yyjson.h:4975
yyjson_api_inline bool yyjson_equals_strn(yyjson_val *val, const char *str, size_t len)
Definition: yyjson.h:4983
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:
yyjson_api_inline yyjson_mut_val * yyjson_mut_strn(yyjson_mut_doc *doc, const char *str, size_t len)
Definition: yyjson.h:5745
yyjson_api_inline yyjson_mut_val * yyjson_mut_strncpy(yyjson_mut_doc *doc, const char *str, size_t len)
Definition: yyjson.h:5777
yyjson_api_inline yyjson_mut_val * yyjson_mut_strcpy(yyjson_mut_doc *doc, const char *str)
Definition: yyjson.h:5759
yyjson_api_inline yyjson_mut_val * yyjson_mut_str(yyjson_mut_doc *doc, const char *str)
Definition: yyjson.h:5728
Reading JSON
The library provides 4 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.
Read JSON from string
The dat
should be a UTF-8 string, null-terminator is not required.
The len
is the byte length of dat
.
The flg
is reader flag, pass 0 if you don't need it, see reader flag
for details.
If input is invalid, NULL
is returned.
size_t len,
uint32_t yyjson_read_flag
Definition: yyjson.h:731
yyjson_api_inline yyjson_doc * yyjson_read(const char *dat, size_t len, yyjson_read_flag flg)
Definition: yyjson.h:936
Sample code:
const char *str = "[1,2,3,4]";
if (doc) {...}
yyjson_api_inline void yyjson_doc_free(yyjson_doc *doc)
Definition: yyjson.h:4833
Read JSON from file
The path
is JSON file path.
The flg
is reader flag, pass 0 if you don't need it, see reader flag
for details.
The alc
is memory allocator, pass NULL if you don't need it, see memory allocator
for details.
The err
is a pointer to receive error message, pass NULL if you don't need it.
If input is invalid, NULL
is returned.
yyjson_api yyjson_doc * yyjson_read_file(const char *path, yyjson_read_flag flg, const yyjson_alc *alc, yyjson_read_err *err)
Sample code:
Read JSON from file pointer
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_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");
if (fp) fclose(fp);
if (doc) {...}
Read JSON with options
The dat
should be a UTF-8 string, you can pass a const string if you don't use YYJSON_READ_INSITU
flag.
The len
is the dat
's length in bytes.
The flg
is reader flag, pass 0 if you don't need it, see reader flag
for details.
The alc
is memory allocator, pass NULL if you don't need it, see memory allocator
for details.
The err
is a pointer to receive error message, pass NULL if you don't need it.
size_t len,
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_err err;
if (doc) {...}
else printf("read error: %s code: %u at position: %ld\n", err.msg, err.code, err.pos);
static const yyjson_read_flag YYJSON_READ_ALLOW_INF_AND_NAN
Definition: yyjson.h:765
static const yyjson_read_flag YYJSON_READ_ALLOW_COMMENTS
Definition: yyjson.h:761
Reader flag
The library provides a set of flags for JSON reader.
You can use a single flag, or combine multiple flags with bitwise |
operator.
● YYJSON_READ_NOFLAG = 0
This is the default flag for JSON reader (RFC-8259 or ECMA-404 compliant):
- Read positive integer as
uint64_t
.
- Read negative integer as
int64_t
.
- Read floating-point number as
double
with correct rounding.
- Read integer which cannot fit in
uint64_t
or int64_t
as double
.
- Report error if double number is infinity.
- Report error if string contains invalid UTF-8 character or BOM.
- Report error on trailing commas, comments,
Inf
and NaN
literals.
● YYJSON_READ_INSITU
Read the input data in-situ.
This option allows the reader to modify and use 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 = ...;
read_from_socket(buf, ...);
if (doc) {...}
free(buf);
static const yyjson_read_flag YYJSON_READ_INSITU
Definition: yyjson.h:749
#define YYJSON_PADDING_SIZE
Definition: yyjson.h:604
● YYJSON_READ_STOP_WHEN_DONE
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:
size_t file_size = ...;
char *dat = malloc(file_size + 4);
your_read_file(dat, file);
memset(dat + file_size, 0, 4);
char *hdr = dat;
char *end = dat + file_size;
while (true) {
if (!doc) break;
your_doc_process(doc);
}
free(dat);
yyjson_api_inline size_t yyjson_doc_get_read_size(yyjson_doc *doc)
Definition: yyjson.h:4825
static const yyjson_read_flag YYJSON_READ_STOP_WHEN_DONE
Definition: yyjson.h:754
● YYJSON_READ_ALLOW_TRAILING_COMMAS
Allow a single trailing comma at the end of an object or array (non-standard), for example:
{
"a": 1,
"b": 2,
}
[
"a",
"b",
]
● YYJSON_READ_ALLOW_COMMENTS
Allow C-style single line and multiple line comments (non-standard), for example:
{
"name": "Harry", // single line comment
"id": /* multiple line comment */ 123
}
● YYJSON_READ_ALLOW_INF_AND_NAN
Allow nan/inf number or case-insensitive literal (non-standard), for example:
{
"large": 123e999,
"nan1": NaN,
"nan2": nan,
"inf1:" Inf,
"inf2": -Infinity
}
● YYJSON_READ_NUMBER_AS_RAW
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:
yyjson_api_inline bool yyjson_is_raw(yyjson_val *val)
Definition: yyjson.h:4848
yyjson_api_inline const char * yyjson_get_raw(yyjson_val *val)
Definition: yyjson.h:4939
yyjson_api_inline size_t yyjson_get_len(yyjson_val *val)
Definition: yyjson.h:4971
● YYJSON_READ_BIGNUM_AS_RAW
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.
● YYJSON_READ_ALLOW_INVALID_UNICODE
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.
Writing JSON
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.
Write JSON to string
The doc/val
is JSON document or root value, if you pass NULL, you will get NULL result.
The flg
is writer flag, pass 0 if you don't need it, see writer flag
for details.
The len
is a pointer to receive output length (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.
yyjson_api_inline char * yyjson_val_write(const yyjson_val *val, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1448
yyjson_api_inline char * yyjson_mut_val_write(const yyjson_mut_val *val, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1550
uint32_t yyjson_write_flag
Definition: yyjson.h:1063
Sample code 1:
printf("%s\n", json);
free(json);
static const yyjson_write_flag YYJSON_WRITE_PRETTY
Definition: yyjson.h:1073
Sample code 2:
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:5378
yyjson_api_inline bool yyjson_mut_arr_add_int(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num)
Definition: yyjson.h:6357
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:5894
Write JSON to file
The path
is output JSON file path, If the path is invalid, you will get an error. If the file is not empty, the content will be discarded.
The doc/val
is JSON document or root value, if you pass NULL, you will get an error.
The flg
is writer flag, pass 0 if you don't need it, see writer flag
for details.
The alc
is memory allocator, pass NULL if you don't need it, see memory allocator
for details.
The err
is a pointer to receive error message, pass NULL if you don't need it.
This function returns true on success, or false if error occurs.
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)
Definition: yyjson.h:1133
Sample code:
Write JSON to file pointer
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.
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");
if (fp) fclose(fp);
if (suc) printf("OK");
Write JSON with options
The doc/val
is JSON document or root value, if you pass NULL, you will get NULL result.
The flg
is writer flag, pass 0 if you don't need it, see writer flag
for details.
The alc
is memory allocator, pass NULL if you don't need it, see memory allocator
for details.
The len
is a pointer to receive output length (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.
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:
char buf[64 * 1024];
size_t len;
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:624
void * ctx
Definition: yyjson.h:626
const char * msg
Definition: yyjson.h:1137
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:1076
yyjson_write_code code
Definition: yyjson.h:1135
Writer flag
The library provides a set of flags for JSON writer.
You can use a single flag, or combine multiple flags with bitwise |
operator.
● YYJSON_WRITE_NOFLAG = 0
This is the default flag for JSON writer:
- Writes JSON in minified format.
- Reports an error on encountering
inf
or nan
number.
- Reports an error on encountering invalid UTF-8 strings.
- Does not escape unicode or slashes.
● YYJSON_WRITE_PRETTY
Writes JSON with a pretty format uing a 4-space indent.
● YYJSON_WRITE_PRETTY_TWO_SPACES
Writes JSON with a pretty format uing a 2-space indent. This flag will override YYJSON_WRITE_PRETTY
flag.
● YYJSON_WRITE_ESCAPE_UNICODE
Escape unicode as \uXXXX
, making the output ASCII-only, for example:
["Alizée, 😊"]
["Aliz\\u00E9e, \\uD83D\\uDE0A"]
● YYJSON_WRITE_ESCAPE_SLASHES
Escapes the forward slash character /
as \/
, for example:
["https://github.com"]
["https:\/\/github.com"]
● YYJSON_WRITE_ALLOW_INF_AND_NAN
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}
● YYJSON_WRITE_INF_AND_NAN_AS_NULL
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}
● YYJSON_WRITE_ALLOW_INVALID_UNICODE
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.
● YYJSON_WRITE_NEWLINE_AT_END
Adds a newline character \n
at the end of the JSON. This can be helpful for text editors or NDJSON.
Accessing JSON Document
JSON Document
You can access the content of a document with the following functions:
yyjson_api_inline size_t yyjson_doc_get_val_count(yyjson_doc *doc)
Definition: yyjson.h:4829
yyjson_api_inline yyjson_val * yyjson_doc_get_root(yyjson_doc *doc)
Definition: yyjson.h:4821
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:
JSON Value
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.
uint8_t yyjson_subtype
Definition: yyjson.h:570
yyjson_api_inline bool yyjson_is_ctn(yyjson_val *val)
Definition: yyjson.h:4900
yyjson_api_inline uint8_t yyjson_get_tag(yyjson_val *val)
Definition: yyjson.h:4918
yyjson_api_inline bool yyjson_is_bool(yyjson_val *val)
Definition: yyjson.h:4864
yyjson_api_inline bool yyjson_is_real(yyjson_val *val)
Definition: yyjson.h:4880
yyjson_api_inline const char * yyjson_get_type_desc(yyjson_val *val)
Definition: yyjson.h:4922
uint8_t yyjson_type
Definition: yyjson.h:551
yyjson_api_inline bool yyjson_is_int(yyjson_val *val)
Definition: yyjson.h:4876
yyjson_api_inline bool yyjson_is_true(yyjson_val *val)
Definition: yyjson.h:4856
yyjson_api_inline bool yyjson_is_false(yyjson_val *val)
Definition: yyjson.h:4860
yyjson_api_inline yyjson_subtype yyjson_get_subtype(yyjson_val *val)
Definition: yyjson.h:4914
yyjson_api_inline yyjson_type yyjson_get_type(yyjson_val *val)
Definition: yyjson.h:4910
yyjson_api_inline bool yyjson_is_null(yyjson_val *val)
Definition: yyjson.h:4852
yyjson_api_inline bool yyjson_is_sint(yyjson_val *val)
Definition: yyjson.h:4872
yyjson_api_inline bool yyjson_is_uint(yyjson_val *val)
Definition: yyjson.h:4868
yyjson_api_inline bool yyjson_is_arr(yyjson_val *val)
Definition: yyjson.h:4892
yyjson_api_inline bool yyjson_is_num(yyjson_val *val)
Definition: yyjson.h:4884
yyjson_api_inline bool yyjson_is_obj(yyjson_val *val)
Definition: yyjson.h:4896
The following functions can be used to get the contents of the JSON value.
yyjson_api_inline int yyjson_get_int(yyjson_val *val)
Definition: yyjson.h:4955
yyjson_api_inline double yyjson_get_real(yyjson_val *val)
Definition: yyjson.h:4959
yyjson_api_inline const char * yyjson_get_str(yyjson_val *val)
Definition: yyjson.h:4967
yyjson_api_inline bool yyjson_get_bool(yyjson_val *val)
Definition: yyjson.h:4943
yyjson_api_inline uint64_t yyjson_get_uint(yyjson_val *val)
Definition: yyjson.h:4947
yyjson_api_inline double yyjson_get_num(yyjson_val *val)
Definition: yyjson.h:4963
yyjson_api_inline int64_t yyjson_get_sint(yyjson_val *val)
Definition: yyjson.h:4951
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).
yyjson_api_inline bool yyjson_set_null(yyjson_val *val)
Definition: yyjson.h:5006
yyjson_api_inline bool yyjson_set_raw(yyjson_val *val, const char *raw, size_t len)
Definition: yyjson.h:4999
yyjson_api_inline bool yyjson_set_uint(yyjson_val *val, uint64_t num)
Definition: yyjson.h:5018
yyjson_api_inline bool yyjson_set_str(yyjson_val *val, const char *str)
Definition: yyjson.h:5042
yyjson_api_inline bool yyjson_set_strn(yyjson_val *val, const char *str, size_t len)
Definition: yyjson.h:5049
yyjson_api_inline bool yyjson_set_real(yyjson_val *val, double num)
Definition: yyjson.h:5036
yyjson_api_inline bool yyjson_set_sint(yyjson_val *val, int64_t num)
Definition: yyjson.h:5024
yyjson_api_inline bool yyjson_set_bool(yyjson_val *val, bool num)
Definition: yyjson.h:5012
yyjson_api_inline bool yyjson_set_int(yyjson_val *val, int num)
Definition: yyjson.h:5030
JSON Array
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.
yyjson_api_inline size_t yyjson_arr_size(yyjson_val *arr)
Definition: yyjson.h:5063
yyjson_api_inline yyjson_val * yyjson_arr_get_last(yyjson_val *arr)
Definition: yyjson.h:5091
yyjson_api_inline yyjson_val * yyjson_arr_get(yyjson_val *arr, size_t idx)
Definition: yyjson.h:5067
yyjson_api_inline yyjson_val * yyjson_arr_get_first(yyjson_val *arr)
Definition: yyjson.h:5082
JSON Array Iterator
There are two ways to traverse an array:
Sample code 1 (iterator API):
your_func(val);
}
yyjson_api_inline yyjson_arr_iter yyjson_arr_iter_with(yyjson_val *arr)
Definition: yyjson.h:5125
yyjson_api_inline yyjson_val * yyjson_arr_iter_next(yyjson_arr_iter *iter)
Definition: yyjson.h:5135
Definition: yyjson.h:1810
Sample code 2 (foreach macro):
size_t idx, max;
your_func(idx, val);
}
#define yyjson_arr_foreach(arr, idx, max, val)
Definition: yyjson.h:1866
There's also mutable version API to traverse an mutable array:
Sample code 1 (mutable iterator API):
if (your_val_is_unused(val)) {
}
}
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_iter_remove(yyjson_mut_arr_iter *iter)
Definition: yyjson.h:5871
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_iter_next(yyjson_mut_arr_iter *iter)
Definition: yyjson.h:5859
yyjson_api_inline yyjson_mut_arr_iter yyjson_mut_arr_iter_with(yyjson_mut_val *arr)
Definition: yyjson.h:5848
Definition: yyjson.h:2490
Sample code 2 (mutable foreach macro):
size_t idx, max;
your_func(idx, val);
}
#define yyjson_mut_arr_foreach(arr, idx, max, val)
Definition: yyjson.h:2560
JSON Object
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.
yyjson_api_inline yyjson_val * yyjson_obj_get(yyjson_val *obj, const char *key)
Definition: yyjson.h:5156
yyjson_api_inline yyjson_val * yyjson_obj_iter_get(yyjson_obj_iter *iter, const char *key)
Definition: yyjson.h:5218
yyjson_api_inline yyjson_val * yyjson_obj_getn(yyjson_val *obj, const char *key, size_t key_len)
Definition: yyjson.h:5161
yyjson_api_inline yyjson_obj_iter yyjson_obj_iter_with(yyjson_val *obj)
Definition: yyjson.h:5194
yyjson_api_inline size_t yyjson_obj_size(yyjson_val *obj)
Definition: yyjson.h:5152
Definition: yyjson.h:1934
JSON Object Iterator
There are two ways to traverse an object:
Sample code 1 (iterator API):
your_func(key, val);
}
yyjson_api_inline yyjson_val * yyjson_obj_iter_get_val(yyjson_val *key)
Definition: yyjson.h:5214
yyjson_api_inline yyjson_val * yyjson_obj_iter_next(yyjson_obj_iter *iter)
Definition: yyjson.h:5204
Sample code 2 (foreach macro):
size_t idx, max;
your_func(key, val);
}
#define yyjson_obj_foreach(obj, idx, max, key, val)
Definition: yyjson.h:2037
There's also mutable version API to traverse an mutable object:
Sample code 1 (mutable iterator API):
if (your_key_is_unused(key)) {
}
}
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_next(yyjson_mut_obj_iter *iter)
Definition: yyjson.h:6495
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_remove(yyjson_mut_obj_iter *iter)
Definition: yyjson.h:6512
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_get_val(yyjson_mut_val *key)
Definition: yyjson.h:6507
yyjson_api_inline yyjson_mut_obj_iter yyjson_mut_obj_iter_with(yyjson_mut_val *obj)
Definition: yyjson.h:6484
Definition: yyjson.h:3292
Sample code 2 (mutable foreach macro):
size_t idx, max;
your_func(key, val);
}
Creating JSON Document
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:
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj(yyjson_mut_doc *doc)
Definition: yyjson.h:6561
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:5710
yyjson_api_inline bool yyjson_mut_obj_add(yyjson_mut_val *obj, yyjson_mut_val *key, yyjson_mut_val *val)
Definition: yyjson.h:6715
yyjson_api_inline bool yyjson_mut_arr_append(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:6116
Mutable Document
The following functions are used to create, modify, copy, and destroy a JSON document.
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_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:5374
yyjson_api bool yyjson_mut_doc_set_str_pool_size(yyjson_mut_doc *doc, size_t len)
JSON Value Creation
The following functions are used to create mutable JSON value, the value's memory is held by the document.
yyjson_api_inline yyjson_mut_val * yyjson_mut_true(yyjson_mut_doc *doc)
Definition: yyjson.h:5649
yyjson_api_inline yyjson_mut_val * yyjson_mut_real(yyjson_mut_doc *doc, double num)
Definition: yyjson.h:5715
yyjson_api_inline yyjson_mut_val * yyjson_mut_false(yyjson_mut_doc *doc)
Definition: yyjson.h:5660
yyjson_api_inline yyjson_mut_val * yyjson_mut_bool(yyjson_mut_doc *doc, bool val)
Definition: yyjson.h:5671
yyjson_api_inline yyjson_mut_val * yyjson_mut_null(yyjson_mut_doc *doc)
Definition: yyjson.h:5638
yyjson_api_inline yyjson_mut_val * yyjson_mut_uint(yyjson_mut_doc *doc, uint64_t num)
Definition: yyjson.h:5684
yyjson_api_inline yyjson_mut_val * yyjson_mut_sint(yyjson_mut_doc *doc, int64_t num)
Definition: yyjson.h:5697
JSON Array Creation
The following functions are used to create mutable JSON array.
int vals[3] = {-1, 0, 1};
const char strs[3] = {"Jan", "Feb", "Mar"};
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:5934
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:5981
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:5973
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:6039
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_float(yyjson_mut_doc *doc, const float *vals, size_t count)
Definition: yyjson.h:6013
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:5965
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_real(yyjson_mut_doc *doc, const double *vals, size_t count)
Definition: yyjson.h:5944
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:5957
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:5989
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_strcpy(yyjson_mut_doc *doc, const char **vals, size_t count)
Definition: yyjson.h:6049
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:6005
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:5939
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:5949
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:5997
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_double(yyjson_mut_doc *doc, const double *vals, size_t count)
Definition: yyjson.h:6021
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:6063
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_str(yyjson_mut_doc *doc, const char **vals, size_t count)
Definition: yyjson.h:6029
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_bool(yyjson_mut_doc *doc, const bool *vals, size_t count)
Definition: yyjson.h:5926
JSON Array Modification
The following functions are used to modify the contents of a JSON array.
yyjson_api_inline bool yyjson_mut_arr_add_str(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str)
Definition: yyjson.h:6377
yyjson_api_inline bool yyjson_mut_arr_add_true(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:6309
yyjson_api_inline bool yyjson_mut_arr_prepend(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:6135
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:6407
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove(yyjson_mut_val *arr, size_t idx)
Definition: yyjson.h:6182
yyjson_api_inline bool yyjson_mut_arr_clear(yyjson_mut_val *arr)
Definition: yyjson.h:6269
yyjson_api_inline bool yyjson_mut_arr_add_strcpy(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str)
Definition: yyjson.h:6397
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_replace(yyjson_mut_val *arr, size_t idx, yyjson_mut_val *val)
Definition: yyjson.h:6154
yyjson_api_inline bool yyjson_mut_arr_add_bool(yyjson_mut_doc *doc, yyjson_mut_val *arr, bool val)
Definition: yyjson.h:6327
yyjson_api_inline bool yyjson_mut_arr_add_uint(yyjson_mut_doc *doc, yyjson_mut_val *arr, uint64_t num)
Definition: yyjson.h:6337
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_add_arr(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:6417
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove_last(yyjson_mut_val *arr)
Definition: yyjson.h:6225
yyjson_api_inline bool yyjson_mut_arr_add_false(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:6318
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:6387
yyjson_api_inline bool yyjson_mut_arr_add_real(yyjson_mut_doc *doc, yyjson_mut_val *arr, double num)
Definition: yyjson.h:6367
yyjson_api_inline bool yyjson_mut_arr_add_val(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:6295
yyjson_api_inline bool yyjson_mut_arr_add_sint(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num)
Definition: yyjson.h:6347
yyjson_api_inline bool yyjson_mut_arr_remove_range(yyjson_mut_val *arr, size_t idx, size_t len)
Definition: yyjson.h:6247
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_add_obj(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:6426
yyjson_api_inline bool yyjson_mut_arr_insert(yyjson_mut_val *arr, yyjson_mut_val *val, size_t idx)
Definition: yyjson.h:6085
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove_first(yyjson_mut_val *arr)
Definition: yyjson.h:6206
yyjson_api_inline bool yyjson_mut_arr_add_null(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:6300
JSON Object Creation
The following functions are used to create mutable JSON object.
const char **keys,
const char **vals,
size_t count);
const char keys[] = {"name", "type", "id"};
const char *vals[] = {"Harry", "student", "123456"};
const char **kv_pairs,
size_t pair_count);
const char *pairs[] = {"name", "Harry", "type", "student", "id", "123456"};
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:6572
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:6603
JSON Object Modification
The following functions are used to modify the contents of a JSON object.
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:6979
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:6966
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:7037
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:6897
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:6941
yyjson_api_inline bool yyjson_mut_obj_add_false(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:6869
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:6907
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:6887
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove_str(yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:7005
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove(yyjson_mut_val *obj, yyjson_mut_val *key)
Definition: yyjson.h:6774
#define yyjson_api_inline
Definition: yyjson.h:372
yyjson_api_inline bool yyjson_mut_obj_add_null(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:6853
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:6987
yyjson_api_inline bool yyjson_mut_obj_add_true(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:6861
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:6927
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:6917
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:6877
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:6953
yyjson_api_inline bool yyjson_mut_obj_put(yyjson_mut_val *obj, yyjson_mut_val *key, yyjson_mut_val *val)
Definition: yyjson.h:6726
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove_strn(yyjson_mut_val *obj, const char *key, size_t len)
Definition: yyjson.h:7010
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:7028
yyjson_api_inline bool yyjson_mut_obj_clear(yyjson_mut_val *obj)
Definition: yyjson.h:6800
JSON Pointer and Patch
JSON Pointer
The library supports querying JSON values using JSON Pointer
(RFC 6901).
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_getn(yyjson_mut_doc *doc, const char *ptr, size_t len)
Definition: yyjson.h:7175
yyjson_api_inline yyjson_val * yyjson_ptr_getx(yyjson_val *val, const char *ptr, size_t len, yyjson_ptr_err *err)
Definition: yyjson.h:7151
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:7118
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_get(yyjson_mut_doc *doc, const char *ptr)
Definition: yyjson.h:7169
yyjson_api_inline yyjson_val * yyjson_doc_ptr_getn(yyjson_doc *doc, const char *ptr, size_t len)
Definition: yyjson.h:7113
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:7181
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_getn(yyjson_mut_val *val, const char *ptr, size_t len)
Definition: yyjson.h:7213
yyjson_api_inline yyjson_val * yyjson_ptr_get(yyjson_val *val, const char *ptr)
Definition: yyjson.h:7140
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_get(yyjson_mut_val *val, const char *ptr)
Definition: yyjson.h:7207
yyjson_api_inline yyjson_val * yyjson_doc_ptr_get(yyjson_doc *doc, const char *ptr)
Definition: yyjson.h:7107
yyjson_api_inline yyjson_val * yyjson_ptr_getn(yyjson_val *val, const char *ptr, size_t len)
Definition: yyjson.h:7146
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:7219
Definition: yyjson.h:3853
Definition: yyjson.h:3825
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[""]) |
if (!val2) printf(
"err %d: %s\n", err.
code, err.
msg);
const char * msg
Definition: yyjson.h:3829
yyjson_ptr_code code
Definition: yyjson.h:3827
The library also supports modifying JSON values using JSON Pointer
.
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_remove(yyjson_mut_doc *doc, const char *ptr)
Definition: yyjson.h:7527
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:7421
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:7450
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:7350
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:7317
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:7538
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_removen(yyjson_mut_val *val, const char *ptr, size_t len)
Definition: yyjson.h:7572
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:7505
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:7356
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:7406
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_ptr_removen(yyjson_mut_doc *doc, const char *ptr, size_t len)
Definition: yyjson.h:7533
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:7248
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:7578
yyjson_api_inline bool yyjson_mut_doc_ptr_set(yyjson_mut_doc *doc, const char *ptr, yyjson_mut_val *new_val)
Definition: yyjson.h:7343
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:7456
yyjson_api_inline yyjson_mut_val * yyjson_mut_ptr_remove(yyjson_mut_val *val, const char *ptr)
Definition: yyjson.h:7566
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:7310
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:7302
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:7414
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:7255
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:7494
yyjson_api_inline bool yyjson_mut_doc_ptr_add(yyjson_mut_doc *doc, const char *ptr, yyjson_mut_val *new_val)
Definition: yyjson.h:7241
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:7461
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:7500
For example:
All the above functions ending with x
can be used to get the result context ctx
, and the error message err
. For example:
if (err.
code) printf(
"err: %s\n", err.
msg);
yyjson_api_inline bool yyjson_mut_is_null(yyjson_mut_val *val)
Definition: yyjson.h:5393
yyjson_api_inline bool yyjson_ptr_ctx_remove(yyjson_ptr_ctx *ctx)
Definition: yyjson.h:7687
JSON Patch
The library supports JSON Patch (RFC 6902). Specification and example: https://tools.ietf.org/html/rfc6902
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)
Definition: yyjson.h:4413
JSON Merge Patch
The library supports JSON Merge Patch (RFC 7386). Specification and example: https://tools.ietf.org/html/rfc7386
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)
Number Processing
Number reader
The library has a built-in high-performance number reader,
it will read numbers according to these rules by default:
- Positive integers are read as
uint64_t
. If an overflow occurs, it is converted to double
.
- Negative integers are read as
int64_t
. If an overflow occurs, it is converted to double
.
- Floating-point numbers are read as
double
with correct rounding.
- If a
double
number overflow (reaches infinity), an error is reported.
- If a number does not conform to the JSON standard, 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_BIGBER_AS_RAW
: read big numbers (overflow or infinity) as raw strings without parsing.
See the Reader flag
section for more details.
Number writer
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:
- If the number is
Infinity
or NaN
, an error is reported.
- The negative sign of
-0.0
is preserved to maintain input information.
- The positive sign in the exponent part is removed.
- The floating-point number writer will generate the shortest correctly rounded decimal representation.
There are 2 flags that can be used to adjust the number writing strategy:
YYJSON_WRITE_ALLOW_INF_AND_NAN
write inf/nan numbers as Infinity
and NaN
literals without error (non-standard).
YYJSON_WRITE_INF_AND_NAN_AS_NULL
write inf/nan numbers as null
literal.
See the "Writer flag" section for more details.
Text Processing
Character Encoding
This library only supports UTF-8 encoding without BOM, as specified in RFC 8259:
JSON text exchanged between systems that are not part of a closed ecosystem MUST be encoded using UTF-8. Implementations MUST NOT add a byte order mark (U+FEFF) to the beginning of a networked-transmitted JSON text.
By default, yyjson performs strict UTF-8 encoding validation on input strings. If an invalid character is encountered, an error will be reported.
You can use YYJSON_READ_ALLOW_INVALID_UNICODE
and YYJSON_WRITE_ALLOW_INVALID_UNICODE
flags to allow invalid Unicode encoding. However, please note that if you enable these flags, the resulting value from yyjson may contain invalid characters, which can be used by other code and may introduce security risks.
NUL Character
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:
Memory Allocator
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:
Single allocator for multiple JSON
If you need to parse multiple small JSON one by one, you can use a single allocator to avoid multiple memory allocations.
Sample code:
size_t max_json_size = 64 * 1024;
void *buf = malloc(buf_size);
for(int i = 0, i < your_json_file_count; i++) {
const char *your_json_file_path = ...;
...
}
free(buf);
yyjson_api_inline size_t yyjson_read_max_memory_usage(size_t len, yyjson_read_flag flg)
Definition: yyjson.h:981
If you are not sure about the amount of memory required to process JSON, you can use the dynamic allocator.
for(int i = 0, i < your_json_file_count; i++) {
const char *your_json_file_path = ...;
...
}
yyjson_api yyjson_alc * yyjson_alc_dyn_new(void)
yyjson_api void yyjson_alc_dyn_free(yyjson_alc *alc)
Stack memory allocator
If the JSON is small enough, you can use stack memory to read or write it.
Sample code:
char buf[128 * 1024];
...
yyjson_doc_free(doc);
Use a third-party allocator library
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:
#include <mimalloc.h>
static void *priv_malloc(void *ctx, size_t size) {
return mi_malloc(size);
}
static void *priv_realloc(void *ctx, void *ptr, size_t old_size, size_t size) {
return mi_realloc(ptr, size);
}
static void priv_free(void *ctx, void *ptr) {
mi_free(ptr);
}
priv_malloc,
priv_realloc,
priv_free,
NULL
};
yyjson_doc *doc = yyjson_doc_read_opts(dat, len, 0, &PRIV_ALC, NULL);
...
yyjson_doc_free(doc);
char *json = yyjson_doc_write(doc, 0, alc, NULL, NULL);
...
alc->free(alc->
ctx, json);
Stack Memory Usage
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:
- Warning
- This function is recursive and may cause a stack overflow if the object level is too deep.
Null Check
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:
if (!str) printf("err!");
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;
if (unsafe_yyjson_equals_str(key, "id") &&
unsafe_yyjson_is_uint(val) &&
unsafe_yyjson_get_uint(val) == 1234) {
...
}
}
Thread Safety
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.
Locale Independence
The library is designed to be locale-independent.
However, there are certain conditions that you should be aware of:
- You use libc's
setlocale()
function to change the locale.
- Your environment does not adhere the IEEE 754 floating-point standard (e.g. some IBM mainframes), or you explicitly set
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.