JSON Reference

Detailed Description

JSON Reference Manual.

Examples:

See the JSON tutorial for an introduction to using the JSON API.

Collaboration diagram for JSON Reference:

Modules
	JSON Parser Callback
	JSON Parser Callback Interface.

Classes
struct	JEncoder
	The JEncoder can serialize a JSON JVAL syntax tree to the JSON text format. More...
struct	JErr
	The JSON error container object. More...
struct	JParserVal
	The parser sets a JParserVal before calling the parser callback JParserIntf. More...
struct	JParser
	The JSON parser parses a JSON stream and calls the JParserIntf callback interface for each parsed object/primitive type. More...
struct	JVal
	JVal represents a value in a JSON tree. More...
struct	JValFact
	The JValFact enables one to manually create a JVal syntax tree or add nodes to an existing syntax tree. More...

Macros
#define	JEncoder_destructor(o)   JEncoder_flush(o)
	Call flush() without freeing the borrowed writer or error object. More...
#define	JEncoder_getErr(o)   (o)->err
	Query error storage. More...
#define	JEncoder_getBufPrint(o)   (o)->out
	Query output storage. More...
#define	JE_MEMBER(o, m)   #m, (o)->m
	JEncoder::set helper macro, used when setting a value for an object. More...
#define	JErr_constructor(o)   (o)->err=JErrT_NoErr
	Initialize only the error code to JErrT_NoErr. More...
#define	JErr_reset(o)   (o)->err=JErrT_NoErr, (o)->msg=0
	Clear the error code and message pointer so the object can be reused. More...
#define	JErr_isError(o)   ((o)->err!=JErrT_NoErr)
#define	JErr_noError(o)   ((o)->err==JErrT_NoErr)
#define	JErr_getErrT(o)   (o)->err
#define	JErr_getExpT(o)   (o)->expType
#define	JErr_getRecT(o)   (o)->recType
#define	JParser_getStatus(o)   ((JParsStat)(o)->status)
	Inspect the last parser result without changing state. More...
#define	JVal_getType(o)   (o)->type
#define	JVal_getStringLen(o)   (o)->stringLen
#define	JVal_getNameLen(o)   (o)->memberNameLen
#define	JVal_getNextElem(o)   (o)->next
#define	JVal_isObjectMember(o)   ((o)->memberName != 0)
#define	JVal_setInt(o, e, v)   JVal_setX(o, e, JVType_Int, &v)
	Replace a scalar value and set its type. More...
#define	JVal_setLong(o, e, v)   JVal_setX(o, e, JVType_Long, &v)
	Replace a scalar value and set its type. More...
#define	JVal_setDouble(o, e, v)   JVal_setX(o, e, JVType_Double, &v)
	Replace a scalar value and set its type. More...
#define	JVal_setBoolean(o, e, v)   JVal_setX(o, e, JVType_Boolean, &v)
	Replace a scalar value and set its type. More...
#define	JVal_setNull(o, e)   JVal_setX(o, e, JVType_Null, 0)
	Replace a scalar value with JSON null. More...
#define	JVal_setString(o, e, v)   JVal_setX(o, e, JVType_String, v)
	Store a string pointer without copying it and set the node's type. More...
#define	JValFact_mkString(o, v)   JValFact_mkVal(o, JVType_String, v)
	Create a detached string node. More...
#define	JValFact_mkDouble(o, v)   JValFact_mkVal(o, JVType_Double, &v)
	Create a detached double node. More...
#define	JValFact_mkInt(o, v)   JValFact_mkVal(o, JVType_Int, &v)
	Create a detached int node. More...
#define	JValFact_mkLong(o, v)   JValFact_mkVal(o, JVType_Long, &v)
	Create a detached long node. More...
#define	JValFact_mkBoolean(o, v)   JValFact_mkVal(o, JVType_Boolean, &v)
	Create a detached boolean node. More...
#define	JValFact_mkNull(o)   JValFact_mkVal(o, JVType_Null, 0)
	Create a detached null node. More...
#define	JValFact_mkObject(o)   JValFact_mkVal(o, JVType_Object, 0)
	Create a detached object node. More...
#define	JValFact_mkArray(o)   JValFact_mkVal(o, JVType_Array, 0)
	Create a detached array node. More...

Typedefs
typedef struct JEncoder	JEncoder
	The JEncoder can serialize a JSON JVAL syntax tree to the JSON text format. More...
typedef struct JErr	JErr
	The JSON error container object. More...
typedef struct JParserVal	JParserVal
	The parser sets a JParserVal before calling the parser callback JParserIntf. More...
typedef U8	JParserStackNode
	The stack used internally by JParser. More...
typedef struct JValFact	JValFact
	The JValFact enables one to manually create a JVal syntax tree or add nodes to an existing syntax tree. More...

Enumerations
enum	JVType {   JVType_InvalidType , JVType_String , JVType_Double , JVType_Int ,   JVType_Long , JVType_Boolean , JVType_Null , JVType_Object ,   JVType_Array }
	The JSON types. More...
enum	JErrT {   JErrT_NoErr =0 , JErrT_JsonErr , JErrT_WrongType , JErrT_InvalidMethodParams ,   JErrT_FmtValErr , JErrT_MemErr , JErrT_IOErr }
	JSON error codes. More...
enum	JParserT {   JParserT_InvalidType =0 , JParserT_Null , JParserT_String = 's' , JParserT_Double = 'f' ,   JParserT_Int = 'd' , JParserT_Long = 'l' , JParserT_Boolean = 'b' , JParserT_BeginObject = '{' ,   JParserT_BeginArray = '[' , JParserT_EndObject = '}' , JParserT_EndArray = ']' }
	Type 't' in JParserVal. More...
enum	JParsStat {   JParsStat_DoneEOS =1 , JParsStat_Done , JParsStat_NeedMoreData = 100 , JParsStat_ParseErr = 200 ,   JParsStat_IntfErr , JParsStat_MemErr , JParsStat_StackOverflow }
	JSON Parser Status. More...

Functions
BA_API void	JEncoder_constructor (JEncoder *o, JErr *err, BufPrint *out)
	Initialize an encoder without writing output or resetting err. More...
BA_API int	JEncoder_flush (JEncoder *o)
	Flush the underlying writer if JErr is clear. More...
BA_API int	JEncoder_commit (JEncoder *o)
	Permit a new top-level value and flush the writer. More...
BA_API int	JEncoder_setInt (JEncoder *o, S32 val)
	Write a JSON number. More...
BA_API int	JEncoder_setLong (JEncoder *o, S64 val)
	Write a JSON number. More...
BA_API int	JEncoder_setDouble (JEncoder *o, double val)
	Write a JSON number. More...
BA_API int	JEncoder_fmtString (JEncoder *o, const char *fmt,...)
	Format text inside JSON quotation marks. More...
BA_API int	JEncoder_vFmtString (JEncoder *o, const char *fmt, va_list argList)
	Write formatted text between JSON quotes, or JSON null. More...
BA_API int	JEncoder_setString (JEncoder *o, const char *val, size_t len)
	Write a quoted JSON string through BufPrint::jsonString. More...
BA_API int	JEncoder_b64enc (JEncoder *o, const void *source, S32 slen)
	Write binary data as a quoted standard Base64 string. More...
BA_API int	JEncoder_setBoolean (JEncoder *o, BaBool val)
	Write a JSON boolean. More...
BA_API int	JEncoder_setNull (JEncoder *o)
	Write JSON null. More...
BA_API int	JEncoder_setJV (JEncoder *o, struct JVal *val, BaBool iterateNext)
	Serialize a JVal node and its child values. More...
BA_API int	JEncoder_set (JEncoder *o, const char *fmt,...)
	Encode/serialize C structs/data to JSON using formatted output. More...
BA_API int	JEncoder_setName (JEncoder *o, const char *name)
	Write an object member name before its value. More...
BA_API int	JEncoder_beginObject (JEncoder *o)
	Begin a JSON object value; call setName() before each member value. More...
BA_API int	JEncoder_endObject (JEncoder *o)
	Close the current object after its final complete member. More...
BA_API int	JEncoder_beginArray (JEncoder *o)
	Begin a JSON array value; array elements have no member-name call. More...
BA_API int	JEncoder_endArray (JEncoder *o)
	Close the current array after its final complete element. More...
BA_API int	JErr_setTooFewParams (JErr *o)
	Record JErrT_InvalidMethodParams with a static message if no error exists. More...
BA_API int	JErr_setTypeErr (JErr *o, JVType expT, JVType recT)
	Record JErrT_WrongType only when no earlier error exists. More...
BA_API int	JErr_setError (JErr *o, JErrT err, const char *msg)
	Record an error only when no earlier error exists. More...
BA_API void	JParser_constructor (JParser *o, JParserIntf *intf, char *nameBuf, int namebufSize, AllocatorIntf *alloc, int extraStackLen)
	Create a JSON parser object. More...
BA_API int	JParser_parse (JParser *o, const U8 *buf, U32 size)
	Feed or resume parsing a top-level JSON object or array. More...
BA_API void	JParser_destructor (JParser *o)
	Free internal assembly storage. More...
BA_API JVal *	JVal_vget (JVal *o, JErr *err, const char **fmt, va_list *argList)
	Extract values as for get(), using mutable format and argument cursors. More...
BA_API JVal *	JVal_get (JVal *o, JErr *err, const char *fmt,...)
	Get any type of value(s) from a JVal node or JVal tree. More...
BA_API S32	JVal_getInt (JVal *o, JErr *e)
	Convert a numeric, boolean, or null node to S32. More...
