FreeJson json
Parameters
| json - JSON handle to release; 0 is a safe no-op |
Description
|
Releases one owned JSON handle. Ownership is the one rule that makes the JSON family tick: every command that hands you a handle hands you the duty to free it. That covers ParseJson, LoadJson, CopyJson, every CreateJson constructor, and the child getters JsonObjectGet and JsonArrayGet - the getters return deep copies, so freeing a child never touches its parent, and freeing the parent never invalidates a child you already fetched. FreeJson 0 is a safe no-op. That is deliberate: failed parses and missing-key lookups return 0, so cleanup code can free the result unconditionally without special-casing failure. Freeing the same nonzero handle twice, or using a handle after it was freed, is a programming error that stops the program with a RuntimeError - handles are generational, so a stale handle is caught rather than silently reading freed memory. Handles are also private to their runtime context: a handle created on the main thread cannot be used or freed inside a Job worker. Leaks matter here: each context can hold at most 4095 live JSON handles, so a forgotten FreeJson inside a loop eventually stops the program. Free short-lived constructor handles right after storing them in a container. For the full rules, see the Application Data language reference. Requires Extended mode. See also: ParseJson, CopyJson, JsonObjectGet, JsonArrayGet, CreateJsonObject. |
Example
; FreeJson Example ; ---------------- ; Requires Extended mode. q$=Chr(34) ; Double-quote character, for building JSON text ; Every successful parse, constructor, copy or child lookup returns ; an OWNED handle - each one must be released with FreeJson. save=ParseJson("{"+q+"player"+q+":"+q+"Aria"+q+","+q+"gold"+q+":1250}") Print "Parsed save-game, handle="+save ; Child getters return deep copies - a second owned handle gold=JsonObjectGet(save,"gold") Print "Child copy of 'gold', handle="+gold+" value="+JsonInteger(gold) ; Freeing the child does not touch the parent... FreeJson gold Print "" Print "Freed the child copy - parent still intact: "+JsonStringify(save,0) ; ...and freeing the parent releases the whole document FreeJson save Print "Freed the parent document." ; FreeJson 0 is always safe, so failed lookups need no special casing FreeJson 0 Print "FreeJson 0 is a safe no-op." Print "" Print "Press any key to close the example" WaitKey End
Index