coreJSON v3.1.0
Parser library for the ECMA-404 JSON standard
core_json.h File Reference

Include this header file to use coreJSON in your application. More...

#include <stdbool.h>
#include <stddef.h>

Go to the source code of this file.

Data Structures

struct  JSONPair_t
 Structure to represent a key-value pair. More...
 

Macros

#define JSON_Search(buf, max, query, queryLength, outValue, outValueLength)    JSON_SearchT( buf, max, query, queryLength, outValue, outValueLength, NULL )
 Find a key or array index in a JSON document and output the pointer outValue to its value. More...
 
#define MAX_INDEX_VALUE   ( 0x7FFFFFF7 ) /* 2^31 - 9 */
 The largest value usable as an array index in a query for JSON_Search(), ~2 billion.
 

Enumerations

enum  JSONStatus_t {
  JSONPartial = 0 , JSONSuccess , JSONIllegalDocument , JSONMaxDepthExceeded ,
  JSONNotFound , JSONNullParameter , JSONBadParameter
}
 Return codes from coreJSON library functions. More...
 
enum  JSONTypes_t {
  JSONInvalid = 0 , JSONString , JSONNumber , JSONTrue ,
  JSONFalse , JSONNull , JSONObject , JSONArray
}
 Value types from the JSON standard. More...
 

Functions

JSONStatus_t JSON_Validate (const char *buf, size_t max)
 Parse a buffer to determine if it contains a valid JSON document. More...
 
JSONStatus_t JSON_SearchT (char *buf, size_t max, const char *query, size_t queryLength, char **outValue, size_t *outValueLength, JSONTypes_t *outType)
 Same as JSON_Search(), but also outputs a type for the value found. More...
 
JSONStatus_t JSON_SearchConst (const char *buf, size_t max, const char *query, size_t queryLength, const char **outValue, size_t *outValueLength, JSONTypes_t *outType)
 Same as JSON_SearchT(), but with const qualified buf and outValue arguments. More...
 
JSONStatus_t JSON_Iterate (const char *buf, size_t max, size_t *start, size_t *next, JSONPair_t *outPair)
 Output the next key-value pair or value from a collection. More...
 

Detailed Description

Include this header file to use coreJSON in your application.

Macro Definition Documentation

◆ JSON_Search

#define JSON_Search (   buf,
  max,
  query,
  queryLength,
  outValue,
  outValueLength 
)     JSON_SearchT( buf, max, query, queryLength, outValue, outValueLength, NULL )

Find a key or array index in a JSON document and output the pointer outValue to its value.

Any value may also be an object or an array to a maximum depth. A search may descend through nested objects or arrays when the query contains matching key strings or array indexes joined by a separator.

For example, if the provided buffer contains {"foo":"abc","bar":{"foo":"xyz"}}, then a search for 'foo' would output abc, 'bar' would output {"foo":"xyz"}, and a search for 'bar.foo' would output xyz.

If the provided buffer contains [123,456,{"foo":"abc","bar":[88,99]}], then a search for '[1]' would output 456, '[2].foo' would output abc, and '[2].bar[0]' would output 88.

On success, the pointer outValue points to a location in buf. No null termination is done for the value. For valid JSON it is safe to place a null character at the end of the value, so long as the character replaced is put back before running another search.

Parameters
[in]bufThe buffer to search.
[in]maxsize of the buffer.
[in]queryThe object keys and array indexes to search for.
[in]queryLengthLength of the key.
[out]outValueA pointer to receive the address of the value found.
[out]outValueLengthA pointer to receive the length of the value found.
Note
The maximum nesting depth may be specified by defining the macro JSON_MAX_DEPTH. The default is 32 of sizeof(char).
JSON_Search() performs validation, but stops upon finding a matching key and its value. To validate the entire JSON document, use JSON_Validate().
Returns
JSONSuccess if the query is matched and the value output; JSONNullParameter if any pointer parameters are NULL; JSONBadParameter if the query is empty, or the portion after a separator is empty, or max is 0, or an index is too large to convert to a signed 32-bit integer; JSONNotFound if the query has no match.

Example

// Variables used in this example.
JSONStatus_t result;
char buffer[] = "{\"foo\":\"abc\",\"bar\":{\"foo\":\"xyz\"}}";
size_t bufferLength = sizeof( buffer ) - 1;
char query[] = "bar.foo";
size_t queryLength = sizeof( query ) - 1;
char * value;
size_t valueLength;
// Calling JSON_Validate() is not necessary if the document is guaranteed to be valid.
result = JSON_Validate( buffer, bufferLength );
if( result == JSONSuccess )
{
result = JSON_Search( buffer, bufferLength, query, queryLength,
&value, &valueLength );
}
if( result == JSONSuccess )
{
// The pointer "value" will point to a location in the "buffer".
char save = value[ valueLength ];
// After saving the character, set it to a null byte for printing.
value[ valueLength ] = '\0';
// "Found: bar.foo -> xyz" will be printed.
printf( "Found: %s -> %s\n", query, value );
// Restore the original character.
value[ valueLength ] = save;
}
JSONStatus_t JSON_Validate(const char *buf, size_t max)
Parse a buffer to determine if it contains a valid JSON document.
Definition: core_json.c:1123
#define JSON_Search(buf, max, query, queryLength, outValue, outValueLength)
Find a key or array index in a JSON document and output the pointer outValue to its value.
Definition: core_json.h:170
JSONStatus_t
Return codes from coreJSON library functions.
Definition: core_json.h:45
@ JSONSuccess
JSON document is valid and complete.
Definition: core_json.h:47
Note
The maximum index value is ~2 billion ( 2^31 - 9 ).

