yyjson Documentation

yyjson uses two distinct types of data structures depending on whether you are reading or building JSON:

1. Immutable structures (yyjson_doc and yyjson_val): Returned when reading an existing JSON document. These cannot be modified after creation.
2. Mutable structures (yyjson_mut_doc and yyjson_mut_val): Used when building a new JSON document from scratch. These can be modified (e.g., appending or removing elements).

While yyjson provides functions to convert between these types, it is recommended to use the public API rather than accessing these structs directly.

yyjson uses two types of data structures depending on whether you are reading or building JSON:

Key Concepts:

• Immutable: Returned when reading JSON. The document holds the memory for all values and strings.
• Mutable: Used when building JSON.
• Conversion: You can convert between them using yyjson_doc_mut_copy (doc $\rightarrow$ mut_doc), yyjson_val_mut_copy (val $\rightarrow$ mut_val), yyjson_mut_doc_imut_copy (mut_doc $\rightarrow$ doc), and yyjson_mut_val_imut_copy (mut_val $\rightarrow$ val).
• API Pattern: For most immutable APIs, you can access the mutable version by adding mut after the prefix (e.g., yyjson_is_str $\rightarrow$ yyjson_mut_is_str).

To improve reading speed, use the YYJSON_READ_INSITU flag. This allows the reader to use the input buffer itself to store string values.

Critical Requirements:

1. The input buffer must be padded with at least YYJSON_PADDING_SIZE bytes (typically 4).
2. The caller must ensure the input buffer is not freed until yyjson_doc_free() has been called.
3. The input buffer must be held until the document is no longer needed.

size_t dat_len = ...;
char *buf = malloc(dat_len + YYJSON_PADDING_SIZE); // create a buffer larger than (len + 4)
read_from_socket(buf, ...);
memset(buf + dat_len, 0, YYJSON_PADDING_SIZE); // set 4-byte padding after data

yyjson_doc *doc = yyjson_read_opts(buf, dat_len, YYJSON_READ_INSITU, NULL, NULL);
if (doc) {...}
yyjson_doc_free(doc);
free(buf); // the input data should be freed after the document.

To build yyjson without a libc (e.g., for WebAssembly targets without a libc sysroot), define YYJSON_FREESTANDING as 1.

When using this mode:

• string.h functions like memcpy, memmove, memset, memcmp, and strlen are provided via built-in inline fallbacks.
• File and FILE pointer APIs are disabled (equivalent to YYJSON_DISABLE_FILE).
• malloc and free are unavailable. You must either pass a yyjson_alc allocator to compatible APIs or define a global default at compile time using -DYYJSON_CUSTOM_ALC=my_alc.
• If you have custom implementations for string functions, you can define YYJSON_FREESTANDING_HEADER to point to your custom header.

The standard public APIs perform null checks on every input parameter to prevent crashes. If you are certain a value is non-null and matches the expected type (e.g., when iterating over a known valid JSON structure), you can use the unsafe_ prefix API to improve performance.

Example:

size_t idx, max;
yyjson_val *key, *val;
yyjson_obj_foreach(obj, idx, max, key, val) {
    // using unsafe_ prefix to skip checks
    if (unsafe_yyjson_equals_str(key, "id") &&
        unsafe_yyjson_is_uint(val) &&
        unsafe_yyjson_get_uint(val) == 1234) {
        ...
    }
}

Memory management in yyjson is document-centric. A JSON document (yyjson_doc or yyjson_mut_doc) owns the memory for all its contained values and strings.

• Freeing memory: You must call yyjson_doc_free() for immutable documents or yyjson_mut_doc_free() for mutable documents when they are no longer needed.
• Value lifetime: Individual JSON values (yyjson_val or yyjson_mut_val) share the lifetime of their parent document. You cannot free a value independently; it will be freed automatically when the document is freed.

To build the library from source using CMake, create a build directory and run the build commands. You can choose to build either a static or a shared library.

# Create build directory
git clone https://github.com/ibireme/yyjson.git
cmake -E make_directory build; cd build

# Build static library
cmake .. 
cmake --build .

# Build shared library
cmake .. -DBUILD_SHARED_LIBS=ON
cmake --build .

You can use the vcpkg dependency manager to install yyjson by following these steps:

git clone https://github.com/Microsoft/vcpkg.git
cd vcpkg
./bootstrap-vcpkg.sh  # ./bootstrap-vcpkg.bat for PowerShell
./vcpkg integrate install
./vcpkg install yyjson