OjC API

Introduction

Optimized JSON in C (OjC), as the name implies, was written to provide performant JSON handling. The primary focus is for applications that need the maximum performance when reading large JSON document from a file or socket. Functions for building, formatting, and writing JSON are also part of the library.

There are a number of options for parsing JSON to address a variety of use cases but in all cases an attempt was made to keep the API as easy to use as possible. The code itself is fairly direct in regard to implementing the algorithms selected in an attempt to make it easy to read and follow. At least that was goal. It is up to the reader to make that judgement though.

Since the code is Open Source most of the types and structs are exposed. There is no reason to hide them when someone can just look at the code and modify it anyway. An object model is used for functions and structures. At the core is the ojVal struct that represents the elements of a JSON document. Generally functions start with the name of the type they are associated with such as oj_build_object() for a function that uses an ojBuilder type. The ojVal is the exception as it is the code so functions such as oj_double_get() forgo the oj_val prefix that might be expected.

In the interest of keeping OjC is as flexible as possible, OjC can not only read from files but also from any file descriptor whether it represents a file, socket, or some other stream. There are no restrictions on how multiple JSON documents appear in the stream other than each document must be valid JSON and only white space is allowed between JSON documents. Formatted or indented JSON is accepted as well as compact JSON that is on one line. Callback APIs are used when parsing streams containing multiple JSON documents.

Validate JSON String

Found in the examples/validate directory.

#include <stdio.h> #include "oj/oj.h" int main(int argc, char **argv) { const char *str = "{\n" " \"num\": 12.34e567\n" "}"; struct _ojErr err = OJ_ERR_INIT; ojStatus status; printf("Validating %s\n", str); status = oj_validate_str(&err, str); if (OJ_OK == status) { printf("Valid!\n"); } else { printf("Validation error: %s at %d:%d\n", err.msg, err.line, err.col); } return err.code; }

Parse JSON String

Parse a JSON string and return an JSON element as an ojVal. ojVal is the type used to represent JSON element in the OjC library.

#include <stdio.h> #include "oj/oj.h" int main(int argc, char **argv) { const char *str = "{\n" " \"num\": 12.34e567\n" "}"; struct _ojErr err = OJ_ERR_INIT; ojVal val; printf("Parsing %s\n", str); val = oj_parse_str(&err, str, NULL); if (NULL != val) { // could check err.code instead for OJ_OK printf("Success!\n"); // Proper memory management releases memoory when no longer // needed. This is one way to cleanup. oj_destroy(val); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } // Another way to return memory is to use the ojReuser. This is slightly // more efficient. Parsing the same string with ojReuser looks like this: struct _ojReuser reuser; oj_err_init(&err); printf("Parsing %s\n", str); val = oj_parse_str(&err, str, &reuser); if (OJ_OK == err.code) { printf("Success!\n"); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } oj_reuse(&reuser); return err.code; }

Push-Pop Parse String

Parse a JSON string using callbacks on each element. For every element the push callback is made. The pop callback is called when an array or object close is encountered. This approach is similar to the XML SAX parsers or the Ruby Oj SCP parser and Oj::ScHandler. It can be more efficient if there is no need to build a full JSON structure in memory. It is also useful when parsing a string that contains multiple JSON documents.

#include <stdio.h> #include "oj/oj.h" typedef struct _cnt { int iter; int depth; } *Cnt; static void push(ojVal val, void *ctx) { switch (val->type) { case OJ_OBJECT: case OJ_ARRAY: ((Cnt)ctx)->depth++; break; } printf("push a %s\n", oj_type_str(val->type)); } static void pop(void *ctx) { Cnt c = (Cnt)ctx; c->depth--; if (c->depth <= 0) { c->iter++; } printf("pop\n"); } int main(int argc, char **argv) { const char *str = "{\n" " \"num\": 12.34e567\n" "}\n" "{\n" " \"string\": \"a string\"\n" "}"; struct _ojErr err = OJ_ERR_INIT; ojStatus status; struct _cnt c = { .depth = 0, .iter = 0 }; printf("Parsing %s\n", str); status = oj_pp_parse_str(&err, str, push, pop, &c); if (OJ_OK == status) { printf("Parsed %d documents\n", c.iter); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } return err.code; }

Callback Parse String

Parse a JSON string using callbacks on each document. For every document the callback is invoked. This is an effective way to iterate over multiple documents in a string.

The callback function's return value indicates to the parser what whould be done after the callback. If the document (val) is no longer needed then OJ_DESTROY is returned. If the parsing should be stopped then OJ_STOP is returned. To both stop and cleanup the two values are ORed together (OJ_DESTROY | OJ_STOP).

#include <stdio.h> #include "oj/oj.h" static ojCallbackOp callback(ojVal val, void *ctx) { *(int*)ctx = *(int*)ctx + 1; return OJ_DESTROY; } int main(int argc, char **argv) { const char *str = "{\n" " \"num\": 12.34e567\n" "}\n" "{\n" " \"string\": \"a string\"\n" "}"; struct _ojErr err = OJ_ERR_INIT; ojStatus status; int iter = 0; printf("Parsing %s\n", str); status = oj_parse_str_cb(&err, str, callback, &iter); if (OJ_OK == status) { printf("Parsed %d documents\n", iter); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } return err.code; }

