Blitz3D+ Command Reference

JsonObjectSet json,key$,value

Parameters

json - JSON object handle to modify

key$ - property name to set, exact and case-sensitive

value - JSON handle whose value is copied into the object

Description

Stores a copy of a JSON value in an object under a key.

The workhorse for building a save-game or settings document: create a value, set it, free your temporary handle. JsonObjectSet copies the value into the object, so the caller still owns the value handle afterwards and must free it separately - the object never takes ownership, and later changes to either side do not affect the other.

A brand-new key is added at the end of the object's insertion order. Replacing an existing key keeps its original position, so a save file's field order stays stable as values change - only removing a key and adding it again moves it to the end. Duplicate keys cannot exist.

The typical pattern:

v=CreateJsonInteger(1250L)
JsonObjectSet save,"gold",v
FreeJson v

Keys are strict UTF-8; invalid UTF-8, a non-object target or a stale value handle are programming errors. The operation is safe under memory pressure: if the copy cannot be allocated, the object is left unchanged.

For the full rules, see the Application Data language reference.

Requires Extended mode.

See also: JsonObjectGet, JsonObjectRemove, JsonObjectHas, CreateJsonObject, FreeJson.

Example

; JsonObjectSet Example
; ---------------------
; Requires Extended mode.

q$=Chr(34)  ; Double-quote character, for building JSON text

; A save-game record in progress
save=ParseJson("{"+q+"player"+q+":"+q+"Aria"+q+","+q+"level"+q+":7}")
Print "Start:        "+JsonStringify(save,0)

; JsonObjectSet copies the value into the object under a key -
; a brand-new key is added at the end
v=CreateJsonInteger(1250L)
JsonObjectSet save,"gold",v
FreeJson v
Print "Added gold:   "+JsonStringify(save,0)

; Replacing an existing key keeps its original position -
; 'level' stays second, it does not jump to the end
v=CreateJsonInteger(8L)
JsonObjectSet save,"level",v
FreeJson v
Print "Level up!     "+JsonStringify(save,0)
Print ""
Print "Note 'level' kept its place when replaced."

FreeJson save

Print ""
Print "Press any key to close the example"
WaitKey

End

Index