BA_API S64	JVal_getLong (JVal *o, JErr *e)
	Convert a numeric, boolean, or null node to S64. More...
BA_API double	JVal_getDouble (JVal *o, JErr *e)
	Convert a numeric, boolean, or null node to double. More...
BA_API BaBool	JVal_getBoolean (JVal *o, JErr *e)
	Read a boolean or null node. More...
BA_API const char *	JVal_getString (JVal *o, JErr *e)
	Access a string without transferring ownership. More...
BA_API char *	JVal_manageString (JVal *o, JErr *e)
	Detach a string's storage, leaving a String node with NULL data and zero length. More...
BA_API const char *	JVal_getName (JVal *o)
BA_API char *	JVal_manageName (JVal *o)
	Detach the member name and clear its pointer/length in the node. More...
BA_API JVal *	JVal_getObject (JVal *o, JErr *e)
	Access the first child of an object node. More...
BA_API JVal *	JVal_getArray (JVal *o, JErr *e)
	Access the first child of an array node. More...
BA_API JVal *	JVal_getJ (JVal *o, JErr *e)
	Access the first child of an object or array node. More...
BA_API JVal *	JVal_manageJ (JVal *o, JErr *e)
	Detach all children from an object/array, leaving the container empty. More...
BA_API S32	JVal_getLength (struct JVal *o, JErr *e)
	Count immediate children of this object/array. More...
BA_API int	JVal_unlink (JVal *o, JVal *child)
	Remove one immediate child without destroying it. More...
BA_API int	JVal_addMember (JVal *o, JErr *e, const char *memberName, JVal *child, AllocatorIntf *dAlloc)
	Prepend a child to an object. More...
BA_API int	JVal_add (JVal *o, JErr *e, JVal *child)
	Prepend a child to an array. More...
BA_API void	JVal_terminate (JVal *o, AllocatorIntf *vAlloc, AllocatorIntf *dAlloc)
	Free this node, all descendants, and all following siblings recursively. More...
BA_API void	JVal_setX (JVal *o, JErr *e, JVType t, void *v)
	Low-level scalar replacement used by the typed setter macros. More...
BA_API void	JValFact_constructor (JValFact *o, AllocatorIntf *vAlloc, AllocatorIntf *dAlloc)
	Initialize a factory without allocating a tree. More...
BA_API JVal *	JValFact_mkVal (JValFact *o, JVType t, const void *uv)
	Allocate a detached typed value. More...
	JEncoder::JEncoder (JErr *err, BufPrint *out)
	Initialize an encoder without writing output or resetting err. More...
	JEncoder::~JEncoder ()
	Call flush() without freeing the borrowed writer or error object. More...
int	JEncoder::setInt (S32 val)
	Write a JSON number. More...
int	JEncoder::setLong (S64 val)
	Write a JSON number. More...
int	JEncoder::setDouble (double val)
	Write a JSON number. More...
int	JEncoder::fmtString (const char *fmt,...)
	Format text inside JSON quotation marks. More...
int	JEncoder::vFmtString (const char *fmt, va_list argList)
	Write formatted text between JSON quotes, or JSON null. More...
int	JEncoder::setString (const char *val, size_t len)
	Write a quoted JSON string through BufPrint::jsonString. More...
int	JEncoder::b64enc (const void *source, S32 slen)
	Write binary data as a quoted standard Base64 string. More...
int	JEncoder::setBoolean (bool val)
	Write a JSON boolean. More...
int	JEncoder::setNull ()
	Write JSON null. More...
int	JEncoder::setJV (struct JVal *val, bool iterateNext=false)
	Serialize a JVal node and its child values. More...
int	JEncoder::set (const char *fmt,...)
	Encode/serialize C structs/data to JSON using formatted output. More...
int	JEncoder::setName (const char *name)
	Write an object member name before its value. More...
int	JEncoder::beginObject ()
	Begin a JSON object value; call setName() before each member value. More...
int	JEncoder::endObject ()
	Close the current object after its final complete member. More...
int	JEncoder::beginArray ()
	Begin a JSON array value; array elements have no member-name call. More...
int	JEncoder::endArray ()
	Close the current array after its final complete element. More...
JErr *	JEncoder::getErr ()
	Query error storage. More...
int	JEncoder::flush ()
	Flush the underlying writer if JErr is clear. More...
int	JEncoder::commit ()
	Permit a new top-level value and flush the writer. More...
BufPrint *	JEncoder::getBufPrint ()
	Query output storage. More...
	JErr::JErr ()
	Initialize only the error code to JErrT_NoErr. More...
void	JErr::reset ()
	Clear the error code and message pointer so the object can be reused. More...
bool	JErr::isError ()
bool	JErr::noError ()
JErrT	JErr::getErrT ()
JVType	JErr::getExpT ()
JVType	JErr::getRecT ()
int	JErr::setTooFewParams ()
	Record JErrT_InvalidMethodParams with a static message if no error exists. More...
int	JErr::setTypeErr (JVType expT, JVType recT)
	Record JErrT_WrongType only when no earlier error exists. More...
int	JErr::setError (JErrT err, const char *msg)
	Record an error only when no earlier error exists. More...
	JParser::JParser (JParserIntf *intf, char *nameBuf, int namebufSize, AllocatorIntf *alloc, int extraStackLen=0)
	Create a JSON parser object. More...
int	JParser::parse (const U8 *buf, U32 size)
	Feed or resume parsing a top-level JSON object or array. More...
	JParser::~JParser ()
	Free internal assembly storage. More...
JParsStat	JParser::getStatus ()
	Inspect the last parser result without changing state. More...
JVType	JVal::getType ()
JVal *	JVal::vget (JErr *err, const char **fmt, va_list *argList)
	Extract values as for get(), using mutable format and argument cursors. More...
JVal *	JVal::get (JErr *err, const char *fmt,...)
	Get any type of value(s) from a JVal node or JVal tree. More...
S32	JVal::getInt (JErr *e)
	Convert a numeric, boolean, or null node to S32. More...
S64	JVal::getLong (JErr *e)
	Convert a numeric, boolean, or null node to S64. More...
double	JVal::getDouble (JErr *e)
	Convert a numeric, boolean, or null node to double. More...
BaBool	JVal::getBoolean (JErr *e)
	Read a boolean or null node. More...
const char *	JVal::getString (JErr *e)
	Access a string without transferring ownership. More...
size_t	JVal::getStringLen ()
char *	JVal::manageString (JErr *e)
	Detach a string's storage, leaving a String node with NULL data and zero length. More...
const char *	JVal::getName ()
size_t	JVal::getNameLen ()
char *	JVal::manageName ()
	Detach the member name and clear its pointer/length in the node. More...
JVal *	JVal::getNextElem ()
JVal *	JVal::getObject (JErr *e)
	Access the first child of an object node. More...
JVal *	JVal::getArray (JErr *e)
	Access the first child of an array node. More...
JVal *	JVal::getJ (JErr *e)
	Access the first child of an object or array node. More...
JVal *	JVal::manageJ (JErr *e)
	Detach all children from an object/array, leaving the container empty. More...
S32	JVal::getLength (JErr *e)
	Count immediate children of this object/array. More...
void	JVal::setInt (JErr *e, S32 v)
	Replace a scalar value and set its type. More...
void	JVal::setLong (JErr *e, S64 v)
	Replace a scalar value and set its type. More...
void	JVal::setDouble (JErr *e, double v)
	Replace a scalar value and set its type. More...
void	JVal::setBoolean (JErr *e, BaBool v)
	Replace a scalar value and set its type. More...
void	JVal::setNull (JErr *e)
	Replace a scalar value with JSON null. More...
void	JVal::setString (JErr *e, char *v)
	Store a string pointer without copying it and set the node's type. More...
bool	JVal::isObjectMember ()
int	JVal::unlink (JVal *child)
	Remove one immediate child without destroying it. More...
int	JVal::addMember (JErr *e, const char *memberName, JVal *child, AllocatorIntf *dAlloc)
	Prepend a child to an object. More...
int	JVal::add (JErr *e, JVal *child)
	Prepend a child to an array. More...
void	JVal::terminate (AllocatorIntf *vAlloc, AllocatorIntf *dAlloc)
	Free this node, all descendants, and all following siblings recursively. More...
	JValFact::JValFact (AllocatorIntf *vAlloc, AllocatorIntf *dAlloc)
	Initialize a factory without allocating a tree. More...
JVal *	JValFact::mkString (const char *v)
	Create a detached string node. More...
JVal *	JValFact::mkDouble (double v)
	Create a detached double node. More...
JVal *	JValFact::mkInt (S32 v)
	Create a detached int node. More...
JVal *	JValFact::mkLong (S64 v)
	Create a detached long node. More...
JVal *	JValFact::mkBoolean (bool v)
	Create a detached boolean node. More...
JVal *	JValFact::mkNull ()
	Create a detached null node. More...
JVal *	JValFact::mkObject ()
	Create a detached object node. More...
JVal *	JValFact::mkArray ()
	Create a detached array node. More...

Macro Definition Documentation

JE_MEMBER

#define JE_MEMBER	(		o,
			m
	)		#m, (o)->m

JEncoder::set helper macro, used when setting a value for an object.

encoder.set("{d}", JE_MEMBER(structval, membername));

JEncoder_destructor

#define JEncoder_destructor

(

o

)

JEncoder_flush(o)

Call flush() without freeing the borrowed writer or error object.

The C++ destructor cannot report a flush failure; call flush() explicitly and check its result before destruction when the outcome matters.

Parameters

o	Required initialized encoder.

JEncoder_getBufPrint

#define JEncoder_getBufPrint

(

o

)

(o)->out

Query output storage.

