Blitz3D+ Command Reference

JsonArrayAppend json,value

Parameters

json - JSON array handle to modify

value - JSON handle whose value is copied onto the end

Description

Adds a copy of a JSON value to the end of an array.

The everyday way an array grows: loot gets picked up and appended to the inventory, a lap time joins the results list, a completed quest lands at the end of the log. Each append increases JsonCount by one and keeps existing elements exactly where they were.

JsonArrayAppend copies the value, so the caller still owns the value handle afterwards and must free it separately. The usual pattern:

v=CreateJsonString("potion")
JsonArrayAppend inventory,v
FreeJson v

Because the copy is independent, you can append the same handle several times to get several separate elements. To place a value somewhere other than the end, use JsonArrayInsert. Calling JsonArrayAppend on a non-array or with a stale value handle is a programming error; if the copy cannot be allocated, the array is left unchanged.

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

Requires Extended mode.

See also: JsonArrayInsert, JsonArraySet, JsonArrayGet, CreateJsonArray, FreeJson.

Example

; JsonArrayAppend Example
; -----------------------
; Requires Extended mode.

; The hero's inventory grows as loot is picked up
inventory=CreateJsonArray()
Print "Empty inventory: "+JsonStringify(inventory,0)

; JsonArrayAppend copies the value onto the end of the array,
; so the temporary handle is freed straight afterwards
v=CreateJsonString("sword")
JsonArrayAppend inventory,v
FreeJson v
Print "Picked up a sword:  "+JsonStringify(inventory,0)

v=CreateJsonString("shield")
JsonArrayAppend inventory,v
FreeJson v
Print "Picked up a shield: "+JsonStringify(inventory,0)

v=CreateJsonString("potion")
JsonArrayAppend inventory,v
FreeJson v
Print "Picked up a potion: "+JsonStringify(inventory,0)

Print ""
Print "Final item count: "+JsonCount(inventory)

FreeJson inventory

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

End

Index