yyjson 0.6.0
A high performance C JSON library.
Data Structures

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

  • Immutable data structures are returned when reading a JSON document. They cannot be modified.
  • Mutable data structures are created when building a JSON document. They can be modified.
  • yyjson also provides some functions for converting between these two types of data structures.

Note that the data structures described in this document are private, and you should use the 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 uni
Definition: yyjson.h:3475
uint64_t tag
Definition: yyjson.h:3474
Definition: yyjson.h:3473

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 have a 52-bit (4PB) physical address limit. Therefore, it is safe to store the type and size in a 64-bit 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_doc

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_doc

Mutable Value

Each mutable JSON value is stored in an yyjson_mut_val struct:

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
Definition: yyjson.h:4165
yyjson_val_uni uni
Definition: yyjson.h:4164
uint64_t tag
Definition: yyjson.h:4163
Definition: yyjson.h:4162

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 holds the tail of the circular linked list, so that yyjson can do append, prepend and remove_first in O(1) time.

For example:

yyjson_mut_doc