Returns

Borrowed BufPrint pointer supplied at construction; no ownership transfer.

Parameters

o	Required initialized encoder.

JEncoder_getErr

#define JEncoder_getErr

(

o

)

(o)->err

Query error storage.

Returns

Required borrowed JErr pointer supplied at construction; does not clear errors.

Parameters

o	Required initialized encoder.

JErr_constructor

#define JErr_constructor

(

o

)

(o)->err=JErrT_NoErr

Initialize only the error code to JErrT_NoErr.

Other fields are not initialized; use reset() if a cleared message pointer is needed.

Parameters

o	Required storage to initialize.

JErr_getErrT

#define JErr_getErrT

(

o

)

(o)->err

Returns

Stored error type; JErrT_NoErr means no recorded error.

Parameters

o	Required initialized error object.

JErr_getExpT

#define JErr_getExpT

(

o

)

(o)->expType

Returns

Expected JVType, meaningful only after a successful setTypeErr().

Parameters

o	Required initialized error object.

JErr_getRecT

#define JErr_getRecT

(

o

)

(o)->recType

Returns

Received JVType, meaningful only after a successful setTypeErr().

Parameters

o	Required initialized error object.

JErr_isError

#define JErr_isError

(

o

)

((o)->err!=JErrT_NoErr)

Returns

True if err is not JErrT_NoErr, false otherwise.

Parameters

o	Required initialized error object.

JErr_noError

#define JErr_noError

(

o

)

((o)->err==JErrT_NoErr)

Returns

True if err is JErrT_NoErr, false otherwise.

Parameters

o	Required initialized error object.

JErr_reset

#define JErr_reset

(

o

)

(o)->err=JErrT_NoErr, (o)->msg=0

Clear the error code and message pointer so the object can be reused.

Expected/received type fields are not reset.

Parameters

o	Required initialized error object.

JParser_getStatus

#define JParser_getStatus

(

o

)

((JParsStat)(o)->status)

Inspect the last parser result without changing state.

Returns

JParsStat value; initially DoneEOS, meaning ready for the first chunk. Done/DoneEOS accompany parse()=1, NeedMoreData accompanies 0, and error states accompany -1. See parse() for input-buffer lifetime.

Parameters

o	Required initialized parser.

JVal_getNameLen

#define JVal_getNameLen

(

o

)

(o)->memberNameLen

Returns

Stored member-name byte length excluding the terminator. Requires a live node; an empty name can still be an object member.

Parameters

o	Required live node.

JVal_getNextElem

#define JVal_getNextElem

(

o

)

(o)->next

Returns

Borrowed next sibling, or NULL at the end. Requires a live node. This does not return a child or transfer ownership.

Parameters

o	Required live node.

JVal_getStringLen

#define JVal_getStringLen

(

o

)

(o)->stringLen

Returns

Stored string byte length, excluding the terminator. Call on a live string node; this direct accessor does not check the type.

Parameters

o	Required live node.

JVal_getType

#define JVal_getType

(

o

)

(o)->type

Returns

Stored JVType of this required live node; no conversion or validation.

Parameters

o	Required live node.

JVal_isObjectMember

#define JVal_isObjectMember

(

o

)

((o)->memberName != 0)

Returns

True if a member-name pointer is present (including an empty name), false otherwise. Requires a live node; this does not inspect a parent pointer.

Parameters

o	Required live node.

JVal_setBoolean

#define JVal_setBoolean	(		o,
			e,
			v
	)		JVal_setX(o, e, JVType_Boolean, &v)

Replace a scalar value and set its type.

Parameters

e	Required initialized error container receiving refusal details.
v	New BaBool value. No return value; inspect e. Cannot replace an object/array or an attached string. Detach and release an old string first. Requires a live non-NULL node; existing errors do not by themselves prevent this setter from changing the node.
o	Required live node. The C macro requires v to be an addressable variable of the declared type.

JVal_setDouble

#define JVal_setDouble	(		o,
			e,
			v
	)		JVal_setX(o, e, JVType_Double, &v)

Replace a scalar value and set its type.

Parameters

e	Required initialized error container receiving refusal details.
v	New double value. No return value; inspect e. Cannot replace an object/array or an attached string. Detach and release an old string first. Requires a live non-NULL node; existing errors do not by themselves prevent this setter from changing the node.
o	Required live node. The C macro requires v to be an addressable variable of the declared type.

JVal_setInt

#define JVal_setInt	(		o,
			e,
			v
	)		JVal_setX(o, e, JVType_Int, &v)

Replace a scalar value and set its type.

Parameters

e	Required initialized error container receiving refusal details.
v	New S32 value. No return value; inspect e. Cannot replace an object/array or an attached string. Detach and release an old string first. Requires a live non-NULL node; existing errors do not by themselves prevent this setter from changing the node.
o	Required live node. The C macro requires v to be an addressable variable of the declared type.

JVal_setLong

#define JVal_setLong	(		o,
			e,
			v
	)		JVal_setX(o, e, JVType_Long, &v)

Replace a scalar value and set its type.

Parameters

e	Required initialized error container receiving refusal details.
v	New S64 value. No return value; inspect e. Cannot replace an object/array or an attached string. Detach and release an old string first. Requires a live non-NULL node; existing errors do not by themselves prevent this setter from changing the node.
o	Required live node. The C macro requires v to be an addressable variable of the declared type.

JVal_setNull

#define JVal_setNull	(		o,
			e
	)		JVal_setX(o, e, JVType_Null, 0)

Replace a scalar value with JSON null.

Parameters

e	Required initialized error container. Objects/arrays and attached strings cannot be replaced; detach/release a string first. Requires a live non-NULL node. No return value; inspect e.
o	Required live node.

JVal_setString

#define JVal_setString	(		o,
			e,
			v
	)		JVal_setX(o, e, JVType_String, v)

Store a string pointer without copying it and set the node's type.

Parameters

e	Required initialized error container receiving refusal details.
v	NUL-terminated string allocated compatibly with the tree's data allocator, or NULL for an empty stored pointer. strlen determines its length. On success the node takes ownership. On failure ownership stays with the caller. Detach/release an old string first; object/array nodes cannot be replaced. Requires a live node. No return value; inspect e.
o	Required live node.

JValFact_mkArray

#define JValFact_mkArray

(

o

)

JValFact_mkVal(o, JVType_Array, 0)

Create a detached array node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators. The container starts empty.

Parameters

o	Required initialized factory.

JValFact_mkBoolean

#define JValFact_mkBoolean	(		o,
			v
	)		JValFact_mkVal(o, JVType_Boolean, &v)

Create a detached boolean node.

Parameters

v	Value copied into the new node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

Parameters

o	Required initialized factory. The C macro requires v to be an addressable variable of its exact numeric type.

JValFact_mkDouble

#define JValFact_mkDouble	(		o,
			v
	)		JValFact_mkVal(o, JVType_Double, &v)

Create a detached double node.

Parameters

v	Value copied into the new node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

Parameters

o	Required initialized factory. The C macro requires v to be an addressable variable of its exact numeric type.

JValFact_mkInt

#define JValFact_mkInt	(		o,
			v
	)		JValFact_mkVal(o, JVType_Int, &v)

Create a detached int node.

Parameters

v	Value copied into the new node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

Parameters

o	Required initialized factory. The C macro requires v to be an addressable variable of its exact numeric type.

JValFact_mkLong

#define JValFact_mkLong	(		o,
			v
	)		JValFact_mkVal(o, JVType_Long, &v)

Create a detached long node.

Parameters

v	Value copied into the new node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

Parameters

o	Required initialized factory. The C macro requires v to be an addressable variable of its exact numeric type.

JValFact_mkNull

#define JValFact_mkNull

(

o

)

JValFact_mkVal(o, JVType_Null, 0)

Create a detached null node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

Parameters

o	Required initialized factory.

JValFact_mkObject

#define JValFact_mkObject

(

o

)

JValFact_mkVal(o, JVType_Object, 0)

Create a detached object node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators. The container starts empty.

Parameters

o	Required initialized factory.

JValFact_mkString

#define JValFact_mkString	(		o,
			v
	)		JValFact_mkVal(o, JVType_String, v)

Create a detached string node.

Parameters

v	Required NUL-terminated string, copied with dAlloc.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

Parameters

o	Required initialized factory.

Typedef Documentation

JEncoder

typedef struct JEncoder JEncoder

The JEncoder can serialize a JSON JVAL syntax tree to the JSON text format.

The JEncoder can also be used for assembling JSON text by calling the primitive methods in this class. Supply a valid sequence of names, values, and matching container delimiters. Writes are incremental: failure can leave partial output and does not roll back prior bytes. The borrowed JErr retains errors until explicitly reset by the caller.

Example:

JErr err;
char buf[40]; //Must be sufficiently large for the JSON string
BufPrint jBuf(buf,sizeof(buf));
JEncoder jEnc(&err,&jBuf);
int status = jEnc.set("{d}", "The number of the day is", (S32)5);
//jBuf.buf == buf
if(status == 0 && jBuf.cursor < sizeof(buf))
{
   buf[jBuf.cursor]=0; // The encoder does not append a C-string terminator.
   printf("%s\n",buf); // Prints: {"The number of the day is":5}
}

JErr

typedef struct JErr JErr

The JSON error container object.

JParserStackNode

typedef U8 JParserStackNode

The stack used internally by JParser.

JParserVal

typedef struct JParserVal JParserVal

The parser sets a JParserVal before calling the parser callback JParserIntf.

JValFact

typedef struct JValFact JValFact

The JValFact enables one to manually create a JVal syntax tree or add nodes to an existing syntax tree.

