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:3788
yyjson_api_inline char * yyjson_mut_write(const yyjson_mut_doc *doc, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1083
yyjson_api_inline char * yyjson_write(const yyjson_doc *doc, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1003
yyjson_api_inline bool yyjson_mut_is_str(yyjson_mut_val *val)
Definition: yyjson.h:4320
Definition: yyjson.h:3478
Definition: yyjson.h:4206
Definition: yyjson.h:4162
Definition: yyjson.h:3473
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 null terminator, or you know the length of the string explicitly, 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:3870
yyjson_api_inline bool yyjson_equals_strn(yyjson_val *val, const char *str, size_t len)
Definition: yyjson.h:3877
When creating JSON, yyjson treats strings as constants for better performance. When your string will be modified, you should use a function with a cpy
to copy the string to the document, for example:
yyjson_api_inline yyjson_mut_val * yyjson_mut_strn(yyjson_mut_doc *doc, const char *str, size_t len)
Definition: yyjson.h:4620
yyjson_api_inline yyjson_mut_val * yyjson_mut_strncpy(yyjson_mut_doc *doc, const char *str, size_t len)
Definition: yyjson.h:4640
yyjson_api_inline yyjson_mut_val * yyjson_mut_strcpy(yyjson_mut_doc *doc, const char *str)
Definition: yyjson.h:4634
yyjson_api_inline yyjson_mut_val * yyjson_mut_str(yyjson_mut_doc *doc, const char *str)
Definition: yyjson.h:4614
Read JSON
The library provides 3 functions for reading JSON,
each function accepts an input of UTF-8 data or a file,
returns a document if it succeeds or returns 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:564
yyjson_api_inline yyjson_doc * yyjson_read(const char *dat, size_t len, yyjson_read_flag flg)
Definition: yyjson.h:741
Sample code:
const char *str = "[1,2,3,4]";
if (doc) {...}
yyjson_api_inline void yyjson_doc_free(yyjson_doc *doc)
Definition: yyjson.h:3734
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 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:598
static const yyjson_read_flag YYJSON_READ_ALLOW_COMMENTS
Definition: yyjson.h:594
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 real number is infinity.
- Report error if string contains invalid UTF-8 character or BOM.
- Report error on trailing commas, comments,
inf
and nan
literals.
● YYJSON_READ_INSITU
Read the input data in-situ.
This option allows the reader to modify and use input data to store string values, which can increase reading speed slightly. The caller should hold the input data before free the document. The input data must be padded by at least YYJSON_PADDING_SIZE
byte. For example: [1,2]
should be [1,2]\0\0\0\0
, 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:582
#define YYJSON_PADDING_SIZE
Definition: yyjson.h:463
● YYJSON_READ_STOP_WHEN_DONE
Stop when done instead of issues an error if there's additional content after a JSON document.
This option may used to parse small pieces of JSON in larger data, such as NDJSON.
Sample code:
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:3726
static const yyjson_read_flag YYJSON_READ_STOP_WHEN_DONE
Definition: yyjson.h:587
● YYJSON_READ_ALLOW_TRAILING_COMMAS
Allow single trailing comma at the end of an object or array, for example:
{
"a": 1,
"b": 2,
}
[
"a",
"b",
]
● YYJSON_READ_ALLOW_COMMENTS
Allow C-style single line and multiple line comments, for example:
{
"name": "Harry", // single line comment
"id": /* multiple line comment */ 123
}
● YYJSON_READ_ALLOW_INF_AND_NAN
Allow nan/inf number or literal (case-insensitive), such as 1e999, NaN, Inf, -Infinity, for example:
{
"large": 123e999,
"nan1": NaN,
"nan2": nan,
"inf1:" Inf,
"inf2": -Infinity
}
● YYJSON_READ_NUMBER_AS_RAW
Read numbers as raw strings without parsing, allowing you to keep arbitrarily large numbers.
You can use these functions to extract raw strings:
yyjson_api_inline bool yyjson_is_raw(yyjson_val *val)
Definition: yyjson.h:3748
yyjson_api_inline const char * yyjson_get_raw(yyjson_val *val)
Definition: yyjson.h:3838
yyjson_api_inline size_t yyjson_get_len(yyjson_val *val)
Definition: yyjson.h:3866
● YYJSON_READ_ALLOW_INVALID_UNICODE
Allow reading invalid unicode when parsing string values (non-standard), for example:
"\x80xyz"
"\xF0\x81\x81\x81"
Invalid characters will be allowed to appear in the string values, but invalid escape sequences will still be reported as errors. This flag does not affect the performance of correctly encoded strings.
Warning: strings in JSON values may contain incorrect encoding when this option is used, you need to handle these strings carefully to avoid security risks.
Write JSON
The library provides 3 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, 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:1164
yyjson_api_inline char * yyjson_mut_val_write(const yyjson_mut_val *val, yyjson_write_flag flg, size_t *len)
Definition: yyjson.h:1242
uint32_t yyjson_write_flag
Definition: yyjson.h:859
Sample code 1:
printf("%s\n", json);
free(json);
static const yyjson_write_flag YYJSON_WRITE_PRETTY
Definition: yyjson.h:869
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:4269
yyjson_api_inline bool yyjson_mut_arr_add_int(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num)
Definition: yyjson.h:5220
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:4758
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)
Sample code:
Write JSON with options
The doc/val
is JSON document or root value, if you pass NULL, you will get NULL result.
The flg
is writer flag, pass 0 if you don't need it, see writer flag
for details.
The alc
is memory allocator, pass NULL if you don't need it, see memory allocator
for details.
The len
is a pointer to receive output length, pass NULL if you don't need it.
The err
is a pointer to receive error message, pass NULL if you don't need it.
This function returns a new JSON string, or NULL if error occurs.
The string is encoded as UTF-8 with a null-terminator.
You should use free() or alc->free() to release it when it's no longer needed.
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:483
void * ctx
Definition: yyjson.h:485
const char * msg
Definition: yyjson.h:925
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:872
yyjson_write_code code
Definition: yyjson.h:923
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:
- Write JSON minify.
- Report error on inf or nan number.
- Report error on invalid UTF-8 string.
- Do not escape unicode or slash.
● YYJSON_WRITE_PRETTY
Write JSON pretty with 4 space indent.
● YYJSON_WRITE_ESCAPE_UNICODE
Escape unicode as \uXXXX
, make the output ASCII only, for example:
["Alizée, 😊"]
["Aliz\\u00E9e, \\uD83D\\uDE0A"]
● YYJSON_WRITE_ESCAPE_SLASHES
Escape /
as \/
, for example:
["https://github.com"]
["https:\/\/github.com"]
● YYJSON_WRITE_ALLOW_INF_AND_NAN
Write inf/nan number as Infinity
and NaN
literals 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
Write inf/nan number as null
literal 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
Allow invalid unicode when encoding string values.
Invalid characters in string value will be copied byte by byte. If YYJSON_WRITE_ESCAPE_UNICODE
flag is also set, invalid character will be escaped as \uFFFD
(replacement character).
This flag does not affect the performance of correctly encoded string.
Access JSON Document
JSON Document
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:3730
yyjson_api_inline yyjson_val * yyjson_doc_get_root(yyjson_doc *doc)
Definition: yyjson.h:3722
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
The following functions can be used to determine the type of a JSON value.
uint8_t yyjson_subtype
Definition: yyjson.h:444
yyjson_api_inline bool yyjson_is_ctn(yyjson_val *val)
Definition: yyjson.h:3800
yyjson_api_inline uint8_t yyjson_get_tag(yyjson_val *val)
Definition: yyjson.h:3818
yyjson_api_inline bool yyjson_is_bool(yyjson_val *val)
Definition: yyjson.h:3764
yyjson_api_inline bool yyjson_is_real(yyjson_val *val)
Definition: yyjson.h:3780
yyjson_api_inline const char * yyjson_get_type_desc(yyjson_val *val)
Definition: yyjson.h:3822
uint8_t yyjson_type
Definition: yyjson.h:433
yyjson_api_inline bool yyjson_is_int(yyjson_val *val)
Definition: yyjson.h:3776
yyjson_api_inline bool yyjson_is_true(yyjson_val *val)
Definition: yyjson.h:3756
yyjson_api_inline bool yyjson_is_false(yyjson_val *val)
Definition: yyjson.h:3760
yyjson_api_inline yyjson_subtype yyjson_get_subtype(yyjson_val *val)
Definition: yyjson.h:3814
yyjson_api_inline yyjson_type yyjson_get_type(yyjson_val *val)
Definition: yyjson.h:3810
yyjson_api_inline bool yyjson_is_null(yyjson_val *val)
Definition: yyjson.h:3752
yyjson_api_inline bool yyjson_is_sint(yyjson_val *val)
Definition: yyjson.h:3772
yyjson_api_inline bool yyjson_is_uint(yyjson_val *val)
Definition: yyjson.h:3768
yyjson_api_inline bool yyjson_is_arr(yyjson_val *val)
Definition: yyjson.h:3792
yyjson_api_inline bool yyjson_is_num(yyjson_val *val)
Definition: yyjson.h:3784
yyjson_api_inline bool yyjson_is_obj(yyjson_val *val)
Definition: yyjson.h:3796
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:3854
yyjson_api_inline double yyjson_get_real(yyjson_val *val)
Definition: yyjson.h:3858
yyjson_api_inline const char * yyjson_get_str(yyjson_val *val)
Definition: yyjson.h:3862
yyjson_api_inline bool yyjson_get_bool(yyjson_val *val)
Definition: yyjson.h:3842
yyjson_api_inline uint64_t yyjson_get_uint(yyjson_val *val)
Definition: yyjson.h:3846
yyjson_api_inline int64_t yyjson_get_sint(yyjson_val *val)
Definition: yyjson.h:3850
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:3899
yyjson_api_inline bool yyjson_set_raw(yyjson_val *val, const char *raw, size_t len)
Definition: yyjson.h:3892
yyjson_api_inline bool yyjson_set_uint(yyjson_val *val, uint64_t num)
Definition: yyjson.h:3911
yyjson_api_inline bool yyjson_set_str(yyjson_val *val, const char *str)
Definition: yyjson.h:3935
yyjson_api_inline bool yyjson_set_strn(yyjson_val *val, const char *str, size_t len)
Definition: yyjson.h:3942
yyjson_api_inline bool yyjson_set_real(yyjson_val *val, double num)
Definition: yyjson.h:3929
yyjson_api_inline bool yyjson_set_sint(yyjson_val *val, int64_t num)
Definition: yyjson.h:3917
yyjson_api_inline bool yyjson_set_bool(yyjson_val *val, bool num)
Definition: yyjson.h:3905
yyjson_api_inline bool yyjson_set_int(yyjson_val *val, int num)
Definition: yyjson.h:3923
JSON Array
The following functions can be used to access a JSON array.
Note that accessing elements by an 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:3956
yyjson_api_inline yyjson_val * yyjson_arr_get_last(yyjson_val *arr)
Definition: yyjson.h:3984
yyjson_api_inline yyjson_val * yyjson_arr_get(yyjson_val *arr, size_t idx)
Definition: yyjson.h:3960
yyjson_api_inline yyjson_val * yyjson_arr_get_first(yyjson_val *arr)
Definition: yyjson.h:3975
JSON Array Iterator
There are two ways to traverse an array:
Sample code 1 (iterator API):
your_func(val);
}
yyjson_api_inline bool yyjson_arr_iter_init(yyjson_val *arr, yyjson_arr_iter *iter)
Definition: yyjson.h:4012
yyjson_api_inline yyjson_val * yyjson_arr_iter_next(yyjson_arr_iter *iter)
Definition: yyjson.h:4028
Definition: yyjson.h:4006
Sample code 2 (foreach macro):
size_t idx, max;
your_func(idx, val);
}
#define yyjson_arr_foreach(arr, idx, max, val)
Definition: yyjson.h:1537
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:4735
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_iter_next(yyjson_mut_arr_iter *iter)
Definition: yyjson.h:4723
yyjson_api_inline bool yyjson_mut_arr_iter_init(yyjson_mut_val *arr, yyjson_mut_arr_iter *iter)
Definition: yyjson.h:4705
Definition: yyjson.h:4697
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:2164
JSON Object
The following functions can be used to access a JSON object.
Note that accessing elements by a 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:4049
yyjson_api_inline yyjson_val * yyjson_obj_iter_get(yyjson_obj_iter *iter, const char *key)
Definition: yyjson.h:4116
yyjson_api_inline yyjson_val * yyjson_obj_getn(yyjson_val *obj, const char *key, size_t key_len)
Definition: yyjson.h:4054
yyjson_api_inline bool yyjson_obj_iter_init(yyjson_val *obj, yyjson_obj_iter *iter)
Definition: yyjson.h:4085
yyjson_api_inline size_t yyjson_obj_size(yyjson_val *obj)
Definition: yyjson.h:4045
Definition: yyjson.h:4078
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:4112
yyjson_api_inline yyjson_val * yyjson_obj_iter_next(yyjson_obj_iter *iter)
Definition: yyjson.h:4102
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:1694
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:5363
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_remove(yyjson_mut_obj_iter *iter)
Definition: yyjson.h:5380
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_iter_get_val(yyjson_mut_val *key)
Definition: yyjson.h:5375
yyjson_api_inline bool yyjson_mut_obj_iter_init(yyjson_mut_val *obj, yyjson_mut_obj_iter *iter)
Definition: yyjson.h:5345
Definition: yyjson.h:5337
Sample code 2 (mutable foreach macro):
size_t idx, max;
your_func(key, val);
}
JSON Pointer
The library supports querying JSON values via JSON Pointer
(RFC 6901).
yyjson_api_inline yyjson_val * yyjson_get_pointer(yyjson_val *val, const char *ptr)
Definition: yyjson.h:5927
yyjson_api_inline yyjson_mut_val * yyjson_mut_get_pointer(yyjson_mut_val *val, const char *ptr)
Definition: yyjson.h:5953
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_get_pointer(yyjson_mut_doc *doc, const char *ptr)
Definition: yyjson.h:5964
yyjson_api_inline yyjson_mut_val * yyjson_mut_doc_get_pointern(yyjson_mut_doc *doc, const char *ptr, size_t len)
Definition: yyjson.h:5959
yyjson_api_inline yyjson_val * yyjson_doc_get_pointern(yyjson_doc *doc, const char *ptr, size_t len)
Definition: yyjson.h:5933
yyjson_api_inline yyjson_val * yyjson_get_pointern(yyjson_val *val, const char *ptr, size_t len)
Definition: yyjson.h:5918
yyjson_api_inline yyjson_mut_val * yyjson_mut_get_pointern(yyjson_mut_val *val, const char *ptr, size_t len)
Definition: yyjson.h:5944
yyjson_api_inline yyjson_val * yyjson_doc_get_pointer(yyjson_doc *doc, const char *ptr)
Definition: yyjson.h:5939
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[""]) |
Create JSON Document
yyjson_mut_doc
and related APIs are used to build JSON documents.
Notice 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. Thus yyjson_mut_doc
is more suitable for write-once than mutation of an existing document.
JSON objects and arrays are made up 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:5430
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:4596
yyjson_api_inline bool yyjson_mut_obj_add(yyjson_mut_val *obj, yyjson_mut_val *key, yyjson_mut_val *val)
Definition: yyjson.h:5586
yyjson_api_inline bool yyjson_mut_arr_append(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:4979
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_inline yyjson_mut_val * yyjson_mut_doc_get_root(yyjson_mut_doc *doc)
Definition: yyjson.h:4265
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:4536
yyjson_api_inline yyjson_mut_val * yyjson_mut_real(yyjson_mut_doc *doc, double num)
Definition: yyjson.h:4601
yyjson_api_inline yyjson_mut_val * yyjson_mut_false(yyjson_mut_doc *doc)
Definition: yyjson.h:4547
yyjson_api_inline yyjson_mut_val * yyjson_mut_bool(yyjson_mut_doc *doc, bool val)
Definition: yyjson.h:4558
yyjson_api_inline yyjson_mut_val * yyjson_mut_null(yyjson_mut_doc *doc)
Definition: yyjson.h:4525
yyjson_api_inline yyjson_mut_val * yyjson_mut_uint(yyjson_mut_doc *doc, uint64_t num)
Definition: yyjson.h:4570
yyjson_api_inline yyjson_mut_val * yyjson_mut_sint(yyjson_mut_doc *doc, int64_t num)
Definition: yyjson.h:4583
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:4797
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:4844
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:4836
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:4902
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_float(yyjson_mut_doc *doc, const float *vals, size_t count)
Definition: yyjson.h:4876
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:4828
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_real(yyjson_mut_doc *doc, const double *vals, size_t count)
Definition: yyjson.h:4807
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:4820
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:4852
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_strcpy(yyjson_mut_doc *doc, const char **vals, size_t count)
Definition: yyjson.h:4912
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:4868
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:4802
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:4812
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:4860
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_double(yyjson_mut_doc *doc, const double *vals, size_t count)
Definition: yyjson.h:4884
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:4926
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_str(yyjson_mut_doc *doc, const char **vals, size_t count)
Definition: yyjson.h:4892
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_with_bool(yyjson_mut_doc *doc, const bool *vals, size_t count)
Definition: yyjson.h:4790
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:5240
yyjson_api_inline bool yyjson_mut_arr_add_true(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:5172
yyjson_api_inline bool yyjson_mut_arr_prepend(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:4998
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:5270
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove(yyjson_mut_val *arr, size_t idx)
Definition: yyjson.h:5045
yyjson_api_inline bool yyjson_mut_arr_clear(yyjson_mut_val *arr)
Definition: yyjson.h:5132
yyjson_api_inline bool yyjson_mut_arr_add_strcpy(yyjson_mut_doc *doc, yyjson_mut_val *arr, const char *str)
Definition: yyjson.h:5260
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_replace(yyjson_mut_val *arr, size_t idx, yyjson_mut_val *val)
Definition: yyjson.h:5017
yyjson_api_inline bool yyjson_mut_arr_add_bool(yyjson_mut_doc *doc, yyjson_mut_val *arr, bool val)
Definition: yyjson.h:5190
yyjson_api_inline bool yyjson_mut_arr_add_uint(yyjson_mut_doc *doc, yyjson_mut_val *arr, uint64_t num)
Definition: yyjson.h:5200
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_add_arr(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:5280
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove_last(yyjson_mut_val *arr)
Definition: yyjson.h:5088
yyjson_api_inline bool yyjson_mut_arr_add_false(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:5181
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:5250
yyjson_api_inline bool yyjson_mut_arr_add_real(yyjson_mut_doc *doc, yyjson_mut_val *arr, double num)
Definition: yyjson.h:5230
yyjson_api_inline bool yyjson_mut_arr_add_val(yyjson_mut_val *arr, yyjson_mut_val *val)
Definition: yyjson.h:5158
yyjson_api_inline bool yyjson_mut_arr_add_sint(yyjson_mut_doc *doc, yyjson_mut_val *arr, int64_t num)
Definition: yyjson.h:5210
yyjson_api_inline bool yyjson_mut_arr_remove_range(yyjson_mut_val *arr, size_t idx, size_t len)
Definition: yyjson.h:5110
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_add_obj(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:5289
yyjson_api_inline bool yyjson_mut_arr_insert(yyjson_mut_val *arr, yyjson_mut_val *val, size_t idx)
Definition: yyjson.h:4948
yyjson_api_inline yyjson_mut_val * yyjson_mut_arr_remove_first(yyjson_mut_val *arr)
Definition: yyjson.h:5069
yyjson_api_inline bool yyjson_mut_arr_add_null(yyjson_mut_doc *doc, yyjson_mut_val *arr)
Definition: yyjson.h:5163
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:5441
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:5472
JSON Object Modification
The following functions are used to modify the contents of a JSON object.
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:5823
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:5879
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:5757
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:5798
yyjson_api_inline bool yyjson_mut_obj_add_false(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:5730
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:5767
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:5747
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove_str(yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:5846
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove(yyjson_mut_val *obj, yyjson_mut_val *key)
Definition: yyjson.h:5635
#define yyjson_api_inline
Definition: yyjson.h:266
yyjson_api_inline bool yyjson_mut_obj_add_null(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:5714
yyjson_api_inline bool yyjson_mut_obj_add_true(yyjson_mut_doc *doc, yyjson_mut_val *obj, const char *key)
Definition: yyjson.h:5722
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:5787
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:5777
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:5738
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:5810
yyjson_api_inline bool yyjson_mut_obj_put(yyjson_mut_val *obj, yyjson_mut_val *key, yyjson_mut_val *val)
Definition: yyjson.h:5597
yyjson_api_inline yyjson_mut_val * yyjson_mut_obj_remove_strn(yyjson_mut_val *obj, const char *key, size_t len)
Definition: yyjson.h:5851
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:5870
yyjson_api_inline bool yyjson_mut_obj_clear(yyjson_mut_val *obj)
Definition: yyjson.h:5664
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 parse numbers according to these rules by default:
- Read positive integer as
uint64_t
, if overflow, convert to double
.
- Read negative integer as
int64_t
, if overflow, convert to double
.
- Read floating-point number as
double
with correct rounding (no ulp error).
- If a
real
number overflow (infinity), it will report an error.
- If a number does not match the JSON standard, it will report an error.
You can use YYJSON_READ_ALLOW_INF_AND_NAN
flag to allow nan
and inf
number/literal. You can also use YYJSON_READ_NUMBER_AS_RAW
to read numbers as raw strings without parsing them. See Reader flag
for details.
Number writer
The library has a built-in high-performance number writer,
it will write numbers according to these rules by default:
- Write positive integer without sign.
- Write negative integer with a negative sign.
- Write floating-point number with ECMAScript format, but with the following changes:
- If number is
Infinity
or NaN
, report an error.
- Keep the negative sign of 0.0 to preserve input information.
- Remove positive sign of exponent part.
- Floating-point number writer should generate shortest correctly rounded decimal representation.
You can use YYJSON_WRITE_ALLOW_INF_AND_NAN
flag to write inf/nan number as Infinity
and NaN
literals without error, but this is not standard JSON. You can also use YYJSON_WRITE_INF_AND_NAN_AS_NULL
to write inf/nan number as null
literal. See Writer flag
for details.
Text Processing
Character Encoding
The 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 a strict UTF-8 encoding validation on input strings. An error will be reported when an invalid character is encountered.
You could use YYJSON_READ_ALLOW_INVALID_UNICODE
and YYJSON_WRITE_ALLOW_INVALID_UNICODE
flags to allow invalid unicode encoding. However, you should be aware that the result value from yyjson may contain invalid characters, which can be used by other code and may pose security risks.
NUL Character
The library supports the NUL
character (also known as null terminator
, or Unicode U+0000
, ASCII \0
) inside strings.
When reading JSON, \u0000
will be unescaped to NUL
. If a string contains NUL
, the length obtained with strlen() will be inaccurate, and you should use yyjson_get_len() to get the actual length.
When building JSON, the input string is treated as null-terminated. If you need to pass in a string with NUL
inside, you should use the API with the n
suffix and pass in the actual length.
For example:
Memory Allocator
The library does not call libc's memory allocation functions (malloc/realloc/free) directly. 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.
Custom memory allocator allows you to take more control over memory allocation, here are a few examples:
Single allocator for multiple JSON
If you need to parse multiple small JSON, you can use a single allocator with pre-allocated buffer to avoid frequent memory allocation.
Sample code:
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:785
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 third-party allocator library
You can use a third-party high-performance memory allocator for yyjson,
such as jemalloc, tcmalloc, mimalloc.
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 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);
Null Check
The library's public API will do null check
for every input parameter to avoid crashes.
For example, when reading a JSON, you don't need to do null check or type check on each value:
if (!str) printf("err!");
But if you are sure that a value is non-null and the type is matched, you can use the unsafe
prefix API to avoid the null check.
For example, when iterating over an array or object, the value and key must be non-null:
size_t idx, max;
if (unsafe_yyjson_equals_str(key, "id") &&
unsafe_yyjson_is_uint(val) &&
unsafe_yyjson_get_uint(val) == 1234) {
...
}
}
Thread Safe
The library does not use global variables, so if you can ensure that the input parameters of a function are thread-safe, then the function calls are also thread-safe.
Typically, 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 Dependent
The library is locale-independent.
However, there are some special conditions that you need to be aware of:
- You use libc's
setlocale()
function to change locale.
- Your environment does not use IEEE 754 floating-point standard (e.g. some IBM mainframes), or you explicitly set
YYJSON_DISABLE_FAST_FP_CONV
during build, in which case yyjson will use strtod()
to parse floating-point numbers.
When you meet both of these conditions, you should avoid calling setlocale()
while other thread is parsing JSON, otherwise an error may be returned for JSON floating point number parsing.