yyjson 0.5.0 A high performance C JSON library.

Data Structures

yyjson has 2 types of data structures: immutable and mutable.

When reading a JSON, yyjson returns immutable document and values;
When building a JSON, yyjson creates mutable document and values.
yyjson also provides some methods to convert immutable document into mutable document.
Note that the data structures described in this document are private, and you should use public API to access them.

# Immutable Value

Each JSON value is stored in an immutable `yyjson_val` struct:

struct yyjson_val {
uint64_t tag;
union {
uint64_t u64;
int64_t i64;
double f64;
const char *str;
void *ptr;
size_t ofs;
} uni;
}
yyjson_val::uni
yyjson_val_uni uni
Definition: yyjson.h:3271
yyjson_val::tag
uint64_t tag
Definition: yyjson.h:3270
yyjson_val
Definition: yyjson.h:3269

The lower 8 bits of `tag` stores the type of value.
The higher 56 bits of `tag` stores the size of value (string length, object size or array size).

Modern 64-bit processors are typically limited to supporting fewer than 64 bits for RAM addresses (Wikipedia). For example, Intel64, AMD64 and ARMv8 has a 52-bit (4PB) physical address limit. So we can safely store type and size into a 64 bits `tag`.

# Immutable Document

A JSON document stores all strings in a contiguous memory area.
Each string is unescaped in-place and ended with a null-terminator.
For example:

yyjson_val

A JSON document stores all values in another contiguous memory area.
The `object` and `array` stores their own memory usage, so we can easily walk through a container's child values.
For example:

yyjson_val

# Mutable Value

Each mutable JSON value is stored in an `yyjson_mut_val` struct:

struct yyjson_mut_val {
uint64_t tag;
union {
uint64_t u64;
int64_t i64;
double f64;
const char *str;
void *ptr;
size_t ofs;
} uni;
yyjson_mut_val *next;
}
yyjson_mut_val::next
yyjson_mut_val * next
Definition: yyjson.h:3832
yyjson_mut_val::uni
yyjson_val_uni uni
Definition: yyjson.h:3831
yyjson_mut_val::tag
uint64_t tag
Definition: yyjson.h:3830
yyjson_mut_val
Definition: yyjson.h:3829

The `tag` and `uni` field is same as immutable value, the `next` field is used to build linked list.

# Mutable Document

A mutable JSON document is composed of multiple `yyjson_mut_val`.

The child values of an `object` or `array` are linked as a cycle,
the parent hold the tail of the linked list, so yyjson can do `append`, `prepend` and `remove_first` in O(1) time.

For example:

yyjson_val