|
json - JSON array handle to modify index - position to insert before, 0 to JsonCount(json); passing the count appends value - JSON handle whose value is copied into the array |
|
Inserts a copy of a JSON value before an array index. For when position matters: an urgent quest jumps to the front of the log with index 0, a new high score slots into its ranked place, a waypoint is spliced into the middle of a route. Everything at the index and after shifts one place right, and JsonCount grows by one. The valid index range is 0 through the current count - inserting at the count is legal and appends, which makes loops that splice "at or past the end" easy to write. Anything outside that range is a programming error that stops the program. JsonArrayInsert copies the value, so the caller still owns the value handle afterwards and must free it separately - create, insert, free. Calling it 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. See also: JsonArrayAppend, JsonArrayRemove, JsonArraySet, JsonArrayGet, FreeJson. |
; JsonArrayInsert Example
; -----------------------
q$=Chr(34) ; Double-quote character, for building JSON text
; The hero's quest log, in priority order
quests=ParseJson("["+q+"find the key"+q+","+q+"open the vault"+q+"]")
Print "Quest log: "+JsonStringify(quests,0)
; JsonArrayInsert copies the value in BEFORE the given index -
; an urgent quest jumps to the front (index 0)
v=CreateJsonString("escape the dungeon!")
JsonArrayInsert quests,0,v
FreeJson v
Print "Urgent quest inserted at 0:"
Print " "+JsonStringify(quests,0)
; Inserting at the current count appends to the end
v=CreateJsonString("spend the treasure")
JsonArrayInsert quests,JsonCount(quests),v
FreeJson v
Print "Long-term quest inserted at count ("+(JsonCount(quests)-1)+"):"
Print " "+JsonStringify(quests,0)
FreeJson quests
Print ""
Print "Press any key to close the example"
WaitKey
End