Trimming and dependencies

Public selection macroImplementation macroDirect dependencies
XRT_MODULE_JSONL_COREXRT_FEATURE_JSONL_COREcore
XRT_MODULE_JSONL_READXRT_FEATURE_JSONL_READjsonl_core, json_read
XRT_MODULE_JSONL_WRITEXRT_FEATURE_JSONL_WRITEjsonl_core, json_write
XRT_MODULE_JSONL_FILEXRT_FEATURE_JSONL_FILEjsonl_read, jsonl_write, file_whole
XRT_MODULE_JSONLXRT_FEATURE_JSONLjsonl_file

The header is <xrt/jsonl.h> and can also be included through the umbrella header <xrt.h>. Selecting only reading or only writing does not pull in the file module.

Stability contract

  • Blank lines are ignored by default: empty lines, and lines containing only ASCII spaces, tabs, or CR. LF, CRLF, and mixed endings are accepted; a lone CR is not a record separator. Unicode whitespace never turns a line into a blank line.
  • Empty input and input consisting entirely of blank lines both return an empty Array. Strict blank-line mode still accepts zero-byte input and a single terminating newline after the last record; extra blank lines are errors.
  • A line must contain exactly one complete value; the final complete record may omit the terminating newline. Multi-line values, multiple root values on one line, a BOM, invalid UTF-8, and a truncated trailing record all fail.
  • An escaped newline inside a string does not split records. Array records preserve nesting; for example the text []\n yields an Array containing one empty array.
  • Deserialization hands over the owned Array only after every record succeeds; on failure it returns C NULL and frees all partial results.
  • The serialization root must be XVALUE_ARRAY; null, the empty string, and empty containers are real records. The SKIP strategy cannot skip a whole record, it only applies to members inside a single root value.
  • Output is compact, one LF appended per record, and an empty Array produces zero bytes. A PRETTY configuration is rejected. The configuration is snapshotted by value; a callback mutating the original configuration does not affect the in-flight call.
  • Valid reuses the DOM-free syntax validation of JSON: blank lines are ignored, the default cumulative budgets are checked, and duplicate-key DOM policy does not participate.
  • File writing completes the in-memory serialization first and then replaces the file atomically; a serialization failure leaves the target untouched. Synchronous callback writing may have committed partial records before failing; those bytes cannot be rolled back.
  • Single-line comments and trailing commas are compatibility extensions enabled only inside Record; they must not continue across physical lines.

Threading and ownership: the API carries no implicit locks; each call owns an independent workspace, and the caller synchronizes shared mutable input. Writing iterates a backing snapshot of the outer Array, so Value subtree ownership rules still apply during callbacks. Input text and configuration are borrowed until the call returns; the result Array is released with xrtValueRelease, the result string with xrtFree. The output callback consumes bytes before returning.

Constants

ConstantValueMeaning
XJSONL_READ_REJECT_EMPTY_LINESUINT32_C(0x00000001)Blank lines become errors; off by default.

Configurations must be initialized with Init; all budgets are non-zero. Record defaults come from the existing JSON initialization functions. Overall input/output defaults to 64 MiB; record count and syntax value count default to 1000000.

xjsonlerrortype

Errors are obtained via xrtGetError() with format domain xrt.jsonl; argument and underlying OOM failures may also surface as Core errors directly. RECORD/OUTPUT/IO wrappers preserve the Cause Kind. If building the wrapper itself fails to allocate, the original cause error is kept and no location data is promised.

ValueMeaning
XJSONL_ERROR_CONFIGConfiguration not initialized, reserved bits non-zero, a zero budget, or PRETTY enabled.
XJSONL_ERROR_SYNTAXA blank line in strict blank-line mode.
XJSONL_ERROR_LIMITOverall or per-record budget exhausted.
XJSONL_ERROR_RECORDEncoding/decoding a single value or appending it to the Array failed; the Cause keeps the specific reason.
XJSONL_ERROR_TYPEThe serialization root is not an Array.
XJSONL_ERROR_OUTPUTSynchronous output callback failed.
XJSONL_ERROR_IOBudgeted file read or atomic file replacement failed.
XJSONL_ERROR_STATEReserved code for an invalid line-processing state.
typedef enum xjsonlerror { XJSONL_ERROR_CONFIG = 1701, XJSONL_ERROR_SYNTAX, XJSONL_ERROR_LIMIT, XJSONL_ERROR_RECORD, XJSONL_ERROR_TYPE, XJSONL_ERROR_OUTPUT, XJSONL_ERROR_IO, XJSONL_ERROR_STATE } xjsonlerror;

