Vely logo Empower C
install  tutorials  examples
documentation  license  about

12.1.0 released on Sep 19, 2022

new-json



PURPOSE:


Parse JSON text.

SYNTAX:


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 ]


DESCRIPTION:


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.

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)



Copyright (c) 2022 DaSoftver LLC. Vely is a trademark of Dasoftver LLC. The software and information herein are provided "AS IS" and without any warranties or guarantees of any kind. Icons copyright PaweĊ‚ Kuna licensed under MIT. This web page is licensed under CC-BY-SA-4.0.