JSON Backend

Functions
SerWriter *	serJsonWriterCreate (StreamBuffer *sb, flags_t flags)
SerReader *	serJsonReaderCreate (StreamBuffer *sb, flags_t flags)

Detailed Description

JSON cannot represent the data model losslessly, so the projection is defined rather than improvised. Each rule below is the behaviour, not a suggestion:

• An integer outside ±2^53 is written as a decimal string, because that is the range past which a JSON consumer with only doubles starts silently rounding. The reader accepts both the string and the number form.
• NaN and ±Inf have no JSON spelling and are written as null; under SER_Strict they are an error instead.
• A byte run is a base64 string.
• A map with non-string keys becomes an array of two-element [key, value] arrays. The backend does not advertise SER_Cap_NonStringKeys, so the traverser projects it.
• A float32 is written in the shortest form that reads back as the same float32.
• A struct member equal to its default is omitted, and an absent member reads back as its default. SER_EmitDefaults writes them anyway.
• An unknown key is ignored on read; under SER_Strict it is an error.

The transport is a StreamBuffer the caller owns and registers a consumer or producer on, the same as the rest of cx's JSON support. The backend only borrows the stream buffer: it neither ends nor releases it, so several documents may go into the same one.

StreamBuffer *sb = sbufCreate(4096);
string out = 0;
sbufStrCRegisterPush(sb, &out);
 
SerWriter *w = serJsonWriterCreate(sb, SER_JSON_Pretty);
serWrite(w, MyStruct, val);
serWriterFinish(w);
serWriterDestroy(&w);
sbufFinish(&sb);

Function Documentation

serJsonReaderCreate()

SerReader * serJsonReaderCreate	(	StreamBuffer *	sb,
		flags_t	flags
	)

Creates a reader that parses JSON from a stream buffer.

Parameters

sb	Stream buffer with a producer registered in pull mode. The reader registers as the consumer, taking a reference of its own; destroying it ends the consumer side and drops that reference, which spends the stream. The caller's own reference is untouched and still has to be released.
flags	SerFlagsEnum options

Returns

A new reader; destroy with serReaderDestroy()

Example:

StreamBuffer *sb = sbufCreate(4096);
sbufStrPRegisterPull(sb, json);
 
SerReader *r = serJsonReaderCreate(sb, 0);
MyStruct out;
structInit(MyStruct, &out);
serRead(r, MyStruct, &out);
serReaderDestroy(&r);
sbufFinish(&sb);

serJsonWriterCreate()

SerWriter * serJsonWriterCreate	(	StreamBuffer *	sb,
		flags_t	flags
	)

Creates a writer that emits JSON to a stream buffer.

Parameters

sb	Stream buffer with a consumer registered in push mode. The writer registers as the producer, taking a reference of its own; finishing or destroying it ends the producer side and drops that reference, which spends the stream. The caller's own reference is untouched and still has to be released.
flags	SerFlagsEnum options. SER_JSON_Pretty indents by 4 and breaks lines, SER_JSON_Compact strips every optional space; the default is one line with spaces after punctuation. Pretty wins if both are given.

Returns

A new writer; destroy with serWriterDestroy()