See also

JParserValFact

Enumeration Type Documentation

JErrT

enum JErrT

JSON error codes.

Enumerator
JErrT_NoErr	No error.
JErrT_JsonErr	Generic error.
JErrT_WrongType	Unexpected JSON type when parsing. See also JErr::getExpT JErr::getRecT
JErrT_InvalidMethodParams	Invalid RPC method parameters.
JErrT_FmtValErr	A format error in JEncoder or JVal::get.
JErrT_MemErr	Memory allocation error.
JErrT_IOErr	I/O error.

JParserT

enum JParserT

Type 't' in JParserVal.

Enumerator
JParserT_InvalidType	InvalidType.
JParserT_Null	Null.
JParserT_String	String.
JParserT_Double	Double.
JParserT_Int	Int.
JParserT_Long	64-bit (long long)
JParserT_Boolean	Boolean.
JParserT_BeginObject	BeginObject.
JParserT_BeginArray	BeginArray.
JParserT_EndObject	EndObject.
JParserT_EndArray	EndArray.

JParsStat

enum JParsStat

JSON Parser Status.

Enumerator
JParsStat_DoneEOS	The parser completed parsing a new JSON object.
JParsStat_Done	The parser completed parsing a new JSON object, but found the unread bytes in the provided buffer. They have not yet been validated as another object or array.
JParsStat_NeedMoreData	The parser needs more data to complete.
JParsStat_ParseErr	JSON Parse error.
JParsStat_IntfErr	The JParserIntf interface reported a problem.
JParsStat_MemErr	Memory allocation error.
JParsStat_StackOverflow	Object nested too deep. Increase stack size in constructor

JVType

enum JVType

The JSON types.

Enumerator
JVType_InvalidType	Invalid JSON type.
JVType_String	JSON string.
JVType_Double	JSON Number encoded as a float.
JVType_Int	JSON Number encoded as an integer.
JVType_Long	JSON Number encoded as a long integer.
JVType_Boolean	JSON boolean.
JVType_Null	JSON NULL value.
JVType_Object	The JVAL is of type JSON object.
JVType_Array	The JVAL is of type JSON array.

Function Documentation

add()

int JVal::add	(	JErr *	e,
		JVal *	child
	)

Prepend a child to an array.

Parameters

e	Required initialized error container.
child	Required detached node with next=NULL and no other owner. Use an unnamed node for an array element. No copy or allocation is performed.

Returns

Zero with ownership transferred, -1 on failure. Check the return as some linkage failures do not set e. Adds at the beginning of the array.

addMember()

int JVal::addMember	(	JErr *	e,
		const char *	memberName,
		JVal *	child,
		AllocatorIntf *	dAlloc
	)

Prepend a child to an object.

Parameters

e	Required initialized error container.
memberName	Required NUL-terminated name used only if child has no name. An existing child name is retained; this does not rename it or check duplicates.
child	Required detached node with next=NULL and no other owning parent.
dAlloc	Allocator used to copy a missing member name. If NULL, the supplied pointer is stored directly; its eventual release must still match tree ownership.

Returns

Zero on success, -1 on failure. Some linkage failures do not set e; check the return. A copied name can remain on child after failure. Success transfers child ownership to the tree and places it first, not last.

b64enc()

int JEncoder::b64enc	(	const void *	source,
		S32	slen
	)

Write binary data as a quoted standard Base64 string.

Parameters

source	Readable bytes borrowed for this call; required for positive slen.
slen	Nonnegative source byte count.

Returns

The current implementation returns -1 even after successful output. A stored JErr indicates an actual format/write failure. This return-value limitation is pending implementation repair.

beginArray()

int JEncoder::beginArray

(

)

Begin a JSON array value; array elements have no member-name call.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Keep container nesting within 511 levels and balance all begin/end calls.

beginObject()

int JEncoder::beginObject

(

)

Begin a JSON object value; call setName() before each member value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Keep container nesting within 511 levels and balance all begin/end calls.

commit()

int JEncoder::commit

(

)

Permit a new top-level value and flush the writer.

Returns

Same result as flush(). The new-value flag is set even if flushing fails. This does not reset JErr or close/reset nested containers; call only after completing the current top-level value.

endArray()

int JEncoder::endArray

(

)

Close the current array after its final complete element.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Keep container nesting within 511 levels and balance all begin/end calls.

endObject()

int JEncoder::endObject

(

)

Close the current object after its final complete member.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Keep container nesting within 511 levels and balance all begin/end calls.

flush()

int JEncoder::flush

(

)

Flush the underlying writer if JErr is clear.

Returns

BufPrint::flush result, or -1 if JErr already records an error. A flush failure is not automatically copied into JErr. This does not validate balanced containers or reset encoder state.

fmtString()

int JEncoder::fmtString	(	const char *	fmt,
			...
	)

Format text inside JSON quotation marks.

Parameters

fmt	BufPrint format string, or NULL to write JSON null. Variadic arguments must match its conversions. Formatted text is not automatically JSON-escaped; use appropriate BufPrint conversions or setString() instead.

Returns

Intended to follow vFmtString().

Warning

The C++ wrapper forwards its va_list to the variadic C declaration, for which no implementation is present in the reviewed source. Use vFmtString() with a va_list or setString() until this is repaired.

get()

JVal * JVal::get	(	JErr *	err,
		const char *	fmt,
			...
	)

Get any type of value(s) from a JVal node or JVal tree.

The get method works in a similar fashion to the ANSI C function scanf; thus, it performs formatted input conversion.

The method internally uses the 'getXXX' methods in this class for extracting the actual value(s), where XXX is Int, Long, etc.. The following table shows the relationship between the format flags and the JSON value extracted:

JSON type	Format flag	C type	Method
Number	d	S32*	JVal::getInt
Number	l	S64*	JVal::getLong
Number	f	double*	JVal::getDouble
boolean	b	BaBool*	JVal::getBoolean
string	s	const char**	JVal::getString
Any type	J	JVal**	All methods
Start object	{	n/a	JVal::getObject
End object	}	n/a	n/a
Start array	[	n/a	JVal::getArray
End array	]	n/a	n/a
Array	A followed by b/d/l/f/s/J	typed output array pointer, int count	All getXXX methods

See the JSON tutorial, section Using JParserValFact , for examples on how to use JVal.

See also

JDecoderr::get

JEncoder::set

Advanced C Example:

JVal* jForecast[7]; //Array for 7 day forecast
JVal_get(rootVal,
         &err,
         "{ssdddAJ}",
         "city",&city,
         "desc",&desc,
         "temp",&temp,
         "humidity",&humidity,
         "dt", &dt,
         "list",jForecast,7);//Flag '{A}' requires: member name, list, length
if(JErr_noError(&err))
{
   for(i=0 ; i < 7 && JErr_noError(&err) ; i++)
   {
      JVal_get(jForecast[i],
               &err,
               "{dddds}",
               "wday",&wday,
               "tmax",&tmax,
               "tmin",&tmin,
               "humidity",&humidity,
               "desc",&desc);
   }
}

Parameters

err

Required initialized error container, preserved once set.

fmt

Required NUL-terminated format. Supply a member name before each object's output arguments. All output pointers must have the exact listed types. A is followed by b/d/l/f/s/J and takes an output array pointer then an int count. Extra source elements are ignored; output can be partially filled before failure. The current empty-array path can leave outputs unchanged without an error, so check the source length when requiring a fixed count. Strings and JVal pointers returned in outputs remain borrowed from the tree.

Returns

Pointer to the next unconsumed sibling, or NULL at the end or on failure. NULL alone is not an error test; inspect err.

getArray()

JVal * JVal::getArray

(

JErr *

e

)

Access the first child of an array node.

Parameters

e	Required initialized error container.

Returns

Borrowed first child, NULL for an empty container, or NULL with an error for the wrong type/missing C node. Inspect e to distinguish these cases.

getBoolean()

BaBool JVal::getBoolean

(

JErr *

e

)

Read a boolean or null node.

Parameters

e	Required initialized error container.

Returns

Stored boolean, FALSE for JSON null, or FALSE with an error for other types/missing C nodes. Numeric values are not treated as booleans.

getBufPrint()

BufPrint * JEncoder::getBufPrint

(

)

Query output storage.

Returns

Borrowed BufPrint pointer supplied at construction; no ownership transfer.

getDouble()

double JVal::getDouble

(

JErr *

e

)

Convert a numeric, boolean, or null node to double.

Parameters

e	Required initialized error container.

Returns

Converted value; null yields zero. Wrong types or a missing C node record an error and return zero. Numeric conversion uses C casts; it is not a range or integrality check. Integer conversion can lose precision.

getErr()

JErr * JEncoder::getErr

(

)

Query error storage.

Returns

Required borrowed JErr pointer supplied at construction; does not clear errors.

getErrT()

JErrT JErr::getErrT

(

)

Returns

Stored error type; JErrT_NoErr means no recorded error.

getExpT()

JVType JErr::getExpT

(

)

Returns

Expected JVType, meaningful only after a successful setTypeErr().

getInt()

S32 JVal::getInt

(

JErr *

e

)

Convert a numeric, boolean, or null node to S32.

Parameters

e	Required initialized error container.

Returns

Converted value; null yields zero. Wrong types or a missing C node record an error and return zero. Numeric conversion uses C casts; it is not a range or integrality check. Floating input must be finite and representable in the destination; fractional parts are discarded.

getJ()

JVal * JVal::getJ

(

JErr *

e

)

Access the first child of an object or array node.

Parameters

e	Required initialized error container.

Returns