Caller Parse String

Parse a JSON string using callbacks on each document. For every document the callback is invoked but invoked in a thread separate from the parser. This is an effective way to iterate over multiple documents in a string where significant processing time is spent on each document. There is some overhead using the caller so it is best used when there is some processing of the documents involved.

The callback function's return value indicates to the parser what whould be done after the callback. If the document (val) is no longer needed then OJ_DESTROY is returned. If the parsing should be stopped then OJ_STOP is returned. To both stop and cleanup the two values are ORed together (OJ_DESTROY | OJ_STOP).

#include <stdio.h> #include "oj/oj.h" static ojCallbackOp callback(ojVal val, void *ctx) { *(int*)ctx = *(int*)ctx + 1; return OJ_DESTROY; } int main(int argc, char **argv) { const char *str = "{\n" " \"num\": 12.34e567\n" "}\n" "{\n" " \"string\": \"a string\"\n" "}"; struct _ojErr err = OJ_ERR_INIT; ojStatus status; struct _ojCaller caller; int iter = 0; // Since multiple threads are being used, make sure the thread safe mode // it activated. oj_thread_safe = true; // Stater the caller. The caller contains the thread that will invoke the // callback function. oj_caller_start(&err, &caller, callback, &iter); printf("Parsing %s\n", str); status = oj_parse_str_call(&err, str, &caller); // Wait for the caller to finish processing. oj_caller_wait(&caller); if (OJ_OK == status) { printf("Parsed %d documents\n", iter); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } return err.code; }

Parse File

Parse a JSON file and return an JSON element as an ojVal. ojVal is the type used to represent JSON element in the OjCz library.

#include <stdio.h> #include <stdlib.h> #include "oj/oj.h" int main(int argc, char **argv) { const char *filename = "sample.json"; struct _ojErr err = OJ_ERR_INIT; ojVal val; printf("Parsing %s\n", filename); val = oj_parse_file(&err, filename, NULL); if (NULL != val) { // could check err.code instead for OJ_OK char *str = oj_to_str(val, 0); printf("Parsed %s\n", str); free(str); // Proper memory management releases memoory when no longer // needed. This is one way to cleanup. oj_destroy(val); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } // Another way to return memory is to use the ojReuser. This is slightly // more efficient. Parsing the same file with ojReuser looks like this: struct _ojReuser reuser; oj_err_init(&err); printf("Parsing %s\n", filename); val = oj_parse_file(&err, filename, &reuser); if (OJ_OK == err.code) { char *str = oj_to_str(val, 0); printf("Parsed %s\n", str); free(str); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } oj_reuse(&reuser); return err.code; }

The input file, sample.json has the following content although and JSON file should be fine.

{ "num": 12.34e567 }

Push-Pop Parse File

Parse a JSON file using callbacks on each element. For every element the push callback is made. The pop callback is called when an array or object close is encountered. This approach is similar to the XML SAX parsers or the Ruby Oj SCP parser and Oj::ScHandler. It can be more efficient if there is no need to build a full JSON structure in memory. It is also useful when parsing a file that contains multiple JSON documents.

#include <stdio.h> #include "oj/oj.h" typedef struct _cnt { int iter; int depth; } *Cnt; static void push(ojVal val, void *ctx) { switch (val->type) { case OJ_OBJECT: case OJ_ARRAY: ((Cnt)ctx)->depth++; break; } printf("push a %s\n", oj_type_str(val->type)); } static void pop(void *ctx) { Cnt c = (Cnt)ctx; c->depth--; if (c->depth <= 0) { c->iter++; } printf("pop\n"); } int main(int argc, char **argv) { const char *filename = "sample.json"; struct _ojErr err = OJ_ERR_INIT; ojStatus status; struct _cnt c = { .depth = 0, .iter = 0 }; printf("Parsing %s\n", filename); status = oj_pp_parse_file(&err, filename, push, pop, &c); if (OJ_OK == status) { printf("Parsed %d documents\n", c.iter); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } return err.code; }

The input file, sample.json has the following content although and JSON file should be fine.

