JSON_Search

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

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

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]	buf	The buffer to search.
[in]	max	size of the buffer.
[in]	query	The object keys and array indexes to search for.
[in]	queryLength	Length of the key.
[out]	outValue	A pointer to receive the address of the value found.
[out]	outValueLength	A 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;
}

Note

The maximum index value is ~2 billion ( 2^31 - 9 ).