Borrowed first child, NULL for an empty container, or NULL with an error for the wrong type/missing C node. Inspect e to distinguish these cases.

getLength()

S32 JVal::getLength

(

JErr *

e

)

Count immediate children of this object/array.

Parameters

e	Required initialized error container.

Returns

S32 child count, zero for an empty container or an error. Call on the container itself, not the first child; this walks the child list.

getLong()

S64 JVal::getLong

(

JErr *

e

)

Convert a numeric, boolean, or null node to S64.

Parameters

e	Required initialized error container.

Returns

Converted value; null yields zero. Wrong types or a missing C node record an error and return zero. Numeric conversion uses C casts; it is not a range or integrality check. Floating input must be finite and representable in the destination; fractional parts are discarded.

getName()

const char * JVal::getName

(

)

Returns

Borrowed member name, or NULL when absent. Use getNameLen() for embedded NUL bytes. The C function also accepts a NULL node. No ownership transfers.

getNameLen()

size_t JVal::getNameLen

(

)

Returns

Stored member-name byte length excluding the terminator. Requires a live node; an empty name can still be an object member.

getNextElem()

JVal * JVal::getNextElem

(

)

Returns

Borrowed next sibling, or NULL at the end. Requires a live node. This does not return a child or transfer ownership.

getObject()

JVal * JVal::getObject

(

JErr *

e

)

Access the first child of an object node.

Parameters

e	Required initialized error container.

Returns

Borrowed first child, NULL for an empty container, or NULL with an error for the wrong type/missing C node. Inspect e to distinguish these cases.

getRecT()

JVType JErr::getRecT

(

)

Returns

Received JVType, meaningful only after a successful setTypeErr().

getStatus()

JParsStat JParser::getStatus

(

)

Inspect the last parser result without changing state.

Returns

JParsStat value; initially DoneEOS, meaning ready for the first chunk. Done/DoneEOS accompany parse()=1, NeedMoreData accompanies 0, and error states accompany -1. See parse() for input-buffer lifetime.

getString()

const char * JVal::getString

(

JErr *

e

)

Access a string without transferring ownership.

Parameters

e	Required initialized error container.

Returns

Borrowed NUL-terminated bytes for a string, NULL for JSON null, or NULL with an error for other types/missing C nodes. Use getStringLen() to preserve embedded NUL bytes. The pointer expires on replacement or tree destruction.

getStringLen()

size_t JVal::getStringLen

(

)

Returns

Stored string byte length, excluding the terminator. Call on a live string node; this direct accessor does not check the type.

getType()

JVType JVal::getType

(

)

Returns

Stored JVType of this required live node; no conversion or validation.

isError()

bool JErr::isError

(

)

Returns

True if err is not JErrT_NoErr, false otherwise.

isObjectMember()

bool JVal::isObjectMember

(

)

Returns

True if a member-name pointer is present (including an empty name), false otherwise. Requires a live node; this does not inspect a parent pointer.

JEncoder()

JEncoder::JEncoder	(	JErr *	err,
		BufPrint *	out
	)

Initialize an encoder without writing output or resetting err.

Parameters

err	Required initialized JErr, borrowed for the encoder's lifetime.
out	Required initialized writer, borrowed for the same lifetime. Start with a clear JErr. The encoder never owns or frees these objects.

JEncoder_b64enc()

BA_API int JEncoder_b64enc	(	JEncoder *	o,
		const void *	source,
		S32	slen
	)

Write binary data as a quoted standard Base64 string.

Parameters

source	Readable bytes borrowed for this call; required for positive slen.
slen	Nonnegative source byte count.

Returns

The current implementation returns -1 even after successful output. A stored JErr indicates an actual format/write failure. This return-value limitation is pending implementation repair.

Parameters

o	Required initialized encoder.

JEncoder_beginArray()

BA_API int JEncoder_beginArray

(

JEncoder *

o

)

Begin a JSON array value; array elements have no member-name call.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Keep container nesting within 511 levels and balance all begin/end calls.

Parameters

o	Required initialized encoder.

JEncoder_beginObject()

BA_API int JEncoder_beginObject

(

JEncoder *

o

)

Begin a JSON object value; call setName() before each member value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Keep container nesting within 511 levels and balance all begin/end calls.

Parameters

o	Required initialized encoder.

JEncoder_commit()

BA_API int JEncoder_commit

(

JEncoder *

o

)

Permit a new top-level value and flush the writer.

Returns

Same result as flush(). The new-value flag is set even if flushing fails. This does not reset JErr or close/reset nested containers; call only after completing the current top-level value.

Parameters

o	Required initialized encoder.

JEncoder_constructor()

BA_API void JEncoder_constructor	(	JEncoder *	o,
		JErr *	err,
		BufPrint *	out
	)

Initialize an encoder without writing output or resetting err.

Parameters

err	Required initialized JErr, borrowed for the encoder's lifetime.
out	Required initialized writer, borrowed for the same lifetime. Start with a clear JErr. The encoder never owns or frees these objects.
o	Required storage to initialize.

JEncoder_endArray()

BA_API int JEncoder_endArray

(

JEncoder *

o

)

Close the current array after its final complete element.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Keep container nesting within 511 levels and balance all begin/end calls.

Parameters

o	Required initialized encoder.

JEncoder_endObject()

BA_API int JEncoder_endObject

(

JEncoder *

o

)

Close the current object after its final complete member.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Keep container nesting within 511 levels and balance all begin/end calls.

Parameters

o	Required initialized encoder.

JEncoder_flush()

BA_API int JEncoder_flush

(

JEncoder *

o

)

Flush the underlying writer if JErr is clear.

Returns

BufPrint::flush result, or -1 if JErr already records an error. A flush failure is not automatically copied into JErr. This does not validate balanced containers or reset encoder state.

Parameters

o	Required initialized encoder.

JEncoder_fmtString()

BA_API int JEncoder_fmtString	(	JEncoder *	o,
		const char *	fmt,
			...
	)

Format text inside JSON quotation marks.

Parameters

fmt	BufPrint format string, or NULL to write JSON null. Variadic arguments must match its conversions. Formatted text is not automatically JSON-escaped; use appropriate BufPrint conversions or setString() instead.

Returns

Intended to follow vFmtString().

Warning

The C++ wrapper forwards its va_list to the variadic C declaration, for which no implementation is present in the reviewed source. Use vFmtString() with a va_list or setString() until this is repaired.

Parameters

o	Required initialized encoder.

JEncoder_set()

BA_API int JEncoder_set	(	JEncoder *	o,
		const char *	fmt,
			...
	)

Encode/serialize C structs/data to JSON using formatted output.

The set method works in a similar fashion to the ANSI C function printf; thus, it performs formatted output conversion.

The method internally uses the 'setXXX' methods in this class for setting the actual value(s), where XXX is setInt, setLong, etc.. The following table shows the relationship between the format flags and the JSON value:

JSON type	Format flag	C type	Method
Number	d	S32	JEncoder::setInt
Number	l	S64	JEncoder::setLong
Number	f	double	JEncoder::setDouble
boolean	b	BaBool	JEncoder::setBoolean
string	s	const char*	JEncoder::setString
Any type	J	JVal*	All methods
Start object	{	n/a	JEncoder::beginObject
End object	}	n/a	JEncoder::endObject
Start array	[	n/a	JEncoder::beginArray
End array	]	n/a	JEncoder::endArray
Array	A followed by b, d, f, s, or J	int count, then typed array pointer	All setXXX methods

See also

JE_MEMBER

JVal::get

JDecoder::get

Parameters

fmt

Required NUL-terminated format with matching braces/brackets. Pass an object member name (const char*) before each object's value arguments. Flag n writes null without a value argument. Flag A takes an int count and an array pointer of BaBool, S32, double, const char*, or JVal* elements, selected by its following flag; long-integer arrays are not supported. All strings, arrays, and JVal trees are borrowed only for this call. Floating and JVal support depend on the build configuration.

Returns

Zero on success, -1 on format/value/output error. Check JErr as well; output is incremental and is not rolled back on failure.

Parameters

o	Required initialized encoder.

JEncoder_setBoolean()

BA_API int JEncoder_setBoolean	(	JEncoder *	o,
		BaBool	val
	)

Write a JSON boolean.

Parameters

val	boolean value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

Parameters

o	Required initialized encoder.

JEncoder_setDouble()

BA_API int JEncoder_setDouble	(	JEncoder *	o,
		double	val
	)

Write a JSON number.

Parameters

val	finite double value. Uses BufPrint floating formatting (%f), not a lossless round-trip conversion. Available only when double support is enabled.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

Parameters

o	Required initialized encoder.

JEncoder_setInt()

BA_API int JEncoder_setInt	(	JEncoder *	o,
		S32	val
	)

Write a JSON number.

Parameters

val	S32 signed integer value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

Parameters

o	Required initialized encoder.

JEncoder_setJV()

BA_API int JEncoder_setJV	(	JEncoder *	o,
		struct JVal *	val,
		BaBool	iterateNext
	)

Serialize a JVal node and its child values.

Parameters

val	Borrowed acyclic node/tree; NULL emits nothing.
iterateNext	False (default) handles this node only; true also serializes its next-linked siblings in the current container context. Member names are emitted for object-member nodes when needed. No tree storage is taken.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Not available when built with NO_JVAL_DEPENDENCY.

Parameters

o	Required initialized encoder.

JEncoder_setLong()

BA_API int JEncoder_setLong	(	JEncoder *	o,
		S64	val
	)

Write a JSON number.

Parameters

val	S64 signed integer value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

Parameters

o	Required initialized encoder.

JEncoder_setName()

BA_API int JEncoder_setName	(	JEncoder *	o,
		const char *	name
	)

