Illustrated C/C++ source sheets, symbol index, API relationship graph, compiler console and debug trace

LIVE AI / FLEXIBLE SENSING / FLIGHT CONTEXT

Sensoraia API

Live AI and sensing, connected to the flight.
See, listen, inspect and return supported results while airborne.

Loading...
Searching...
No Matches
jsonbourne.h File Reference

JSON reader, writer and DOM utilities for Linux C11 with a C++11-compatible API. More...

#include <stddef.h>
#include <stdint.h>
Include dependency graph for jsonbourne.h:
This graph shows which files directly or indirectly include this file:

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.

Enumerations

enum  jsonbourne_read_flag_e {
  JSONBOURNE_READ_NOFLAG = 0 , JSONBOURNE_READ_ALLOW_TRAILING_COMMAS = 0x0002 , JSONBOURNE_READ_ALLOW_UNQUOTED_KEY = 0x0004 , JSONBOURNE_READ_ALLOW_GLOBAL_OBJECT = 0x0008 ,
  JSONBOURNE_READ_ALLOW_EQUALS = 0x0010 , JSONBOURNE_READ_ALLOW_NO_COMMAS = 0x0020 , JSONBOURNE_READ_ALLOW_COMMENTS = 0x0040 , JSONBOURNE_READ_RESERVED = 0x0080 ,
  JSONBOURNE_READ_TRACK_LOCATION = 0x0100 , JSONBOURNE_READ_ALLOW_SINGLE_QUOTED_STR = 0x0200 , JSONBOURNE_READ_ALLOW_HEX_NUM = 0x0400 , JSONBOURNE_READ_ALLOW_PLUS_SIGN = 0x0800 ,
  JSONBOURNE_READ_ALLOW_DECIMAL_POINT = 0x1000 , JSONBOURNE_READ_ALLOW_INF_AND_NAN = 0x2000 , JSONBOURNE_READ_ALLOW_MULTILINE_STR = 0x4000 , JSONBOURNE_READ_SIMPLIFIED = 0x003e ,
  JSONBOURNE_READ_JSON5 = 0x7e46
}
 Independent reader options and convenience presets. More...
enum  jsonbourne_type {
  JSONBOURNE_TYPE_STR , JSONBOURNE_TYPE_NUM , JSONBOURNE_TYPE_OBJ , JSONBOURNE_TYPE_ARR ,
  JSONBOURNE_TYPE_TRUE , JSONBOURNE_TYPE_FALSE , JSONBOURNE_TYPE_NULL
}
 Payload tag; literals need no separately allocated payload. More...
enum  jsonbourne_read_code_e {
  JSONBOURNE_READ_SUCCESS = 0 , JSONBOURNE_READ_ERROR_EXPECTED_SEPARATOR , JSONBOURNE_READ_ERROR_EXPECTED_COLON , JSONBOURNE_READ_ERROR_EXPECTED_KEY ,
  JSONBOURNE_READ_ERROR_INVALID_ESCAPE , JSONBOURNE_READ_ERROR_INVALID_NUMBER , JSONBOURNE_READ_ERROR_LITERAL , JSONBOURNE_READ_ERROR_UNEXPECTED_END ,
  JSONBOURNE_READ_ERROR_INVALID_STRING , JSONBOURNE_READ_ERROR_MEMORY_ALLOCATION , JSONBOURNE_READ_ERROR_UNEXPECTED_CONTENT , JSONBOURNE_READ_ERROR_DEPTH ,
  JSONBOURNE_READ_ERROR_INVALID_COMMENT , JSONBOURNE_READ_ERROR_UNKNOWN , JSONBOURNE_READ_ERROR_INVALID_UTF8 , JSONBOURNE_READ_ERROR_LIMIT ,
  JSONBOURNE_READ_ERROR_INVALID_PARAMETER
}
 Reader failures; zero denotes success and leaves error coordinates zeroed. More...

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.
See also
jsonbourne_read_buf(), jsonbourne_read_limits_default(), jsonbourne_version()

Definition in file jsonbourne.h.