new-json
Purpose: Parse JSON text.
new-json [ define ] <json> from <text> \
[ length <length> ] \
[ status [ define ] <status> ] \
[ error-text [ define ] <error text> ] \
[ error-position [ define ] <error position> ] \
[ max-hash-size <max-hash-size> ] \
[ noencode ]
new-json will parse <text> into <json> variable (a pointer to type "vely_json") which can be created with optional "define".
The length of <text> may be specified with "length" clause in <length> variable, or if not, it will be calculated as the string length of <text>.
The "status" clause specifies the return <status>, which is VV_OKAY if successful or VV_ERR_JSON if there is an error. The number variable <error position> in "error-position" clause is the byte position in <text> where error was found, in which case <error text> in "error-text" clause is the error message. Both can be created with optional "define".
See
read-json on obtaining values from JSON document.
No copying
String <text> is modified during parsing for performance reasons. It is parceled out and <json> contains pointers to it that hold the actual primitive values (string, numbers, boolean, null). This way no data is ever copied for faster parsing. If you don't wish <text> to be modified, make a copy of it before parsing it (see
copy-string). In many cases though, this is not necessary, allowing for better performance.
Hash table
Hash table is used to provide fast access to any value in JSON text, with the number of lookups being close to 1, which means near-direct memory access. By default, the maximum size of a hash table is limited to 10000. If your JSON document has considerably more values than that, use "max-hash-size" clause to specify the maximum hash table size. Hash table mechanism is the same as used internaly in
new-hash.
Encoding
"noencode" clause will not encode strings, i.e. convert from JSON Unicode strings to UTF8 (see
read-json), nor will it perform any validity checks on strings. This may be useful as a performance boost, however it is not recommended in general.
Limitations
The maximum depth of nested structures in JSON document (i.e. objects and arrays) is 32, and the maximum length of normalized leaf node name is 1024 (see
read-json for more on normalized names). There is no limit on document size.
Duplicate normalized names are valid, however, only one of them is reported, and the very last value encountered is actually stored (the others from duplicate names are discarded).
Creating JSON
To create a JSON document, you can use
write-string to programmatically construct one - use
utf8-json to create JSON-compatible Unicode string values.
Allocated internals
<json> is
allocated memory along with additional internal memory, which can be released if
delete-json is used with <json> from a previously executed new-json.
Examples
Parse text "json_text1" and store the result in "json_var" variable, get status, error text and the location of error:
...
new-json json_var from json_text1 status define st error-text errt error-position errp
read-json json_var key "glossary"."title" value d
See also
JSON (
delete-json new-json read-json )
SEE ALL (
documentation)