Write an object member name before its value.

Parameters

name	Required borrowed NUL-terminated UTF-8 name, escaped as JSON. Call only inside an object, once before each value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

Parameters

o	Required initialized encoder.

JEncoder_setNull()

BA_API int JEncoder_setNull

(

JEncoder *

o

)

Write JSON null.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

Parameters

o	Required initialized encoder.

JEncoder_setString()

BA_API int JEncoder_setString	(	JEncoder *	o,
		const char *	val,
		size_t	len
	)

Write a quoted JSON string through BufPrint::jsonString.

Parameters

val	Borrowed UTF-8 bytes, or NULL to write JSON null.
len	Byte count, excluding any terminator; ignored when val is NULL. Embedded NUL bytes are encoded as part of the string.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

Parameters

o	Required initialized encoder.

JEncoder_vFmtString()

BA_API int JEncoder_vFmtString	(	JEncoder *	o,
		const char *	fmt,
		va_list	argList
	)

Write formatted text between JSON quotes, or JSON null.

Parameters

fmt	Borrowed BufPrint format string, or NULL for null. Ensure its output is properly escaped JSON string content; this function only adds outer quotes.
argList	Valid argument list matching fmt, consumed according to va_list rules. Use va_copy if the original list must be reused.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

Parameters

o	Required initialized encoder.

JErr()

JErr::JErr

(

)

Initialize only the error code to JErrT_NoErr.

Other fields are not initialized; use reset() if a cleared message pointer is needed.

JErr_setError()

BA_API int JErr_setError	(	JErr *	o,
		JErrT	err,
		const char *	msg
	)

Record an error only when no earlier error exists.

Parameters

err	Error type to store.
msg	Borrowed message pointer, or NULL. Retain its storage while the error is used.

Returns

Zero if recorded, -1 if an earlier error is preserved.

Parameters

o	Required initialized error object.

JErr_setTooFewParams()

BA_API int JErr_setTooFewParams

(

JErr *

o

)

Record JErrT_InvalidMethodParams with a static message if no error exists.

Returns

Zero if recorded, -1 if an earlier error is preserved.

Parameters

o	Required initialized error object.

JErr_setTypeErr()

BA_API int JErr_setTypeErr	(	JErr *	o,
		JVType	expT,
		JVType	recT
	)

Record JErrT_WrongType only when no earlier error exists.

Parameters

expT	Expected JVType.
recT	Received JVType.

Returns

Zero if recorded, -1 if an earlier error is preserved.

Parameters

o	Initialized error object, or NULL to return -1.

JParser()

JParser::JParser	(	JParserIntf *	intf,
		char *	nameBuf,
		int	namebufSize,
		AllocatorIntf *	alloc,
		int	extraStackLen = 0
	)

Create a JSON parser object.

Parameters

intf	Required borrowed interface with a non-NULL callback. Provide your own callback or use one of JParserValFact or JDecoder.
nameBuf	is a buffer required for temporarily storing parsed object member names. Required writable storage, retained for the parser lifetime; it must fit the longest name plus its terminator.
namebufSize	Positive capacity of nameBuf in bytes. This buffer does not grow; an oversized member name reports JParsStat_MemErr.
alloc	Borrowed allocator for string/number assembly, retained until destruction. Supply an allocation/reallocation/free-capable allocator for general input; NULL disables dynamic assembly rather than choosing a default.
extraStackLen	is an undocumented feature and must be set to 0.

JParser_constructor()

BA_API void JParser_constructor	(	JParser *	o,
		JParserIntf *	intf,
		char *	nameBuf,
		int	namebufSize,
		AllocatorIntf *	alloc,
		int	extraStackLen
	)

Create a JSON parser object.

Parameters

intf	Required borrowed interface with a non-NULL callback. Provide your own callback or use one of JParserValFact or JDecoder.
nameBuf	is a buffer required for temporarily storing parsed object member names. Required writable storage, retained for the parser lifetime; it must fit the longest name plus its terminator.
namebufSize	Positive capacity of nameBuf in bytes. This buffer does not grow; an oversized member name reports JParsStat_MemErr.
alloc	Borrowed allocator for string/number assembly, retained until destruction. Supply an allocation/reallocation/free-capable allocator for general input; NULL disables dynamic assembly rather than choosing a default.
extraStackLen	is an undocumented feature and must be set to 0.
o	Required storage to initialize.

JParser_destructor()

BA_API void JParser_destructor

(

JParser *

o

)

Free internal assembly storage.

The callback interface, nameBuf, allocator, and input chunks are borrowed and are not freed. Stop parsing first.

Parameters

o	Required initialized parser.

JParser_parse()

BA_API int JParser_parse	(	JParser *	o,
		const U8 *	buf,
		U32	size
	)

Feed or resume parsing a top-level JSON object or array.

Parameters

buf	Borrowed input chunk. Supply a new chunk after DoneEOS or NeedMoreData. After Done, the parser retains unread bytes from the previous chunk and ignores these new arguments; call again before replacing that buffer.
size	Byte length of a new chunk, excluding any terminator. Retain its storage until the parser has consumed it. No NUL termination is needed.

Returns

0 means more input is needed, 1 means one complete object/array was delivered, -1 means parsing, callback, allocation, or nesting failure. Done indicates unread bytes remain; DoneEOS indicates the chunk was exhausted. Neither proves that an entire external input stream contains just one value. At actual end of input, NeedMoreData means the document is incomplete. After failure, destroy and reinitialize before reuse; callbacks may already have changed application data. Top-level scalar values are not supported.

Note

This parser also accepts extensions such as comments and single-quoted strings. It is not a strict JSON conformance validator.

Parameters

o	Required initialized parser.

JVal_add()

BA_API int JVal_add	(	JVal *	o,
		JErr *	e,
		JVal *	child
	)

Prepend a child to an array.

Parameters

e	Required initialized error container.
child	Required detached node with next=NULL and no other owner. Use an unnamed node for an array element. No copy or allocation is performed.

Returns

Zero with ownership transferred, -1 on failure. Check the return as some linkage failures do not set e. Adds at the beginning of the array.

Parameters

o	Required live node.

JVal_addMember()

BA_API int JVal_addMember	(	JVal *	o,
		JErr *	e,
		const char *	memberName,
		JVal *	child,
		AllocatorIntf *	dAlloc
	)

Prepend a child to an object.

Parameters

e	Required initialized error container.
memberName	Required NUL-terminated name used only if child has no name. An existing child name is retained; this does not rename it or check duplicates.
child	Required detached node with next=NULL and no other owning parent.
dAlloc	Allocator used to copy a missing member name. If NULL, the supplied pointer is stored directly; its eventual release must still match tree ownership.

Returns

Zero on success, -1 on failure. Some linkage failures do not set e; check the return. A copied name can remain on child after failure. Success transfers child ownership to the tree and places it first, not last.

Parameters

o	Required live node.

JVal_get()

BA_API JVal * JVal_get	(	JVal *	o,
		JErr *	err,
		const char *	fmt,
			...
	)

Get any type of value(s) from a JVal node or JVal tree.

The get method works in a similar fashion to the ANSI C function scanf; thus, it performs formatted input conversion.

The method internally uses the 'getXXX' methods in this class for extracting the actual value(s), where XXX is Int, Long, etc.. The following table shows the relationship between the format flags and the JSON value extracted:

JSON type	Format flag	C type	Method
Number	d	S32*	JVal::getInt
Number	l	S64*	JVal::getLong
Number	f	double*	JVal::getDouble
boolean	b	BaBool*	JVal::getBoolean
string	s	const char**	JVal::getString
Any type	J	JVal**	All methods
Start object	{	n/a	JVal::getObject
End object	}	n/a	n/a
Start array	[	n/a	JVal::getArray
End array	]	n/a	n/a
Array	A followed by b/d/l/f/s/J	typed output array pointer, int count	All getXXX methods

See the JSON tutorial, section Using JParserValFact , for examples on how to use JVal.

See also

JDecoderr::get

JEncoder::set

Advanced C Example:

JVal* jForecast[7]; //Array for 7 day forecast
JVal_get(rootVal,
         &err,
         "{ssdddAJ}",
         "city",&city,
         "desc",&desc,
         "temp",&temp,
         "humidity",&humidity,
         "dt", &dt,
         "list",jForecast,7);//Flag '{A}' requires: member name, list, length
if(JErr_noError(&err))
{
   for(i=0 ; i < 7 && JErr_noError(&err) ; i++)
   {
      JVal_get(jForecast[i],
               &err,
               "{dddds}",
               "wday",&wday,
               "tmax",&tmax,
               "tmin",&tmin,
               "humidity",&humidity,
               "desc",&desc);
   }
}

Parameters

err

Required initialized error container, preserved once set.

fmt

Required NUL-terminated format. Supply a member name before each object's output arguments. All output pointers must have the exact listed types. A is followed by b/d/l/f/s/J and takes an output array pointer then an int count. Extra source elements are ignored; output can be partially filled before failure. The current empty-array path can leave outputs unchanged without an error, so check the source length when requiring a fixed count. Strings and JVal pointers returned in outputs remain borrowed from the tree.

Returns

Pointer to the next unconsumed sibling, or NULL at the end or on failure. NULL alone is not an error test; inspect err.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getArray()

BA_API JVal * JVal_getArray	(	JVal *	o,
		JErr *	e
	)

Access the first child of an array node.

Parameters

e	Required initialized error container.

Returns

Borrowed first child, NULL for an empty container, or NULL with an error for the wrong type/missing C node. Inspect e to distinguish these cases.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getBoolean()