{ { "num": 12.34e567 } { "string": "a string" }

Callback Parse File

Parse a JSON file using callbacks on each document. For every document the callback is invoked. This is an effective way to iterate over multiple documents in a file.

The callback function's return value indicates to the parser what whould be done after the callback. If the document (val) is no longer needed then OJ_DESTROY is returned. If the parsing should be stopped then OJ_STOP is returned. To both stop and cleanup the two values are ORed together (OJ_DESTROY | OJ_STOP).

#include <stdio.h> #include "oj/oj.h" static ojCallbackOp callback(ojVal val, void *ctx) { *(int*)ctx = *(int*)ctx + 1; return OJ_DESTROY; } int main(int argc, char **argv) { const char *filename = "sample.json"; struct _ojErr err = OJ_ERR_INIT; ojStatus status; int iter = 0; printf("Parsing %s\n", filename); status = oj_parse_file_cb(&err, filename, callback, &iter); if (OJ_OK == status) { printf("Parsed %d documents\n", iter); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } return err.code; }

The input file, sample.json has the following content although and JSON file should be fine.

{ { "num": 12.34e567 } { "string": "a string" }

Caller Parse File

Parse a JSON file using callbacks on each document. For every document the callback is invoked but invoked in a thread separate from the parser. This is an effective way to iterate over multiple documents in a file where significant processing time is spent on each document. There is some overhead using the caller so it is best used when there is some processing of the documents involved.

The callback function's return value indicates to the parser what whould be done after the callback. If the document (val) is no longer needed then OJ_DESTROY is returned. If the parsing should be stopped then OJ_STOP is returned. To both stop and cleanup the two values are ORed together (OJ_DESTROY | OJ_STOP).

#include <stdio.h> #include "oj/oj.h" static ojCallbackOp callback(ojVal val, void *ctx) { *(int*)ctx = *(int*)ctx + 1; return OJ_DESTROY; } int main(int argc, char **argv) { const char *filename = "sample.json"; struct _ojErr err = OJ_ERR_INIT; ojStatus status; struct _ojCaller caller; int iter = 0; // Since multiple threads are being used, make sure the thread safe mode // it activated. oj_thread_safe = true; // Stater the caller. The caller contains the thread that will invoke the // callback function. oj_caller_start(&err, &caller, callback, &iter); printf("Parsing %s\n", filename); status = oj_parse_file_call(&err, filename, &caller); // Wait for the caller to finish processing. oj_caller_wait(&caller); if (OJ_OK == status) { printf("Parsed %d documents\n", iter); } else { printf("Parse error: %s at %d:%d\n", err.msg, err.line, err.col); } return err.code; }

The input file, sample.json has the following content although and JSON file should be fine.

{ { "num": 12.34e567 } { "string": "a string" }

Build and Write

This example demonstrates the use of the ojBuilder to construct a JSON document as well as writing the document to a file as indented JSON.

#include <stdio.h> #include "oj/oj.h" int main(int argc, char **argv) { struct _ojBuilder b = OJ_BUILDER_INIT; oj_build_object(&b, NULL); oj_build_double(&b, "num", 12.34e567L); oj_build_array(&b, "list"); oj_build_bool(&b, NULL, true); oj_build_bool(&b, NULL, false); oj_build_pop(&b); oj_build_pop(&b); if (OJ_OK != b.err.code) { printf("Build error: %s at %d:%d\n", b.err.msg, b.err.line, b.err.col); return 1; } char buf[256]; struct _ojErr err = OJ_ERR_INIT; oj_fill(&err, b.top, 2, buf, sizeof(buf)); printf("Built %s\n", buf); // Once written, the file should look like the output displayed by printf. oj_fwrite(&err, b.top, 2, "out.json"); if (OJ_OK != err.code) { printf("Build error: %s at %d:%d\n", err.msg, err.line, err.col); return 1; } return 0; }

ojCallbackOp

typedef enum { OJ_CONTINUE = 0x00, OJ_STOP = 0x01, OJ_DESTROY = 0x02, } ojCallbackOp;

This enum is for the return values of the ojParseCallback functions.

OJ_CONTINUE	Indicates parsing should continue.
OJ_STOP	Indicates parsing should stop.
OJ_DESTROY	Indicates the ojVal argument to the callback should be freed. This value can be OR-ed with either OJ_CONTINUE or OJ_STOP.

ojMod

typedef enum { OJ_OBJ_RAW = '\0', OJ_OBJ_HASH = 'h', } ojMod;

Used to indicate how object members are stored in a value.

OJ_OBJ_RAW	Members are stores as a simple list.
OJ_OBJ_HASH	Members are store in a fixed size hash.

ojStatus

typedef enum { OJ_OK = 0, OJ_ERR_MEMORY = ENOMEM, OJ_ERR_PARSE = OJ_ERR_START, OJ_ERR_READ, OJ_ERR_WRITE, OJ_ERR_OVERFLOW, OJ_ERR_ARG, OJ_ERR_TOO_MANY, OJ_ERR_TYPE, OJ_ERR_KEY, OJ_ABORT, OJ_ERR_LAST, } ojStatus;

Functions that can fail take an ojErr argument. If an error occurs the fields of the ojErr are set. The ojErr.code is set to either one of the errors in errno.h or to one of the ojStatus enum values.

OJ_OK	No error, Okay
OJ_ERR_MEMORY	A memory error
OJ_ERR_PARSE	A parse error
OJ_ERR_READ	A read error
OJ_ERR_WRITE	A write error
OJ_ERR_OVERFLOW	An overflow error
OJ_ERR_ARG	An argument error
OJ_ERR_TOO_MANY	Too many of something error
OJ_ERR_TYPE	A type error
OJ_ERR_KEY	A key error
OJ_ABORT	An indication that parsing should stop
OJ_ERR_LAST	Maximum enum value

ojType

typedef enum { OJ_NONE = '\0', OJ_NULL = 'n', OJ_TRUE = 't', OJ_FALSE = 'f', OJ_INT = 'i', OJ_DECIMAL = 'd', OJ_BIG = 'b', OJ_STRING = 's', OJ_OBJECT = 'o', OJ_ARRAY = 'a', } ojType;

Used to identify ojVal types.

OJ_NONE	Type not set
OJ_NULL	Value is a JSON null
OJ_TRUE	Value is a JSON true
OJ_FALSE	Value is a JSON false
OJ_INT	Value is a int64_t
OJ_DECIMAL	Value is a long double
OJ_BIG	Value is a bignum stored as a string (const char*)
OJ_STRING	Value is a string (const char*)
OJ_OBJECT	Value is a JSON object
OJ_ARRAY	Value is a JSON array

ojBuf

typedef struct _ojBuf { char *head; char *end; char *tail; int fd; bool realloc_ok; ojStatus err; char base[4096]; } *ojBuf;

Used for building strings as well as writing to files. The buffer starts out with a fixed size base and appends to that until more space is needed. If more space is needed it is allocated. If fronting for a file then the buffer is written and the tail is reset.

char*	head	Always points to the string being built
char*	end	Marks the end of the buffer
char*	tail	The current or next position to write to
int	fd	fiel descriptor to write to is not 0
bool	realloc_ok	A flag indicating reallocation is okay. Set to false if used for reading only.
ojStatus	err	Error indicator
char	base[4096]	Built in buffer

ojBuilder

typedef struct _ojBuilder { ojVal top; ojVal stack; struct _ojErr err; } *ojBuilder;

Used for building ojVal JSON documents. A stack based approach is used making use of the ojVal.next field.

ojVal	top	Top of the document
ojVal	stack	The stack
struct _ojErr	err	Place to store errors

ojCall

typedef struct _ojCall { ojVal val; struct _ojReuser reuser; atomic_flag busy; } *ojCall;

Struct used internally by the ojCaller.

ojVal	val	Value for callbacks
struct _ojReuser	reuser	Used to return values to the pool
atomic_flag	busy	Concurrent use protection

ojCaller

typedef struct _ojCaller { struct _ojCall queue[256]; pthread_t thread; ojParseCallback cb; void *ctx; ojCall end; ojCall tail; atomic_flag starting; volatile bool done; } *ojCaller;

Used for concurrent callbacks. The fields in the struct should not be modified directly. The correct use of the caller when parsing is to first call the oj_caller_start() and then finish up with oj_caller_wait() after the parser is called.

struct _ojCall	queue[256]	Callback queue
pthread_t	thread	Thread invoking the callback
ojParseCallback	cb	The callback
void*	ctx	The callback context
ojCall	end	The end of the queue
ojCall	tail	Last slot for the callback thread
atomic_flag	starting	Concurrent protection flag
volatile bool	done	Indicator that callbacks are complete

ojErr

typedef struct _ojErr { int code; int line; int col; char msg[256]; } *ojErr;

Struct to store error information.

int	code	Error code (ojStatus)
int	line	Line in document the error occured on if applicable
int	col	Column in document the error occured on if applicable
char	msg[256]	Message describing the error

ojList

typedef struct _ojList { struct _ojVal *head; struct _ojVal *tail; } *ojList;

List representation. It is also used for the object raw mode.

struct _ojVal*	head	Head of the list
struct _ojVal*	tail	Tail or last member in the list

ojNum

typedef struct _ojNum { long double dub; int64_t fixnum; uint32_t len; int16_t div; int16_t exp; uint8_t shift; bool neg; bool exp_neg; bool calc; union { char raw[88]; ojS4k s4k; struct { size_t cap; char *ptr; }; }; } *ojNum;

All numbers are stores in this struct. The ojVal.type determines which members are set. Several of the members are only used during parsing and can be ignored.

long double	dub	Decimal value
int64_t	fixnum	Integer values or all digits when parsing
uint32_t	len	Length of the string representation
int16_t	div	Divisor when parsing
int16_t	exp	Exponent when parsing
uint8_t	shift	Shift of fixnum to get the decimal value
bool	neg	If true the number is negative
bool	exp_neg	If true the exponent is negative
bool	calc	Indicator that the parts have been used to calculate the fixnum or double value
char	raw[88]	String version of the number
ojS4k	s4k	String version of the number if too long for the raw field
size_t	cap	Capacity of string representation if too long for the s4k field
char*	ptr	String representation if too long for the s4k field

ojParseCallback

typedef ojCallbackOp (*ojParseCallback)(ojVal val, void *ctx);

The type for callback functions when using the callback parsers.

ojPopFunc

typedef void (*ojPopFunc)(void *ctx);

The type for the push function with the push-pop parsers.

ojPushFunc

typedef void (*ojPushFunc)(ojVal val, void *ctx);

The type for the pop function with the push-pop parsers.

ojReuser

typedef struct _ojReuser { ojVal head; ojVal tail; ojVal dig; } *ojReuser;

The struct used for collecting and efficiently returning ojVal instances back to the pool. The fields are used internally only.

ojVal	head	Head of the ojVals to be returned
ojVal	tail	Tail of the ojVals to be returned
ojVal	dig	ojVals that need addition free calls.

ojS4k

typedef union _ojS4k { union _ojS4k *next; char str[4096]; } *ojS4k;

Blocks used for strings and bignums that are too large to fit directly into a ojVal. These are used internally.

union _ojS4k*	next	Linked list link
char	str[4096]	Space for the string

ojStr

typedef struct _ojStr { int len; union { char raw[120]; ojS4k s4k; struct { size_t cap; char *ptr; }; }; } *ojStr;

Used to store strings. There are three locations for the string data depending on the string length. Shorter strings are stored in the raw member. The next level up is the s4k member. If the string is larger than a ojS4k then the ptr member is used to store the string.

int	len	Length of raw or ptr excluding terminating null
char	raw[120]	Storage for shorter string
ojS4k	s4k	Storage for larger strings
size_t	cap	Capacity of extra large strings
char*	ptr	Storage for extra large strings

ojVal

typedef struct _ojVal { struct _ojVal *next; struct _ojVal *free; struct _ojStr key; uint32_t kh; uint8_t type; uint8_t mod; union { struct _ojStr str; struct _ojList list; struct _ojVal *hash[16]; struct _ojNum num; }; } *ojVal;

Each element of a JSON document is represented by the ojVal struct.

Hash of the key

struct _ojVal*	next	Linked list next pointer
struct _ojVal*	free	Free list next pointer
struct _ojStr	key	Key of the member if a member of an object
uint32_t	kh
uint8_t	type	Type of the value (ojType)
uint8_t	mod	Modifier of the type (objects only)
struct _ojStr	str	String value
struct _ojList	list	List and raw object value
struct _ojVal*	hash[16]	Object value when a hash
struct _ojNum	num	Numeric value

oj_thread_safe

extern bool oj_thread_safe;

Thread safe flag. It should be set when using the library from multiple threads.

oj_append()

extern ojStatus oj_append(ojErr err, ojVal val, ojVal member);

Appends a member to an array. It can also be used to set an object entry if the member key is set.

ojErr	err	Used for error reporting.
ojVal	val	Array or object to append to.
ojVal	member	Member to append.

oj_array_create()

extern ojVal oj_array_create(ojErr err);

Create a new array ojVal.

ojErr

err

Used for error reporting.

oj_array_first()

extern ojVal oj_array_first(ojVal val);

Return the first member of a list. If not a list or the list is empty NULL is returned.

ojVal

val

The array to get the first member from.

oj_array_last()

extern ojVal oj_array_last(ojVal val);

Return the last member of a list. If not a list or the list is empty NULL is returned.

ojVal

val

The list to get the last member from.

oj_array_nth()

extern ojVal oj_array_nth(ojVal val, int n);

Return the nth member of a list. If not a list or there is no nth element NULL is returned.

ojVal	val	The list to get the nth member from.
int	n	The member offset (n) in the list to return.

oj_bignum_create()

extern ojVal oj_bignum_create(ojErr err, const char *s, size_t len);

Create a new bignum ojVal.

ojErr	err	Used for error reporting.
const char*	s	String representation of a big number.
size_t	len	Length of the string.

oj_bignum_get()

extern const char* oj_bignum_get(ojVal val);

Return the bignum string.

ojVal

val

Value to get the string from.

oj_bignum_set()

extern ojStatus oj_bignum_set(ojErr err, ojVal val, const char *s, size_t len);

Set the value of a ojVal to a bignum.

ojErr	err	Used for error reporting.
ojVal	val	Value to set.
const char*	s	Bignum string.
size_t	len	String length.

oj_bool_create()

extern ojVal oj_bool_create(ojErr err, bool b);

Create a new boolean ojVal.

ojErr	err	Used for error reporting.
bool	b	Boolean value for the new ojVal.

oj_bool_set()

extern void oj_bool_set(ojVal val, bool b);

Set the value of a ojVal to a boolean.

ojVal	val	ojVal to set the value of.
bool	b	Boolean value for the ojVal.

oj_buf()

extern size_t oj_buf(ojBuf buf, ojVal val, int indent, int depth);

Marshal a ojVal into a ojBuf indented with the specified indentation and stating depth.

ojBuf	buf	Buffer to fill.
ojVal	val	Value to marshal.
int	indent	Identation of generated string.
int	depth	Initial depth of the indentation.

oj_build_array()

extern ojStatus oj_build_array(ojBuilder b, const char *key);

Push an array onto the build stack of a ojBuilder and return the state of the builder error code.

ojBuilder	b	Builder to push the new value to.
const char*	key	Key for the value being pushed if parent is an object.

oj_build_bignum()

extern ojStatus oj_build_bignum(ojBuilder b, const char *key, const char *big, size_t len);

Push a bignum string onto the build stack or append to the most recent object or array on the stack a ojBuilder and return the state of the builder error code.

ojBuilder	b	Builder to push the new value to.
const char*	key	Key for the value being pushed if parent is an object.
const char*	big	The bignum string to push.
size_t	len	Length of the bignum string.

oj_build_bool()

extern ojStatus oj_build_bool(ojBuilder b, const char *key, bool boo);

Push a boolean onto the build stack or append to the most recent object or array on the stack a ojBuilder and return the state of the builder error code.

ojBuilder	b	Builder to push the new value to.
const char*	key	Key for the value being pushed if parent is an object.
bool	boo	Value to push to the stack.

oj_build_double()

extern ojStatus oj_build_double(ojBuilder b, const char *key, long double d);

Push a long double onto the build stack or append to the most recent object or array on the stack a ojBuilder and return the state of the builder error code.

ojBuilder	b	Builder to push the new value to.
const char*	key	Key for the value being pushed if parent is an object.
long double	d	Value to push to the stack.

oj_build_int()

extern ojStatus oj_build_int(ojBuilder b, const char *key, int64_t i);

Push an int64_t onto the build stack or append to the most recent object or array on the stack a ojBuilder and return the state of the builder error code.

ojBuilder	b	Builder to push the new value to.
const char*	key	Key for the value being pushed if parent is an object.
int64_t	i	Value to push on the stack.

oj_build_null()

extern ojStatus oj_build_null(ojBuilder b, const char *key);

Push a null onto the build stack or append to the most recent object or array on the stack a ojBuilder and return the state of the builder error code.

ojBuilder	b	Builder to push the new value to.
const char*	key	Key for the value being pushed if parent is an object.

oj_build_object()

extern ojStatus oj_build_object(ojBuilder b, const char *key);

Push an object onto the build stack of a ojBuilder and return the state of the builder error code.

ojBuilder	b	Builder to push the new value to.
const char*	key	Key for the value being pushed if parent is an object.

oj_build_pop()

extern ojStatus oj_build_pop(ojBuilder b);

Pop a value from the builder stack. This has the effect of closing the most recent object or array.

ojBuilder

b

Builder to pop a value from.

oj_build_popall()

extern void oj_build_popall(ojBuilder b);

Continue popping a value from the builder stack until the stack is empty. This has the effect of closing all remaining objects and arrays.

ojBuilder

b

Builder to pop values from.

oj_build_string()

extern ojStatus oj_build_string(ojBuilder b, const char *key, const char *s, size_t len);

Push a string onto the build stack or append to the most recent object or array on the stack a ojBuilder and return the state of the builder error code.

ojBuilder	b	Builder to push the new value to.
const char*	key	Key for the value being pushed if parent is an object.
const char*	s	String to push onto the stack.
size_t	len	Length of the string to push.

oj_caller_shutdown()

extern void oj_caller_shutdown(ojCaller caller);

Shutdown a ojCaller which stops the callback thread. Any remaining callbacks are discarded.

ojCaller

caller

The caller to shutdown.

oj_caller_start()

extern ojStatus oj_caller_start(ojErr err, ojCaller caller, ojParseCallback cb, void *ctx);

Starts a ojCaller so that is is ready when call parser is invoked with it as an argument.

ojErr	err	Used for error reporting.
ojCaller	caller	Caller to start.
ojParseCallback	cb	Callback function for calls.
void*	ctx	Context for the callback function.

oj_caller_wait()

extern void oj_caller_wait(ojCaller caller);

Wait for a ojCaller to finish processing pending callbacks.

ojCaller

caller

Caller to wait on.

oj_cleanup()

extern void oj_cleanup(void);

Cleans up memory used by the library. It should be called before exiting an application if checking for memory leaks.

oj_destroy()

extern void oj_destroy(ojVal val);

Returns a ojVal to the memory pool. A reuse pool is used to improve performance.

ojVal

val

The ojVal to return to the pool.

oj_double_create()

extern ojVal oj_double_create(ojErr err, long double dub);

Create a new double numeric ojVal.

ojErr	err	Used for error reporting.
long double	dub	The value to set in the new ojVal.

oj_double_get()

extern long double oj_double_get(ojVal val, bool prec);

Return the long double value of a ojVal. If the ojVal is not a double then 0.0 is returned.

oj_double_set()

extern void oj_double_set(ojVal val, long double dub);

Set the value of a ojVal to a long double.

ojVal	val	The ojVal set the provided value on.
long double	dub	The value to set the ojVal to.

oj_each()

extern ojVal oj_each(ojVal val, bool (*cb)(ojVal v, void* ctx), void *ctx);

Iterate over all members of an array or object.

ojVal	val	Array or object ojVal to iterate over.
bool ()(ojVal, void)	cb	Callback to be invoked for each member of the array or object.
void*	ctx	Context to provide to each callback invocation.

oj_err_init()

extern void oj_err_init(ojErr err);

Initialize a ojErr struct.

ojErr

err

ojVal to initialize.

oj_fill()

extern size_t oj_fill(ojErr err, ojVal val, int indent, char *buf, int max);

Fill a buffer with a ojVal marshalled into JSON.

ojErr	err	Used for error reporting.
ojVal	val	ojVal to marshal into JSON.
int	indent	Indentation to use for formatting the JSON.
char*	buf	Buffer to fill with JSON.
int	max	Maximum size of encoded JSON.

oj_fwrite()

extern size_t oj_fwrite(ojErr err, ojVal val, int indent, const char *filepath);

Write a ojVal to a file encoded as JSON.

ojErr	err	Used for error reporting.
ojVal	val	ojVal to encode.
int	indent	Indentation to use for formatting the JSON.
const char*	filepath	Filename to write to.

oj_int_create()

extern ojVal oj_int_create(ojErr err, int64_t fixnum);

Create a new integer numeric ojVal.

ojErr	err	Used for error reporting.
int64_t	fixnum	TBD.

oj_int_get()

extern int64_t oj_int_get(ojVal val);

Return the int64_t value of a ojVal. If the ojVal is not a int then 0 is returned.

ojVal

val

ojVal to get the value from.

oj_int_set()

extern void oj_int_set(ojVal val, int64_t fixnum);

Set the value of a ojVal to a int64_t.

ojVal	val	ojVal to set the value of.
int64_t	fixnum	The value to set the ojVal to.

oj_key()

extern const char* oj_key(ojVal val);

Return the key of a ojVal.

ojVal

val

The ojVal to get the key from.

oj_key_set()

extern ojStatus oj_key_set(ojErr err, ojVal val, const char *key, size_t len);

Set the key of a ojVal.

ojErr	err	Used for error reporting.
ojVal	val	ojVal to set the key of.
const char*	key	Key to set the ojVal to.
size_t	len	Length of the key.

oj_null_create()

extern ojVal oj_null_create(ojErr err);

Create a new null ojVal.

ojErr

err

Used for error reporting.

oj_null_set()

extern void oj_null_set(ojVal val);

Set the value of a ojVal to null.

ojVal

val

ojVal to set to a null value.

oj_object_create()

extern ojVal oj_object_create(ojErr err);

Create a new object ojVal.

ojErr

err

Used for error reporting.

oj_object_find()

extern ojVal oj_object_find(ojVal val, const char *key, int len);

Find the member of the object that has a matching key if the ojVal is an object. The mode is not changed.

ojVal	val	Object to get a value from.
const char*	key	Key to match.
int	len	Length of the key.

oj_object_get()

extern ojVal oj_object_get(ojVal val, const char *key, int len);

Get the member of the object that has a matching key if the ojVal is an object. The mode is set to OJ_OBJ_HASH.

ojVal	val	Object to get a value from.
const char*	key	Key to match.
int	len	Length of the key.

oj_object_set()

extern ojStatus oj_object_set(ojErr err, ojVal val, const char *key, ojVal member);

Set a member of the object associated with the provided key.

ojErr	err	Used for error reporting.
ojVal	val	Object to set the member of.
const char*	key	Key for the member.
ojVal	member	Member to be set associated with the key.

oj_parse_fd()

extern ojVal oj_parse_fd(ojErr err, int fd, ojReuser reuser);

Parse JSON read from a file descriptor. Only one JSON document should be in the stream. The caller is responsible for freeing the returned value with oj_destroy() or by using the reuser if provided.

ojErr	err	Used for error reporting.
int	fd	Stream parse.
ojReuser	reuser	Optional reused for freeing the returned value.

oj_parse_fd_call()

extern ojStatus oj_parse_fd_call(ojErr err, int fd, ojCaller caller);

Parse multiple JSON documents from a file descriptor using callback through the provided caller.

ojErr	err	Used for error reporting.
int	fd	Stream to read from.
ojCaller	caller	Caller for invoking callbacks.

oj_parse_fd_cb()

extern ojStatus oj_parse_fd_cb(ojErr err, int fd, ojParseCallback cb, void *ctx);

Parse multiple JSON documents from a file descriptor using a callback function.

ojErr	err	Used for error reporting.
int	fd	Stream to read from.
ojParseCallback	cb	Callback function.
void*	ctx	Context for the callback.

oj_parse_file()

extern ojVal oj_parse_file(ojErr err, const char *filename, ojReuser reuser);

Parse JSON read from a file. Only one JSON document should be in the file. The caller is responsible for freeing the returned value with oj_destroy() or by using the reuser if provided.

ojErr	err	Used for error reporting.
const char*	filename	File to parse.
ojReuser	reuser	Optional reused for freeing the returned value.

oj_parse_file_call()

extern ojStatus oj_parse_file_call(ojErr err, const char *filename, ojCaller caller);

Parse multiple JSON documents from a file using callback through the provided caller.

ojErr	err	Used for error reporting.
int	filename	File to read from.
ojCaller	caller	Caller for invoking callbacks.

oj_parse_file_cb()

extern ojStatus oj_parse_file_cb(ojErr err, const char *filename, ojParseCallback cb, void *ctx);

Parse multiple JSON documents from a file using callback through the provided callback function.

ojErr	err	Used for error reporting.
const char*	filename	File to parse.
ojParseCallback	cb	Callback function.
void*	ctx	Context for the callback.

oj_parse_str()

extern ojVal oj_parse_str(ojErr err, const char *json, ojReuser reuser);

pp Parse JSON string. Only one JSON document should be in the string. The caller is responsible for freeing the returned value with oj_destroy() or by using the reuser if provided.

ojErr	err	Used for error reporting.
const char*	json	String to parse.
ojReuser	reuser	Optional reused for freeing the returned value.

oj_parse_str_call()

extern ojStatus oj_parse_str_call(ojErr err, const char *json, ojCaller caller);

Parse multiple JSON documents from a string using callback through the provided caller.

ojErr	err	Used for error reporting.
const char*	json	String to parse.
ojCaller	caller	Caller for invoking callbacks.

oj_parse_str_cb()

extern ojStatus oj_parse_str_cb(ojErr err, const char *json, ojParseCallback cb, void *ctx);

Parse multiple JSON documents from a string using callback through the provided callback function.

ojErr	err	Used for error reporting.
const char*	json	String to parse.
ojParseCallback	cb	Callback function.
void*	ctx	Context for the callback.

oj_parse_strp()

extern ojVal oj_parse_strp(ojErr err, const char **json, ojReuser reuser);

Parse a JSON string pointed to by the json pointer. Only one document is parsed and then the json argument is set to point to just after the parsed string. The caller is responsible for freeing the returned value with oj_destroy() or by using the reuser if provided.

ojErr	err	Used for error reporting.
const char**	json	Pointer to a string to parse.
ojReuser	reuser	Optional reused for freeing the returned value.

oj_pp_parse_fd()

extern ojStatus oj_pp_parse_fd(ojErr err, int fd, ojPushFunc push, ojPopFunc pop, void *ctx);

Parse multiple JSON documents from a file descriptor using callbacks for pushing values when they are first encountered and popping when array or objects are closed.

ojErr	err	Used for error reporting.
int	fd	Stream to parse.
ojPushFunc	push	Push callback.
ojPopFunc	pop	Pop callback.
void*	ctx	Context for both callbacks.

oj_pp_parse_file()

extern ojStatus oj_pp_parse_file(ojErr err, const char *filepath, ojPushFunc push, ojPopFunc pop, void *ctx);

Parse multiple JSON documents from a file using callbacks for pushing values when they are first encountered and popping when array or objects are closed.

ojErr	err	Used for error reporting.
const char*	filepath	File to parse.
ojPushFunc	push	Push callback.
ojPopFunc	pop	Pop callback.
void*	ctx	Context for both callbacks.

oj_pp_parse_str()

extern ojStatus oj_pp_parse_str(ojErr err, const char *json, ojPushFunc push, ojPopFunc pop, void *ctx);

Parse multiple JSON documents from a string using callbacks for pushing values when they are first encountered and popping when array or objects are closed.

ojErr	err	Used for error reporting.
const char*	json	String to parse.
ojPushFunc	push	Push callback.
ojPopFunc	pop	Pop callback.
void*	ctx	Context for both callbacks.

oj_reuse()

extern void oj_reuse(ojReuser reuser);

Return ojVal instance collected during parsing.

ojReuser

reuser

Reuser that collected ojVal instances.

oj_status_str()

extern const char* oj_status_str(ojStatus code);

Return a string representation of the ojStatus provided.

ojStatus

code

ojStatus to return a string from.

oj_str_create()

extern ojVal oj_str_create(ojErr err, const char *s, size_t len);

Create a new string ojVal.

ojErr	err	Used for error reporting.
const char*	s	String value for the new ojVal.
size_t	len	Length of string.

oj_str_get()

extern const char* oj_str_get(ojVal val);

Return the string value of a ojVal. If the ojVal is not a string then NULL is returned.

ojVal

val

ojVal to get the value from.

oj_str_set()

extern ojStatus oj_str_set(ojErr err, ojVal val, const char *s, size_t len);

Set the value of a ojVal to a string.

ojErr	err	Used for error reporting.
ojVal	val	ojVal to set the value on.
int64_t	s	The value to set the ojVal to.
size_t	len	Length of string.

oj_to_str()

extern char* oj_to_str(ojVal val, int indent);

Return a JSON string represented by the ojVal provided. The returned JSON string should be freed when no longer needed.

ojVal	val	ojVal to encode.
int	indent	Indentation for the JSON string.

oj_type_str()

extern const char* oj_type_str(ojType type);

Return a string representation of the provided type.

ojType

type

Type to return a string represenation of.

oj_val_create()

extern ojVal oj_val_create();

Create a new blank ojVal.

oj_validate_str()

extern ojStatus oj_validate_str(ojErr err, const char *json);

Validate a JSON string.

ojErr	err	Used for error reporting.
const char*	json	JSON string to validate.

oj_version()

extern const char* oj_version(void);

Return the OjC version.

oj_write()

extern size_t oj_write(ojErr err, ojVal val, int indent, int fd);

Write a ojVal to a stream in JSON format.

ojErr	err	Used for error reporting.
ojVal	val	ojVal to encode.
int	indent	Indentation for the JSON output.
int	fd	Stream to write to.