JsonObjectGet ( json,key$ )
Parameters
|
json - JSON object handle key$ - property name to fetch, exact and case-sensitive |
Description
|
Returns an owned deep copy of an object property, or 0 when the key is absent. This is how you read fields out of a loaded save or settings document. The returned handle is a fully independent copy: it stays valid even if you later change, clear or free the parent object, and freeing it never touches the parent. You own it - release it with FreeJson. A missing key returns 0 quietly, without changing JsonError - so reading optional fields needs no error handling ceremony, and since FreeJson 0 is a safe no-op you can free the result unconditionally. Remember that 0 means "absent", while a present-but-null field returns a real handle whose JsonIsNull is true. Because every get copies the value, fetching a large subtree over and over is wasteful - fetch it once, read what you need, free it. Keys are strict UTF-8 and case-sensitive. Calling JsonObjectGet on a non-object is a programming error. For the full rules, see the Application Data language reference. Requires Extended mode. See also: JsonObjectHas, JsonObjectSet, JsonObjectKey, JsonArrayGet, FreeJson. |
Example
; JsonObjectGet Example ; --------------------- ; Requires Extended mode. q$=Chr(34) ; Double-quote character, for building JSON text ; A loaded save-game record save=ParseJson("{"+q+"player"+q+":"+q+"Aria"+q+","+q+"gold"+q+":1250}") Print "Save-game: "+JsonStringify(save,0) Print "" ; JsonObjectGet returns an OWNED deep copy of the property gold=JsonObjectGet(save,"gold") Print "gold handle = "+gold+", value = "+JsonInteger(gold) ; An absent key returns zero - no error, no diagnostics change mount=JsonObjectGet(save,"mount") Print "mount handle = "+mount+" (0 means the key is absent)" Print "" If mount=0 Then Print "Aria still travels on foot." FreeJson mount ; FreeJson 0 is safe FreeJson gold FreeJson save Print "" Print "Press any key to close the example" WaitKey End
Index