BA_API BaBool JVal_getBoolean	(	JVal *	o,
		JErr *	e
	)

Read a boolean or null node.

Parameters

e	Required initialized error container.

Returns

Stored boolean, FALSE for JSON null, or FALSE with an error for other types/missing C nodes. Numeric values are not treated as booleans.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getDouble()

BA_API double JVal_getDouble	(	JVal *	o,
		JErr *	e
	)

Convert a numeric, boolean, or null node to double.

Parameters

e	Required initialized error container.

Returns

Converted value; null yields zero. Wrong types or a missing C node record an error and return zero. Numeric conversion uses C casts; it is not a range or integrality check. Integer conversion can lose precision.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getInt()

BA_API S32 JVal_getInt	(	JVal *	o,
		JErr *	e
	)

Convert a numeric, boolean, or null node to S32.

Parameters

e	Required initialized error container.

Returns

Converted value; null yields zero. Wrong types or a missing C node record an error and return zero. Numeric conversion uses C casts; it is not a range or integrality check. Floating input must be finite and representable in the destination; fractional parts are discarded.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getJ()

BA_API JVal * JVal_getJ	(	JVal *	o,
		JErr *	e
	)

Access the first child of an object or array node.

Parameters

e	Required initialized error container.

Returns

Borrowed first child, NULL for an empty container, or NULL with an error for the wrong type/missing C node. Inspect e to distinguish these cases.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getLength()

BA_API S32 JVal_getLength	(	struct JVal *	o,
		JErr *	e
	)

Count immediate children of this object/array.

Parameters

e	Required initialized error container.

Returns

S32 child count, zero for an empty container or an error. Call on the container itself, not the first child; this walks the child list.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getLong()

BA_API S64 JVal_getLong	(	JVal *	o,
		JErr *	e
	)

Convert a numeric, boolean, or null node to S64.

Parameters

e	Required initialized error container.

Returns

Converted value; null yields zero. Wrong types or a missing C node record an error and return zero. Numeric conversion uses C casts; it is not a range or integrality check. Floating input must be finite and representable in the destination; fractional parts are discarded.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getName()

BA_API const char * JVal_getName

(

JVal *

o

)

Returns

Borrowed member name, or NULL when absent. Use getNameLen() for embedded NUL bytes. The C function also accepts a NULL node. No ownership transfers.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getObject()

BA_API JVal * JVal_getObject	(	JVal *	o,
		JErr *	e
	)

Access the first child of an object node.

Parameters

e	Required initialized error container.

Returns

Borrowed first child, NULL for an empty container, or NULL with an error for the wrong type/missing C node. Inspect e to distinguish these cases.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_getString()

BA_API const char * JVal_getString	(	JVal *	o,
		JErr *	e
	)

Access a string without transferring ownership.

Parameters

e	Required initialized error container.

Returns

Borrowed NUL-terminated bytes for a string, NULL for JSON null, or NULL with an error for other types/missing C nodes. Use getStringLen() to preserve embedded NUL bytes. The pointer expires on replacement or tree destruction.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_manageJ()

BA_API JVal * JVal_manageJ	(	JVal *	o,
		JErr *	e
	)

Detach all children from an object/array, leaving the container empty.

Parameters

e	Required initialized error container.

Returns

Caller-owned first child and its complete sibling chain, or NULL for an empty container/error. Release using terminate() with the original allocators. The parent node itself is not detached or destroyed.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_manageName()

BA_API char * JVal_manageName

(

JVal *

o

)

Detach the member name and clear its pointer/length in the node.

Returns

Caller-owned string to release through the original data allocator, or NULL if absent. The C function accepts NULL. The node is no longer marked as an object member after its name is detached.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_manageString()

BA_API char * JVal_manageString	(	JVal *	o,
		JErr *	e
	)

Detach a string's storage, leaving a String node with NULL data and zero length.

Parameters

e	Required initialized error container.

Returns

Previously owned string pointer, now caller-owned; release through the original data allocator. NULL can mean no stored pointer or a type/missing-node error; inspect e. JSON null is a type error for this operation.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JVal_setX()

BA_API void JVal_setX	(	JVal *	o,
		JErr *	e,
		JVType	t,
		void *	v
	)

Low-level scalar replacement used by the typed setter macros.

Parameters

o	Required live scalar node; objects/arrays cannot be replaced.
e	Required initialized error container. An attached old string must first be detached; failure is reported here, with no return value.
t	New type: Int, Long, Double (when enabled), Boolean, String, or Null.
v	Pointer to S32, S64, double, or BaBool storage matching t; for String it is the string itself and ownership transfers on success. NULL is accepted for Null and as a stored String pointer. See the typed setters for lifetime.

JVal_terminate()

BA_API void JVal_terminate	(	JVal *	o,
		AllocatorIntf *	vAlloc,
		AllocatorIntf *	dAlloc
	)

Free this node, all descendants, and all following siblings recursively.

Parameters

vAlloc	Required original allocator for node storage.
dAlloc	Required original allocator for strings/member names. Detach the chain from its owner before calling; every freed pointer becomes invalid. Allocators must accept all storage being released. The C function accepts NULL for an empty chain, but a C++ member call still requires a node.
o	Node pointer; see the operation contract for NULL handling.

JVal_unlink()

BA_API int JVal_unlink	(	JVal *	o,
		JVal *	child
	)

Remove one immediate child without destroying it.

Parameters

child

Required child to detach from this live object/array.

Returns

Zero when found and removed, -1 otherwise. Success clears child->next and transfers that node/subtree to the caller; its member name is retained.

Parameters

o	Required live node.

JVal_vget()

BA_API JVal * JVal_vget	(	JVal *	o,
		JErr *	err,
		const char **	fmt,
		va_list *	argList
	)

Extract values as for get(), using mutable format and argument cursors.

Parameters

err	Required initialized error container.
fmt	Required pointer to a NUL-terminated format cursor, advanced by parsing.
argList	Required pointer to a matching initialized va_list, consumed.

Returns

Remaining sibling pointer, possibly NULL on success; inspect err.

Parameters

o	Node pointer; see the operation contract for NULL handling.

JValFact()

JValFact::JValFact	(	AllocatorIntf *	vAlloc,
		AllocatorIntf *	dAlloc
	)

Initialize a factory without allocating a tree.

Parameters

vAlloc	Required borrowed allocator for nodes.
dAlloc	Required borrowed allocator for strings. Allocators may be the same and must outlive all storage they allocate. NULL does not select a default. The caller owns created nodes; the factory does not track or free them.

JValFact_constructor()

BA_API void JValFact_constructor	(	JValFact *	o,
		AllocatorIntf *	vAlloc,
		AllocatorIntf *	dAlloc
	)

Initialize a factory without allocating a tree.

Parameters

vAlloc	Required borrowed allocator for nodes.
dAlloc	Required borrowed allocator for strings. Allocators may be the same and must outlive all storage they allocate. NULL does not select a default. The caller owns created nodes; the factory does not track or free them.
o	Required storage to initialize.

JValFact_mkVal()

BA_API JVal * JValFact_mkVal	(	JValFact *	o,
		JVType	t,
		const void *	uv
	)

Allocate a detached typed value.

Parameters

o	Required initialized factory.
t	Supported JVType, excluding InvalidType; Double requires double support.
uv	Pointer to the matching S32/S64/double/BaBool scalar, or the required NUL-terminated string itself for String. Ignored for Null/Object/Array. Values and strings are copied, not retained.

Returns

Caller-owned node, or NULL on allocation failure. Empty objects/arrays have no children. Free with the factory's node and data allocators.

manageJ()

JVal * JVal::manageJ

(

JErr *

e

)

Detach all children from an object/array, leaving the container empty.

Parameters

e	Required initialized error container.

Returns

Caller-owned first child and its complete sibling chain, or NULL for an empty container/error. Release using terminate() with the original allocators. The parent node itself is not detached or destroyed.

manageName()

char * JVal::manageName

(

)

Detach the member name and clear its pointer/length in the node.

Returns

Caller-owned string to release through the original data allocator, or NULL if absent. The C function accepts NULL. The node is no longer marked as an object member after its name is detached.

manageString()

char * JVal::manageString

(

JErr *

e

)

Detach a string's storage, leaving a String node with NULL data and zero length.

Parameters

e	Required initialized error container.

Returns

Previously owned string pointer, now caller-owned; release through the original data allocator. NULL can mean no stored pointer or a type/missing-node error; inspect e. JSON null is a type error for this operation.

mkArray()

JVal * JValFact::mkArray

(

)

Create a detached array node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators. The container starts empty.

mkBoolean()

JVal * JValFact::mkBoolean

(

bool

v

)

Create a detached boolean node.

Parameters

v	Value copied into the new node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

mkDouble()

JVal * JValFact::mkDouble

(

double

v

)

Create a detached double node.

Parameters

v	Value copied into the new node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

mkInt()

JVal * JValFact::mkInt

(

S32

v

)

Create a detached int node.

Parameters

v	Value copied into the new node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

mkLong()

JVal * JValFact::mkLong

(

S64

v

)

Create a detached long node.

Parameters

v	Value copied into the new node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

mkNull()

JVal * JValFact::mkNull

(

)

Create a detached null node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

mkObject()

JVal * JValFact::mkObject

(

)

Create a detached object node.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators. The container starts empty.

mkString()

JVal * JValFact::mkString

(

const char *

v

)

Create a detached string node.

Parameters

v	Required NUL-terminated string, copied with dAlloc.

Returns

Caller-owned node, or NULL on allocation failure. Attach it to a tree or release it with JVal::terminate and the factory's original allocators.

noError()

bool JErr::noError

