JSON reader, writer and DOM utilities for Linux C11 with a C++11-compatible API. More...
#include <stddef.h>#include <stdint.h>

Go to the source code of this file.
Data Structures | |
| struct | jsonbourne_str |
| Decoded UTF-8 bytes; len, not strlen(), determines the string's extent. More... | |
| struct | jsonbourne_str_loc |
| String view followed by optional source coordinates. More... | |
| struct | jsonbourne_num |
| Original number spelling, retained so reading never rounds through a double. More... | |
| struct | jsonbourne_obj_entry |
| One object member; linked order and duplicate decoded keys are retained. More... | |
| struct | jsonbourne_obj |
| Ordered object members; len must exactly match the linked-list length. More... | |
| struct | jsonbourne_arr_entry |
| One array element in source order. More... | |
| struct | jsonbourne_arr |
| Ordered array elements; explicit length supports bounded traversal. More... | |
| struct | jsonbourne_val |
| Tagged DOM value; children and text borrow the root allocation's lifetime. More... | |
| struct | jsonbourne_val_loc |
| Value view followed by coordinates recorded only with TRACK_LOCATION. More... | |
| struct | jsonbourne_read_err |
| Optional read result; coordinates describe the parser's failure cursor. More... | |
| struct | jsonbourne_read_limits |
| Per-read budgets checked during validation, before a DOM is allocated. More... | |
Macros | |
| #define | JSONBOURNE_VERSION_MAJOR 1 |
| Major API version component. | |
| #define | JSONBOURNE_VERSION_MINOR 0 |
| Minor API version component. | |
| #define | JSONBOURNE_VERSION_PATCH 1 |
| Patch version component. | |
| #define | JSONBOURNE_VERSION_HEX ((JSONBOURNE_VERSION_MAJOR << 16) | (JSONBOURNE_VERSION_MINOR << 8) | JSONBOURNE_VERSION_PATCH) |
| Packed major/minor/patch version for compile-time comparisons. | |
| #define | JSONBOURNE_VERSION_STRING "1.0.1" |
| Human-readable header version; query jsonbourne_version() for the linked object. | |
| #define | JSONBOURNE_READER_DEPTH_LIMIT 999 |
| Maximum simultaneous open reader containers; must be positive. | |
| #define | JSONBOURNE_WRITER_DEPTH_LIMIT JSONBOURNE_READER_DEPTH_LIMIT |
| Positive writer/copy nesting bound, defaulting to the reader bound. | |
| #define | JSONBOURNE_MAX_HEX_DIGITS 1024 |
| Maximum significant hexadecimal digits converted to decimal output. | |
| #define | JSONBOURNE_DISABLE_SIMD 0 |
| Set to 1 to exercise the scalar path or omit architecture-specific intrinsics. | |
| #define | JSONBOURNE_API |
| Optional declaration annotation for a consumer's visibility/export policy. | |
| #define | JSONBOURNE_READ_ALLOW_EXT_NUMBER |
| Numeric spelling extensions; does not by itself permit Infinity or NaN. | |
Typedefs | |
| typedef size_t | jsonbourne_read_flag |
| Read-option bitmask; combine named options with bitwise OR. | |
| typedef enum jsonbourne_type | jsonbourne_type |
| Payload tag; literals need no separately allocated payload. | |
| typedef struct jsonbourne_str | jsonbourne_str |
| Decoded UTF-8 bytes; len, not strlen(), determines the string's extent. | |
| typedef struct jsonbourne_str_loc | jsonbourne_str_loc |
| String view followed by optional source coordinates. | |
| typedef struct jsonbourne_num | jsonbourne_num |
| Original number spelling, retained so reading never rounds through a double. | |
| typedef struct jsonbourne_val | jsonbourne_val |
| Forward name for values referenced by recursive container entries. | |
| typedef struct jsonbourne_obj_entry | jsonbourne_obj_entry |
| Forward name allowing an object entry to link to its own type. | |
| typedef struct jsonbourne_obj | jsonbourne_obj |
| Ordered object members; len must exactly match the linked-list length. | |
| typedef struct jsonbourne_arr_entry | jsonbourne_arr_entry |
| Forward name allowing an array entry to link to its own type. | |
| typedef struct jsonbourne_arr | jsonbourne_arr |
| Ordered array elements; explicit length supports bounded traversal. | |
| typedef struct jsonbourne_val_loc | jsonbourne_val_loc |
| Value view followed by coordinates recorded only with TRACK_LOCATION. | |
| typedef size_t | jsonbourne_read_code |
| Stable storage type for a diagnostic code, separate from display text. | |
| typedef struct jsonbourne_read_err | jsonbourne_read_err |
| Optional read result; coordinates describe the parser's failure cursor. | |
| typedef struct jsonbourne_read_limits | jsonbourne_read_limits |
| Per-read budgets checked during validation, before a DOM is allocated. | |
Functions | |
| JSONBOURNE_API uint32_t | jsonbourne_version (void) |
| Query the linked implementation rather than the including header. | |
| JSONBOURNE_API struct jsonbourne_read_limits | jsonbourne_read_limits_default (void) |
| Create default budgets using the linked implementation's reader limit. | |
| JSONBOURNE_API int | jsonbourne_read_measure (const void *src, size_t len, jsonbourne_read_flag flg, const jsonbourne_read_limits *limits, size_t *required, jsonbourne_read_err *err) |
| Validate input and measure the exact single-allocation DOM size. | |
| JSONBOURNE_API int | jsonbourne_read_validate (const void *src, size_t len, jsonbourne_read_flag flg, const jsonbourne_read_limits *limits, jsonbourne_read_err *err) |
| Validate the entire extent without allocating a DOM or changing input. | |
| JSONBOURNE_API jsonbourne_val * | jsonbourne_read_buf (const void *src, size_t len, jsonbourne_read_flag flg, const jsonbourne_read_limits *limits, void *buf, size_t cap, size_t *required, jsonbourne_read_err *err) |
| Read a DOM into aligned caller storage without heap allocation. | |
| JSONBOURNE_API jsonbourne_val * | jsonbourne_read_opts_with_limits (const void *src, size_t len, jsonbourne_read_flag flg, const jsonbourne_read_limits *limits, void *(*alc_fn)(void *, size_t), void *alc_ctx, jsonbourne_read_err *err) |
| Validate against explicit budgets, then allocate the entire DOM once. | |
| JSONBOURNE_API jsonbourne_val * | jsonbourne_read_opts (const void *src, size_t len, jsonbourne_read_flag flg, void *(*alc_fn)(void *, size_t), void *alc_ctx, jsonbourne_read_err *err) |
| Read with named options and the linked implementation's default limits. | |
| JSONBOURNE_API jsonbourne_val * | jsonbourne_read (const void *src, size_t len) |
| Read strict JSON with default limits and malloc-backed ownership. | |
| JSONBOURNE_API void * | jsonbourne_val_write_opts (const jsonbourne_val *val, void *(*alc_fn)(void *, size_t), void(*free_fn)(void *, void *), void *alc_ctx, size_t *out_len) |
| Validate a DOM and allocate minified JSON output. | |
| JSONBOURNE_API void * | jsonbourne_val_write (const jsonbourne_val *val, size_t *out_len) |
| Allocate minified JSON using malloc. | |
| JSONBOURNE_API void * | jsonbourne_val_write_pretty_opts (const jsonbourne_val *val, const char *indent, const char *newline, void *(*alc_fn)(void *, size_t), void(*free_fn)(void *, void *), void *alc_ctx, size_t *out_len) |
| Validate and allocate pretty output with explicit formatting/ownership. | |
| JSONBOURNE_API void * | jsonbourne_val_write_pretty (const jsonbourne_val *val, const char *indent, const char *newline, size_t *out_len) |
| Allocate pretty JSON using malloc. | |
| JSONBOURNE_API int | jsonbourne_val_write_buf (const jsonbourne_val *val, char *buf, size_t cap, size_t *out_len) |
| Preflight minified output, then write only if the caller buffer fits. | |
| JSONBOURNE_API int | jsonbourne_val_write_pretty_buf (const jsonbourne_val *val, const char *indent, const char *newline, char *buf, size_t cap, size_t *out_len) |
| Preflight pretty output without allocating storage. | |
| JSONBOURNE_API jsonbourne_val * | jsonbourne_val_copy_opts (const jsonbourne_val *val, void *(*alc_fn)(void *, size_t), void *alc_ctx) |
| Deep-copy a validated value into one independent allocation. | |
| JSONBOURNE_API jsonbourne_val * | jsonbourne_val_copy (const jsonbourne_val *val) |
| Make an independently owned deep copy using malloc. | |
| JSONBOURNE_API jsonbourne_str * | jsonbourne_get_str (jsonbourne_val *val) |
| Borrow a string payload without allocating or copying. | |
| JSONBOURNE_API jsonbourne_num * | jsonbourne_get_num (jsonbourne_val *val) |
| Borrow the original number-token view. | |
| JSONBOURNE_API jsonbourne_obj * | jsonbourne_get_obj (jsonbourne_val *val) |
| Borrow the ordered object payload. | |
| JSONBOURNE_API jsonbourne_arr * | jsonbourne_get_arr (jsonbourne_val *val) |
| Borrow the ordered array payload. | |
| JSONBOURNE_API int | jsonbourne_is_true (const jsonbourne_val *val) |
| Test the true tag without coercing numbers or strings. | |
| JSONBOURNE_API int | jsonbourne_is_false (const jsonbourne_val *val) |
| Test the false tag without truthiness conversion. | |
| JSONBOURNE_API int | jsonbourne_is_null (const jsonbourne_val *val) |
| Distinguish JSON null from a missing C pointer. | |
| JSONBOURNE_API const jsonbourne_val * | jsonbourne_obj_getn (const jsonbourne_val *val, const char *key, size_t len) |
| Find the first exact decoded member name, including embedded NUL bytes. | |
| JSONBOURNE_API const jsonbourne_val * | jsonbourne_obj_getn_unique (const jsonbourne_val *val, const char *key, size_t len) |
| Require exactly one decoded matching key instead of silently choosing. | |
| JSONBOURNE_API const jsonbourne_val * | jsonbourne_arr_get (const jsonbourne_val *val, size_t idx) |
| Locate a zero-based array element by bounded linked traversal. | |
| JSONBOURNE_API int | jsonbourne_num_to_uint (const jsonbourne_num *num, uint64_t *out) |
| Convert an unsigned decimal integer token exactly, without coercion. | |
| JSONBOURNE_API int | jsonbourne_num_to_sint (const jsonbourne_num *num, int64_t *out) |
| Convert a signed decimal integer token exactly, including INT64_MIN. | |
| JSONBOURNE_API const jsonbourne_val * | jsonbourne_ptr_getn (const jsonbourne_val *val, const char *pointer, size_t len) |
| Resolve an RFC 6901 pointer without allocating decoded path tokens. | |
| JSONBOURNE_API const char * | jsonbourne_read_err_desc (jsonbourne_read_code code) |
| Borrow human-readable diagnostic text without allocating. | |
Detailed Description
JSON reader, writer and DOM utilities for Linux C11 with a C++11-compatible API.
Strict parsing validates RFC 8259 grammar and Unicode scalar values in UTF-8. The input need not be terminated, aligned or padded and is never modified. Decoded strings and unchanged numeric tokens are owned by the returned DOM. Duplicate names and their order are preserved; jsonbourne_obj_getn_unique() rejects ambiguous lookups. Embedded NULs are supported through explicit byte lengths.
Parsing and cloning make one allocation, released with free() when the default allocator is used. Custom allocators must provide malloc-compatible alignment and own their corresponding release policy. jsonbourne_read_buf(), jsonbourne_read_measure(), jsonbourne_read_validate() and the *_buf writers do not allocate. Input, DOM and output buffers must not overlap and must remain stable throughout each operation. Allocator callbacks must not mutate input or DOM data. Independent calls share no mutable state and may run concurrently.
JSONBOURNE_READER_DEPTH_LIMIT bounds reader nesting and fixed traversal storage. JSONBOURNE_WRITER_DEPTH_LIMIT bounds writer/copy traversal and defaults to the reader limit. Both are positive hard limits, initially 999; zero does not mean unlimited. Embedded consumers should select smaller application-specific limits when compiling jsonbourne.c. Runtime limits additionally bound input, total DOM bytes, decoded string bytes and value count before allocation. SIMD is automatic for baseline x86-64 SSE2 and AArch64 NEON; define JSONBOURNE_DISABLE_SIMD=1 for a scalar build. Every vector load is within the supplied input extent. Normal -O2/-O3 suffices; no fast-math or SSSE3 is needed.
Writers validate accessible DOM structures, UTF-8, numbers, list lengths and cycles. All output sizes INCLUDE the terminating NUL, matching the original API. Numbers keep their decimal spelling and precision. Relaxed hexadecimal tokens are converted exactly, up to JSONBOURNE_MAX_HEX_DIGITS significant hex digits; larger conversions fail rather than overflow. The legacy relaxed nonfinite writer policy maps NaN to 0 and infinities to signed DBL_MAX text. Compile jsonbourne.c once with the desired build options and link its object. Public names follow Yuan conventions, but the DOM layout, flag bits and writer lengths are JSONbourne-specific rather than Yuan ABI compatible. Pretty-print indentation/newlines must contain JSON whitespace only.
- Why tokens and lengths are preserved
- Keeping decimal text avoids rounding large integers through binary floating point. Explicit byte lengths distinguish embedded NULs from terminators, and preserving duplicate keys lets the application decide whether ambiguity is acceptable instead of silently discarding input.
- Precondition
- Input, DOM nodes, linked entries and output storage must refer to valid, accessible memory for their advertised lifetimes and extents. Structural validation detects malformed lists and cycles, not arbitrary invalid pointers.
- Note
- Select compile-time options when building jsonbourne.c; defining them only in a client does not change the linked implementation's storage limits.
Definition in file jsonbourne.h.