xjsonllocationtype

FieldTypeMeaning
Offsetsize_tZero-based byte offset in the raw input.
Linesize_tOne-based physical line number split on LF; CRLF counts as one line, and ignored blank lines still count.
Columnsize_tOne-based UTF-8 byte column within the current physical line; not counted in Unicode characters.
RecordIndexsize_tZero-based record index; blank lines do not increment it, and a blank-line error points at the next pending record index.
typedef struct xjsonllocation { size_t Offset; size_t Line; size_t Column; size_t RecordIndex; } xjsonllocation;

xjsonlreadflagtype

ValueMeaning
XJSONL_READ_REJECT_EMPTY_LINESTurns the blank lines ignored by default into syntax errors.
typedef enum xjsonlreadflag { XJSONL_READ_REJECT_EMPTY_LINES = UINT32_C(0x00000001)

xjsonlreadconfigtype

FieldTypeMeaning
RecordxjsonreadconfigPer-record configuration; MaxInputBytes/MaxOutputBytes exclude the CRLF/LF separators, and depth counts from each record's root value.
Flagsuint32Defaults to 0; XJSONL_READ_REJECT_EMPTY_LINES enables blank-line errors.
MaxInputBytessize_tCap on the whole raw input, including ignored blank lines and all separators; default 64 MiB.
MaxRecordssize_tCap on non-blank record count, equal to the maximum element count of the result Array; default 1000000.
MaxTotalValuessize_tCumulative cap on syntax values across all records, including values dropped by duplicate-key policy and excluding the synthesized Array; default 1000000.
Reserveduint32[4]Reserved space; must be all zero.
typedef struct xjsonlreadconfig { xjsonreadconfig Record; uint32 Flags; size_t MaxInputBytes; size_t MaxRecords; size_t MaxTotalValues; uint32 Reserved[4]; } xjsonlreadconfig;

xjsonlwriteconfigtype

FieldTypeMeaning
RecordxjsonwriteconfigPer-record configuration; MaxInputBytes/MaxOutputBytes exclude the CRLF/LF separators, and depth counts from each record's root value.
MaxOutputBytessize_tCap on total output bytes, including every LF and excluding the trailing NUL of the result; default 64 MiB.
MaxRecordssize_tCap on non-blank record count, equal to the maximum element count of the result Array; default 1000000.
Reserveduint32[4]Reserved space; must be all zero.
typedef struct xjsonlwriteconfig { xjsonwriteconfig Record; size_t MaxOutputBytes; size_t MaxRecords; uint32 Reserved[4]; } xjsonlwriteconfig;
Text, configuration, and file interfaces

xrtJsonlErrorLocationfunction

Reads the global byte offset, one-based physical line/column, and zero-based record index; leaves the output unchanged when no location is present.

bool xrtJsonlErrorLocation(const xerror* pError, xjsonllocation* pLocation)

Parameters

ParameterDirectionConstraintsDescription
pErrorinputmay be null; read-only borrowReads the location from an error of this format; returns false for no location or a foreign error domain.
pLocationoutputnon-nullFilled with the global location on success; contents unchanged on failure.
Return value
ReturnMeaningState on failure
trueLocation read.—
falseNo location or invalid argument.Location output unchanged; absence of a location does not itself set an error.
Errors
  • XERR_ARGUMENT — the location output is null.

ExampleCompile-verified

jsonl · Call to xrtJsonlErrorLocation in the complete program; failure jumps to unified cleanup.

if ( !xrtJsonlErrorLocation(xrtGetError(), &Location) ) goto done;

xrtJsonlReadConfigInitfunction

Initializes blank-line skipping by default, strict per-record syntax, and bounded cumulative budgets.

void xrtJsonlReadConfigInit(xjsonlreadconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
pConfigoutputnon-nullSets defaults and zeroes the reserved fields.
Return value
ReturnMeaningState on failure
voidInitialization complete.A null pointer sets an argument error.
Errors
  • XERR_ARGUMENT — the configuration output is null.

ExampleCompile-verified

jsonl · Call to xrtJsonlReadConfigInit in the complete program; failure jumps to unified cleanup.

xrtJsonlReadConfigInit(&Read);

xrtJsonlParsefunction

Parses the record sequence with default configuration; returns an owned Array on success, an empty Array for empty input.

xvalue* xrtJsonlParse(xstrview Text)

Parameters

ParameterDirectionConstraintsDescription
Textinputexplicit byte length; NULL Data only at zero lengthThe whole text is borrowed until the call returns; input need not be NUL-terminated.
Return value
ReturnMeaningState on failure
non-nullOwned Array for the caller to release.—
NULLArgument, budget, syntax, or resource error.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlParse in the complete program; failure jumps to unified cleanup.

pArray = xrtJsonlParse(XRT_STR_LITERAL("{\"id\":1}\n\n[2,3]\r\nnull\n"));
if ( pArray == NULL ) goto done;

xrtJsonlReadfunction

Parses all records per configuration; on failure frees partial results and returns NULL. Release the result with xrtValueRelease.

xvalue* xrtJsonlRead(xstrview Text, const xjsonlreadconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
Textinputexplicit byte length; NULL Data only at zero lengthThe whole text is borrowed until the call returns; input need not be NUL-terminated.
pConfiginputnon-null; must be initializedPer-record configuration and cumulative budgets; the source is not modified by this call.
Return value
ReturnMeaningState on failure
non-nullOwned Array for the caller to release.—
NULLArgument, budget, syntax, or resource error.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlRead in the complete program; failure jumps to unified cleanup.

pRead = xrtJsonlRead((xstrview){ Text, Size }, &Read);
if ( pRead == NULL ) goto done;

xrtJsonlValidfunction

Ignores blank lines by default and validates per-line syntax and cumulative budgets without building a Value DOM; duplicate-key policy does not participate.

bool xrtJsonlValid(xstrview Text)

Parameters

ParameterDirectionConstraintsDescription
Textinputexplicit byte length; NULL Data only at zero lengthThe whole text is borrowed until the call returns; input need not be NUL-terminated.
Return value
ReturnMeaningState on failure
trueEvery non-blank line passed the default syntax and budget checks.—
falseOperation failed.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlValid in the complete program; failure jumps to unified cleanup.

if ( !xrtJsonlValid((xstrview){ Text, Size }) ) goto done;

xrtJsonlWriteConfigInitfunction

Initializes compact single-line output, LF separation, and bounded cumulative budgets; a PRETTY configuration is invalid.

void xrtJsonlWriteConfigInit(xjsonlwriteconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
pConfigoutputnon-nullSets defaults and zeroes the reserved fields.
Return value
ReturnMeaningState on failure
voidInitialization complete.A null pointer sets an argument error.
Errors
  • XERR_ARGUMENT — the configuration output is null.

ExampleCompile-verified

jsonl · Call to xrtJsonlWriteConfigInit in the complete program; failure jumps to unified cleanup.

xrtJsonlWriteConfigInit(&Write);

xrtJsonlStringifyfunction

Writes each Array element as one line; returns NUL-terminated text released with xrtFree. On failure the optional pSize is left unchanged.

str xrtJsonlStringify(const xvalue* pArray, size_t* pSize)

Parameters

ParameterDirectionConstraintsDescription
pArrayinputnon-null and of type XVALUE_ARRAYElements to serialize; the call does not consume the caller's owned reference.
pSizeoutputmay be nullOn success receives the byte count including LF and excluding the NUL; unchanged on failure.
Return value
ReturnMeaningState on failure
non-nullOwned NUL-terminated text; empty output still returns a releasable string.—
NULLConfiguration, type, encoding, or resource error.pSize unchanged; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_TYPE — the serialization root is not an Array.
  • XERR_UNSUPPORTED — a single value cannot be encoded by the selected format.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlStringify in the complete program; failure jumps to unified cleanup.

Text = xrtJsonlStringify(pArray, &Size);
if ( Text == NULL ) goto done;

xrtJsonlWritefunction

Writes each record and its LF to a synchronous chunked callback; the callback's borrowed bytes are valid only during the call, and bytes committed before a failure cannot be rolled back.

bool xrtJsonlWrite(const xvalue* pArray, const xjsonlwriteconfig* pConfig, xjsonwriteproc pWrite, ptr pUserData)

Parameters

ParameterDirectionConstraintsDescription
pArrayinputnon-null and of type XVALUE_ARRAYElements to serialize; the call does not consume the caller's owned reference.
pConfiginputnon-null; must be initializedPer-record configuration and cumulative budgets; the source is not modified by this call.
pWriteinputnon-null synchronous callbackConsumes borrowed bytes in chunks; returning false aborts output.
pUserDatainputmay be nullPassed through to the synchronous output callback.
Return value
ReturnMeaningState on failure
trueAll output completed.—
falseOperation failed.Input references stay with the caller; committed bytes cannot be rolled back, and the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_TYPE — the serialization root is not an Array.
  • XERR_UNSUPPORTED — a single value cannot be encoded by the selected format.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlWrite in the complete program; failure jumps to unified cleanup.

if ( !xrtJsonlWrite(pArray, &Write, discard, NULL) ) goto done;

xrtJsonlParseFilefunction

Reads the file under the default budget and returns an owned Array.

xvalue* xrtJsonlParseFile(cstr sPath)

Parameters

ParameterDirectionConstraintsDescription
sPathinputnon-null NUL-terminated pathFile to read, or target file for atomic replacement.
Return value
ReturnMeaningState on failure
non-nullOwned Array for the caller to release.—
NULLArgument, budget, syntax, or resource error.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlParseFile in the complete program; failure jumps to unified cleanup.

pRead = xrtJsonlParseFile(Path);
if ( pRead == NULL ) goto done;

xrtJsonlReadFilefunction

Reads the file under the overall input cap and parses it line by line; on failure no partial Array is returned.

xvalue* xrtJsonlReadFile(cstr sPath, const xjsonlreadconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
sPathinputnon-null NUL-terminated pathFile to read, or target file for atomic replacement.
pConfiginputnon-null; must be initializedPer-record configuration and cumulative budgets; the source is not modified by this call.
Return value
ReturnMeaningState on failure
non-nullOwned Array for the caller to release.—
NULLArgument, budget, syntax, or resource error.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_PROTOCOL — a non-blank line is not one complete valid value, or strict mode hit a blank line; a per-record error keeps the underlying cause chain.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlReadFile in the complete program; failure jumps to unified cleanup.

pRead = xrtJsonlReadFile(Path, &Read);
if ( pRead == NULL ) goto done;

xrtJsonlStringifyFilefunction

Fully serializes the Array with default configuration and then replaces the file atomically.

bool xrtJsonlStringifyFile(cstr sPath, const xvalue* pArray)

Parameters

ParameterDirectionConstraintsDescription
sPathinputnon-null NUL-terminated pathFile to read, or target file for atomic replacement.
pArrayinputnon-null and of type XVALUE_ARRAYElements to serialize; the call does not consume the caller's owned reference.
Return value
ReturnMeaningState on failure
trueAll output completed.—
falseOperation failed.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_TYPE — the serialization root is not an Array.
  • XERR_UNSUPPORTED — a single value cannot be encoded by the selected format.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlStringifyFile in the complete program; failure jumps to unified cleanup.

if ( !xrtJsonlStringifyFile(Path, pArray) ) goto done;

xrtJsonlWriteFilefunction

Fully serializes with the advanced configuration and then replaces the file atomically; a serialization failure keeps the original file.

bool xrtJsonlWriteFile(cstr sPath, const xvalue* pArray, const xjsonlwriteconfig* pConfig)

Parameters

ParameterDirectionConstraintsDescription
sPathinputnon-null NUL-terminated pathFile to read, or target file for atomic replacement.
pArrayinputnon-null and of type XVALUE_ARRAYElements to serialize; the call does not consume the caller's owned reference.
pConfiginputnon-null; must be initializedPer-record configuration and cumulative budgets; the source is not modified by this call.
Return value
ReturnMeaningState on failure
trueAll output completed.—
falseOperation failed.No partial result; the error is obtained via xrtGetError().
Errors
  • XERR_ARGUMENT — a required pointer is null, or a configuration field or reserved bit is invalid.
  • XERR_MEMORY — workspace, result, or structured-error allocation failed.
  • XERR_RANGE — a per-record or cumulative budget was exhausted.
  • XERR_TYPE — the serialization root is not an Array.
  • XERR_UNSUPPORTED — a single value cannot be encoded by the selected format.
  • XERR_IO — a file operation or an output-callback failure that reported no specific error; other Kinds of the underlying cause are preserved as-is.

Other per-record codec errors inherit the specific Kind and code of their Cause.

ExampleCompile-verified

jsonl · Call to xrtJsonlWriteFile in the complete program; failure jumps to unified cleanup.

if ( !xrtJsonlWriteFile(Path, pArray, &Write) ) goto done;

Constant indexconstant

The following constants are defined in this page's header; semantics are documented in the public header comments.

ConstantDescription
XJSONL_ERROR_CONFIGSee header comments
XJSONL_ERROR_IOSee header comments
XJSONL_ERROR_LIMITSee header comments
XJSONL_ERROR_OUTPUTSee header comments
XJSONL_ERROR_RECORDSee header comments
XJSONL_ERROR_STATESee header comments
XJSONL_ERROR_SYNTAXSee header comments
XJSONL_ERROR_TYPESee header comments
XJSONL_READ_REJECT_EMPTY_LINESSee header comments