(

)

Returns

True if err is JErrT_NoErr, false otherwise.

parse()

int JParser::parse	(	const U8 *	buf,
		U32	size
	)

Feed or resume parsing a top-level JSON object or array.

Parameters

buf	Borrowed input chunk. Supply a new chunk after DoneEOS or NeedMoreData. After Done, the parser retains unread bytes from the previous chunk and ignores these new arguments; call again before replacing that buffer.
size	Byte length of a new chunk, excluding any terminator. Retain its storage until the parser has consumed it. No NUL termination is needed.

Returns

0 means more input is needed, 1 means one complete object/array was delivered, -1 means parsing, callback, allocation, or nesting failure. Done indicates unread bytes remain; DoneEOS indicates the chunk was exhausted. Neither proves that an entire external input stream contains just one value. At actual end of input, NeedMoreData means the document is incomplete. After failure, destroy and reinitialize before reuse; callbacks may already have changed application data. Top-level scalar values are not supported.

Note

This parser also accepts extensions such as comments and single-quoted strings. It is not a strict JSON conformance validator.

reset()

void JErr::reset

(

)

Clear the error code and message pointer so the object can be reused.

Expected/received type fields are not reset.

set()

int JEncoder::set	(	const char *	fmt,
			...
	)

Encode/serialize C structs/data to JSON using formatted output.

The set method works in a similar fashion to the ANSI C function printf; thus, it performs formatted output conversion.

The method internally uses the 'setXXX' methods in this class for setting the actual value(s), where XXX is setInt, setLong, etc.. The following table shows the relationship between the format flags and the JSON value:

JSON type	Format flag	C type	Method
Number	d	S32	JEncoder::setInt
Number	l	S64	JEncoder::setLong
Number	f	double	JEncoder::setDouble
boolean	b	BaBool	JEncoder::setBoolean
string	s	const char*	JEncoder::setString
Any type	J	JVal*	All methods
Start object	{	n/a	JEncoder::beginObject
End object	}	n/a	JEncoder::endObject
Start array	[	n/a	JEncoder::beginArray
End array	]	n/a	JEncoder::endArray
Array	A followed by b, d, f, s, or J	int count, then typed array pointer	All setXXX methods

See also

JE_MEMBER

JVal::get

JDecoder::get

Parameters

fmt

Required NUL-terminated format with matching braces/brackets. Pass an object member name (const char*) before each object's value arguments. Flag n writes null without a value argument. Flag A takes an int count and an array pointer of BaBool, S32, double, const char*, or JVal* elements, selected by its following flag; long-integer arrays are not supported. All strings, arrays, and JVal trees are borrowed only for this call. Floating and JVal support depend on the build configuration.

Returns

Zero on success, -1 on format/value/output error. Check JErr as well; output is incremental and is not rolled back on failure.

setBoolean() [1/2]

int JEncoder::setBoolean

(

bool

val

)

Write a JSON boolean.

Parameters

val	boolean value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

setBoolean() [2/2]

void JVal::setBoolean	(	JErr *	e,
		BaBool	v
	)

Replace a scalar value and set its type.

Parameters

e	Required initialized error container receiving refusal details.
v	New BaBool value. No return value; inspect e. Cannot replace an object/array or an attached string. Detach and release an old string first. Requires a live non-NULL node; existing errors do not by themselves prevent this setter from changing the node.

setDouble() [1/2]

int JEncoder::setDouble

(

double

val

)

Write a JSON number.

Parameters

val	finite double value. Uses BufPrint floating formatting (%f), not a lossless round-trip conversion. Available only when double support is enabled.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

setDouble() [2/2]

void JVal::setDouble	(	JErr *	e,
		double	v
	)

Replace a scalar value and set its type.

Parameters

e	Required initialized error container receiving refusal details.
v	New double value. No return value; inspect e. Cannot replace an object/array or an attached string. Detach and release an old string first. Requires a live non-NULL node; existing errors do not by themselves prevent this setter from changing the node.

setError()

int JErr::setError	(	JErrT	err,
		const char *	msg
	)

Record an error only when no earlier error exists.

Parameters

err	Error type to store.
msg	Borrowed message pointer, or NULL. Retain its storage while the error is used.

Returns

Zero if recorded, -1 if an earlier error is preserved.

setInt() [1/2]

void JVal::setInt	(	JErr *	e,
		S32	v
	)

Replace a scalar value and set its type.

Parameters

e	Required initialized error container receiving refusal details.
v	New S32 value. No return value; inspect e. Cannot replace an object/array or an attached string. Detach and release an old string first. Requires a live non-NULL node; existing errors do not by themselves prevent this setter from changing the node.

setInt() [2/2]

int JEncoder::setInt

(

S32

val

)

Write a JSON number.

Parameters

val	S32 signed integer value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

setJV()

int JEncoder::setJV	(	struct JVal *	val,
		bool	iterateNext = false
	)

Serialize a JVal node and its child values.

Parameters

val	Borrowed acyclic node/tree; NULL emits nothing.
iterateNext	False (default) handles this node only; true also serializes its next-linked siblings in the current container context. Member names are emitted for object-member nodes when needed. No tree storage is taken.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written. Not available when built with NO_JVAL_DEPENDENCY.

setLong() [1/2]

void JVal::setLong	(	JErr *	e,
		S64	v
	)

Replace a scalar value and set its type.

Parameters

e	Required initialized error container receiving refusal details.
v	New S64 value. No return value; inspect e. Cannot replace an object/array or an attached string. Detach and release an old string first. Requires a live non-NULL node; existing errors do not by themselves prevent this setter from changing the node.

setLong() [2/2]

int JEncoder::setLong

(

S64

val

)

Write a JSON number.

Parameters

val	S64 signed integer value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

setName()

int JEncoder::setName

(

const char *

name

)

Write an object member name before its value.

Parameters

name	Required borrowed NUL-terminated UTF-8 name, escaped as JSON. Call only inside an object, once before each value.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

setNull() [1/2]

int JEncoder::setNull

(

)

Write JSON null.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

setNull() [2/2]

void JVal::setNull

(

JErr *

e

)

Replace a scalar value with JSON null.

Parameters

e	Required initialized error container. Objects/arrays and attached strings cannot be replaced; detach/release a string first. Requires a live non-NULL node. No return value; inspect e.

setString() [1/2]

int JEncoder::setString	(	const char *	val,
		size_t	len
	)

Write a quoted JSON string through BufPrint::jsonString.

Parameters

val	Borrowed UTF-8 bytes, or NULL to write JSON null.
len	Byte count, excluding any terminator; ignored when val is NULL. Embedded NUL bytes are encoded as part of the string.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

setString() [2/2]

void JVal::setString	(	JErr *	e,
		char *	v
	)

Store a string pointer without copying it and set the node's type.

Parameters

e	Required initialized error container receiving refusal details.
v	NUL-terminated string allocated compatibly with the tree's data allocator, or NULL for an empty stored pointer. strlen determines its length. On success the node takes ownership. On failure ownership stays with the caller. Detach/release an old string first; object/array nodes cannot be replaced. Requires a live node. No return value; inspect e.

setTooFewParams()

int JErr::setTooFewParams

(

)

Record JErrT_InvalidMethodParams with a static message if no error exists.

Returns

Zero if recorded, -1 if an earlier error is preserved.

setTypeErr()

int JErr::setTypeErr	(	JVType	expT,
		JVType	recT
	)

Record JErrT_WrongType only when no earlier error exists.

Parameters

expT	Expected JVType.
recT	Received JVType.

Returns

Zero if recorded, -1 if an earlier error is preserved.

terminate()

void JVal::terminate	(	AllocatorIntf *	vAlloc,
		AllocatorIntf *	dAlloc
	)

Free this node, all descendants, and all following siblings recursively.

Parameters

vAlloc	Required original allocator for node storage.
dAlloc	Required original allocator for strings/member names. Detach the chain from its owner before calling; every freed pointer becomes invalid. Allocators must accept all storage being released. The C function accepts NULL for an empty chain, but a C++ member call still requires a node.

unlink()

int JVal::unlink

(

JVal *

child

)

Remove one immediate child without destroying it.

Parameters

child

Required child to detach from this live object/array.

Returns

Zero when found and removed, -1 otherwise. Success clears child->next and transfers that node/subtree to the caller; its member name is retained.

vFmtString()

int JEncoder::vFmtString	(	const char *	fmt,
		va_list	argList
	)

Write formatted text between JSON quotes, or JSON null.

Parameters

fmt	Borrowed BufPrint format string, or NULL for null. Ensure its output is properly escaped JSON string content; this function only adds outer quotes.
argList	Valid argument list matching fmt, consumed according to va_list rules. Use va_copy if the original list must be reused.

Returns

Zero on success, -1 for a stored format/value or output error. Inspect getErr(); output may already be partially written.

vget()

JVal * JVal::vget	(	JErr *	err,
		const char **	fmt,
		va_list *	argList
	)

Extract values as for get(), using mutable format and argument cursors.

Parameters

err	Required initialized error container.
fmt	Required pointer to a NUL-terminated format cursor, advanced by parsing.
argList	Required pointer to a matching initialized va_list, consumed.

Returns

Remaining sibling pointer, possibly NULL on success; inspect err.

~JEncoder()

JEncoder::~JEncoder

(

)

Call flush() without freeing the borrowed writer or error object.

The C++ destructor cannot report a flush failure; call flush() explicitly and check its result before destruction when the outcome matters.

~JParser()

JParser::~JParser

(

)

Free internal assembly storage.

The callback interface, nameBuf, allocator, and input chunks are borrowed and are not freed. Stop parsing first.