Function Documentation

◆ JSON_Validate()

JSONStatus_t JSON_Validate ( const char *  buf,
size_t  max 
)

Parse a buffer to determine if it contains a valid JSON document.

Parameters
[in]bufThe buffer to parse.
[in]maxThe size of the buffer.
Note
The maximum nesting depth may be specified by defining the macro JSON_MAX_DEPTH. The default is 32 of sizeof(char).
By default, a valid JSON document may contain a single element (e.g., string, boolean, number). To require that a valid document contain an object or array, define JSON_VALIDATE_COLLECTIONS_ONLY.
Returns
JSONSuccess if the buffer contents are valid JSON; JSONNullParameter if buf is NULL; JSONBadParameter if max is 0; JSONIllegalDocument if the buffer contents are NOT valid JSON; JSONMaxDepthExceeded if object and array nesting exceeds a threshold; JSONPartial if the buffer contents are potentially valid but incomplete.

Example

// Variables used in this example.
JSONStatus_t result;
char buffer[] = "{\"foo\":\"abc\",\"bar\":{\"foo\":\"xyz\"}}";
size_t bufferLength = sizeof( buffer ) - 1;
result = JSON_Validate( buffer, bufferLength );
// JSON document is valid.
assert( result == JSONSuccess );

See core_json.h for docs.

Verify that the entire buffer contains exactly one scalar or collection within optional whitespace.

◆ JSON_SearchT()

JSONStatus_t JSON_SearchT ( char *  buf,
size_t  max,
const char *  query,
size_t  queryLength,
char **  outValue,
size_t *  outValueLength,
JSONTypes_t outType 
)

Same as JSON_Search(), but also outputs a type for the value found.

See JSON_Search for documentation of common behavior.

Parameters
[in]bufThe buffer to search.
[in]maxsize of the buffer.
[in]queryThe object keys and array indexes to search for.
[in]queryLengthLength of the key.
[out]outValueA pointer to receive the address of the value found.
[out]outValueLengthA pointer to receive the length of the value found.
[out]outTypeAn enum indicating the JSON-specific type of the value.

See core_json.h for docs.

◆ JSON_SearchConst()

JSONStatus_t JSON_SearchConst ( const char *  buf,
size_t  max,
const char *  query,
size_t  queryLength,
const char **  outValue,
size_t *  outValueLength,
JSONTypes_t outType 
)

Same as JSON_SearchT(), but with const qualified buf and outValue arguments.

See JSON_Search for documentation of common behavior.

Parameters
[in]bufThe buffer to search.
[in]maxsize of the buffer.
[in]queryThe object keys and array indexes to search for.
[in]queryLengthLength of the key.
[out]outValueA pointer to receive the address of the value found.
[out]outValueLengthA pointer to receive the length of the value found.
[out]outTypeAn enum indicating the JSON-specific type of the value.

See core_json.h for docs.

◆ JSON_Iterate()

JSONStatus_t JSON_Iterate ( const char *  buf,
size_t  max,
size_t *  start,
size_t *  next,
JSONPair_t outPair 
)

Output the next key-value pair or value from a collection.

This function may be used in a loop to output each key-value pair from an object, or each value from an array. For the first invocation, the integers pointed to by start and next should be initialized to 0. These will be updated by the function. If another key-value pair or value is present, the output structure is populated and JSONSuccess is returned; otherwise the structure is unchanged and JSONNotFound is returned.

Parameters
[in]bufThe buffer to search.
[in]maxsize of the buffer.
[in,out]startThe index at which the collection begins.
[in,out]nextThe index at which to seek the next value.
[out]outPairA pointer to receive the next key-value pair.
Note
This function expects a valid JSON document; run JSON_Validate() first.
For an object, the outPair structure will reference a key and its value. For an array, only the value will be referenced (i.e., outPair.key will be NULL).
Returns
JSONSuccess if a value is output; JSONIllegalDocument if the buffer does not contain a collection; JSONNotFound if there are no further values in the collection.

Example

// Variables used in this example.
static char * json_types[] =
{
"invalid",
"string",
"number",
"true",
"false",
"null",
"object",
"array"
};
void show( const char * json,
size_t length )
{
size_t start = 0, next = 0;
JSONPair_t pair = { 0 };
JSONStatus_t result;
result = JSON_Validate( json, length );
if( result == JSONSuccess )
{
result = JSON_Iterate( json, length, &start, &next, &pair );
}
while( result == JSONSuccess )
{
if( pair.key != NULL )
{
printf( "key: %.*s\t", ( int ) pair.keyLength, pair.key );
}
printf( "value: (%s) %.*s\n", json_types[ pair.jsonType ],
( int ) pair.valueLength, pair.value );
result = JSON_Iterate( json, length, &start, &next, &pair );
}
}
JSONStatus_t JSON_Iterate(const char *buf, size_t max, size_t *start, size_t *next, JSONPair_t *outPair)
Output the next key-value pair or value from a collection.
Definition: core_json.c:1762
Structure to represent a key-value pair.
Definition: core_json.h:247
const char * value
Pointer to the code point sequence for value.
Definition: core_json.h:250
size_t keyLength
Length of the code point sequence for key.
Definition: core_json.h:249
JSONTypes_t jsonType
JSON-specific type of the value.
Definition: core_json.h:252
size_t valueLength
Length of the code point sequence for value.
Definition: core_json.h:251
const char * key
Pointer to the code point sequence for key.
Definition: core_json.h:248

See core_json.h for docs.