Awesome

Introduction

A high performance JSON library written in ANSI C.

Features

• Fast: can read or write gigabytes per second JSON data on modern CPUs.
• Portable: complies with ANSI C (C89) for cross-platform compatibility.
• Strict: complies with RFC 8259 JSON standard, ensuring strict number format and UTF-8 validation.
• Extendable: offers options to allow comments, trailing commas, NaN/Inf, and custom memory allocator.
• Accuracy: can accurately read and write int64, uint64, and double numbers.
• Flexible: supports unlimited JSON nesting levels, \u0000 characters, and non null-terminated strings.
• Manipulation: supports querying and modifying using JSON Pointer, JSON Patch and JSON Merge Patch.
• Developer-Friendly: easy integration with only one h and one c file.

Limitations

• An array or object is stored as a data structure such as linked list, which makes accessing elements by index or key slower than using an iterator.
• Duplicate keys are allowed in an object, and the order of the keys is preserved.
• JSON parsing result is immutable, requiring a mutable copy for modification.

Performance

Benchmark project and dataset: yyjson_benchmark

The simdjson's new On Demand API is faster if most JSON fields are known at compile-time. This benchmark project only checks the DOM API, a new benchmark will be added later.

AWS EC2 (AMD EPYC 7R32, gcc 9.3)

iPhone (Apple A14, clang 12)

More benchmark reports with interactive charts (update 2020-12-12)

For better performance, yyjson prefers:

• A modern processor with:
  • high instruction level parallelism
  • excellent branch predictor
  • low penalty for misaligned memory access
• A modern compiler with good optimizer (e.g. clang)

Sample Code

Read JSON string

const char *json = "{\"name\":\"Mash\",\"star\":4,\"hits\":[2,2,1,3]}";

// Read JSON and get root
yyjson_doc *doc = yyjson_read(json, strlen(json), 0);
yyjson_val *root = yyjson_doc_get_root(doc);

// Get root["name"]
yyjson_val *name = yyjson_obj_get(root, "name");
printf("name: %s\n", yyjson_get_str(name));
printf("name length:%d\n", (int)yyjson_get_len(name));

// Get root["star"]
yyjson_val *star = yyjson_obj_get(root, "star");
printf("star: %d\n", (int)yyjson_get_int(star));

// Get root["hits"], iterate over the array
yyjson_val *hits = yyjson_obj_get(root, "hits");
size_t idx, max;
yyjson_val *hit;
yyjson_arr_foreach(hits, idx, max, hit) {
    printf("hit%d: %d\n", (int)idx, (int)yyjson_get_int(hit));
}

// Free the doc
yyjson_doc_free(doc);

// All functions accept NULL input, and return NULL on error.

Write JSON string

// Create a mutable doc
yyjson_mut_doc *doc = yyjson_mut_doc_new(NULL);
yyjson_mut_val *root = yyjson_mut_obj(doc);
yyjson_mut_doc_set_root(doc, root);

// Set root["name"] and root["star"]
yyjson_mut_obj_add_str(doc, root, "name", "Mash");
yyjson_mut_obj_add_int(doc, root, "star", 4);

// Set root["hits"] with an array
int hits_arr[] = {2, 2, 1, 3};
yyjson_mut_val *hits = yyjson_mut_arr_with_sint32(doc, hits_arr, 4);
yyjson_mut_obj_add_val(doc, root, "hits", hits);

// To string, minified
const char *json = yyjson_mut_write(doc, 0, NULL);
if (json) {
    printf("json: %s\n", json); // {"name":"Mash","star":4,"hits":[2,2,1,3]}
    free((void *)json);
}

// Free the doc
yyjson_mut_doc_free(doc);

Read JSON file with options

// Read JSON file, allowing comments and trailing commas
yyjson_read_flag flg = YYJSON_READ_ALLOW_COMMENTS | YYJSON_READ_ALLOW_TRAILING_COMMAS;
yyjson_read_err err;
yyjson_doc *doc = yyjson_read_file("/tmp/config.json", flg, NULL, &err);

// Iterate over the root object
if (doc) {
    yyjson_val *obj = yyjson_doc_get_root(doc);
    yyjson_obj_iter iter;
    yyjson_obj_iter_init(obj, &iter);
    yyjson_val *key, *val;
    while ((key = yyjson_obj_iter_next(&iter))) {
        val = yyjson_obj_iter_get_val(key);
        printf("%s: %s\n", yyjson_get_str(key), yyjson_get_type_desc(val));
    }
} else {
    printf("read error (%u): %s at position: %ld\n", err.code, err.msg, err.pos);
}

// Free the doc
yyjson_doc_free(doc);

Write JSON file with options

// Read the JSON file as a mutable doc
yyjson_doc *idoc = yyjson_read_file("/tmp/config.json", 0, NULL, NULL);
yyjson_mut_doc *doc = yyjson_doc_mut_copy(idoc, NULL);
yyjson_mut_val *obj = yyjson_mut_doc_get_root(doc);

// Remove null values in root object
yyjson_mut_obj_iter iter;
yyjson_mut_obj_iter_init(obj, &iter);
yyjson_mut_val *key, *val;
while ((key = yyjson_mut_obj_iter_next(&iter))) {
    val = yyjson_mut_obj_iter_get_val(key);
    if (yyjson_mut_is_null(val)) {
        yyjson_mut_obj_iter_remove(&iter);
    }
}

// Write the json pretty, escape unicode
yyjson_write_flag flg = YYJSON_WRITE_PRETTY | YYJSON_WRITE_ESCAPE_UNICODE;
yyjson_write_err err;
yyjson_mut_write_file("/tmp/config.json", doc, flg, NULL, &err);
if (err.code) {
    printf("write error (%u): %s\n", err.code, err.msg);
}

// Free the doc
yyjson_doc_free(idoc);
yyjson_mut_doc_free(doc);

Documentation

The latest (unreleased) documentation can be accessed in the doc directory. The pre-generated Doxygen HTML for the release version can be viewed here:

• Home Page
  • Build and test
  • API and sample code
  • Data structure
  • Changelog

Packaging status

Built With yyjson

A non-exhaustive list of projects that expose yyjson to other languages or use yyjson internally for a major feature. If you have a project that uses yyjson, feel free to open a PR to add it to this list.

TODO for v1.0

• Add documentation page.
• Add GitHub workflow for CI and codecov.
• Add more tests: valgrind, sanitizer, fuzzing.
• Support JSON Pointer to query and modify JSON.
• Add RAW type for JSON reader and writer.
• Add option to limit real number output precision.
• Add option to support JSON5 (if feasible).
• Add functions to diff two JSON documents.
• Add documentation on performance optimizations.
• Ensure ABI stability.

License

This project is released under the MIT license.