@JsonAdd

Diese @Function fügt einem bestehenden JSON-Object oder JSON-Array einen neuen Wert hinzu.

Das Verhalten und die Bedeutung der optionalen Parameter hängen davon ab, ob HJSON auf ein JSON-Object oder ein JSON-Array verweist.

Bei einem JSON-Object wird VALUE unter dem mit TEXT KEY angegebenen Key gespeichert. Existiert bereits ein Eintrag mit demselben Key, wird dessen bisheriger Wert ersetzt.

Bei einem JSON-Array wird VALUE als neues Element am Ende des Arrays angefügt. Da Elemente eines JSON-Arrays keinen Key besitzen, entfällt der Parameter KEY.
Ein optionaler dritter Parameter wird bei Arrays deshalb bereits als TEXT TYPE interpretiert.

Für VALUE werden folgende Datentypen unterstützt: TEXT, FN, TEXTLIST, FNLIST und VSPECBINBUFFER sowie bestehende VSPECHJSON (HJS) Handles.
Engine-Listen werden als vollständiges JSON-Array eingefügt und nicht in die Zielstruktur aufgefächert.

Numerische Werte werden standardmäßig als JSON-Real-Werte erzeugt. Über den optionalen Parameter TYPE können numerische Werte alternativ als JSON-Integer oder JSON-Boolean gespeichert werden.
JSON-Strings müssen gültiges UTF-8 enthalten. Mit der Option "S" können ungültige UTF-8-Sequenzen in Textwerten automatisch bereinigt werden.

Als Return-Wert liefert die @Function bei einem Fehler @ERROR, andernfalls TRUE.

VSPECHJSON HJSON:
Handle des JSON-Objects oder JSON-Arrays, dem ein Wert hinzugefügt werden soll.
HJSON muss ein gültiges VSPECHJSON (HJS) Handle enthalten, das auf ein JSON-Object oder JSON-Array verweist.

VALUE:
Der hinzuzufügende Wert.

Folgende Datentypen werden unterstützt:
TEXT
TEXTLIST
NUMBER
NUMBERLIST
FLOAT
FLOATLIST
VSPECBINBUFFER
VSPECHJSON (HJS)

Die Umsetzung in JSON erfolgt abhängig vom Datentyp:
TEXT JSON String
TEXTLIST JSON Array aus Strings

NUMBER JSON Real, Boolean oder Integer
NUMBERLIST JSON Array aus Real-, Boolean- oder Integer-Werten

FLOAT JSON Real, Boolean oder Integer
FLOATLIST JSON Array aus Real-, Boolean- oder Integer-Werten

VSPECBINBUFFER JSON String
VSPECHJSON JSON Object oder JSON Array

Bei NUMBER, NUMBERLIST, FLOAT und FLOATLIST wird ohne Angabe von TEXT TYPE standardmäßig der JSON-Typ Real verwendet.
Eine Engine-Liste wird immer als ein JSON-Array eingefügt. Wird eine Liste einem bereits bestehenden JSON-Array hinzugefügt, entsteht daher ein verschachteltes Array.

Beispiel:
VALUES:="A":"B":"C";
@JsonAdd(HJSON;VALUES);

führt bei einem JSON-Array zu:
[["A","B","C"]]
und nicht zu:
["A","B","C"]

TEXT KEY:
Key, unter dem VALUE in einem JSON-Object gespeichert wird.
Der Parameter wird nur bei JSON-Objects verwendet.

@JsonAdd(HJSON;"Max Mustermann";"Name");
erzeugt beispielsweise:
{"Name":"Max Mustermann"}

Existiert der angegebene Key bereits, wird dessen Wert ersetzt.
Der Key selbst wird nicht durch die Option "S" bereinigt und muss gültiges UTF-8 enthalten.
Wird bei einem JSON-Object kein KEY angegeben, verwendet die aktuelle Implementierung einen leeren String als Key.
Normalerweise sollte deshalb für JSON-Objects ein KEY angegeben werden.

TEXT TYPE:
Optionaler Typ beziehungsweise Verarbeitungsparameter für VALUE.
"R" Real
"B" Boolean
"I" Integer
"S" Ungültige UTF-8-Sequenzen in Strings bereinigen
Die Angaben sind nicht case-sensitiv.

Es kann jeweils nur eine dieser Optionen angegeben werden; Kombinationen wie "SI" oder "SB" sind nicht zulässig.
"R" – Real
Numerische Werte werden als JSON-Real-Werte gespeichert.
Dies ist das Standardverhalten und muss normalerweise nicht ausdrücklich angegeben werden.
@JsonAdd(HJSON;42;"Value";"R");
erzeugt:
{"Value":42.0}

"B" – Boolean
Numerische Werte werden als JSON-Boolean interpretiert.
Der Wert 0 ergibt false, ein von 0 verschiedener Wert ergibt true.
@JsonAdd(HJSON;1;"Active";"B");
erzeugt:
{"Active":true}

"I" – Integer
Numerische Werte werden als JSON-Integer gespeichert.
@JsonAdd(HJSON;42;"Count";"I");
erzeugt:
{"Count":42}

Bei einem FLOAT-Wert wird dieser bei der Umwandlung in einen Integer auf einen ganzzahligen Wert reduziert.

"S" – UTF-8 Sanitize
JSON-Strings müssen gültiges UTF-8 enthalten. Wird "S" angegeben, versucht @JsonAdd, ungültige UTF-8-Sequenzen im übergebenen String zu bereinigen, bevor der Wert in die JSON-Struktur aufgenommen wird.
Die Option gilt für:
TEXT
TEXTLIST
VSPECBINBUFFER

Ohne "S" führt ein ungültiger UTF-8-String dazu, dass der Wert nicht hinzugefügt werden kann.
Die Option "S" führt keine Zeichensatzkonvertierung durch. Sie ist insbesondere keine LMBCS-zu-UTF-8-Konvertierung, sondern dient lediglich dazu, fehlerhafte UTF-8-Sequenzen in Daten zu bereinigen, die bereits als UTF-8 vorgesehen sind.

Besonderheit bei JSON-Arrays:
Bei einem JSON-Array besitzt ein Element keinen Key. Daher hat der dritte Parameter eine andere Bedeutung als bei einem JSON-Object.

HJSON:=@JsonCreate("Array");
@JsonAdd(HJSON;42);
@JsonAdd(HJSON;10;"I");
@JsonAdd(HJSON;1;"B");

ergibt:
[42.0,10,true]
Ein vierter Parameter ist bei einem JSON-Array nicht zulässig.

Hinweise:
Die gleiche Engine-Variable darf nicht gleichzeitig als Ziel-JSON und als hinzuzufügender Wert beziehungsweise als weiterer Parameter verwendet werden.
In diesem Fall liefert @JsonAdd den Fehler:
"SAME JSON VARIABLE CANNOT BE USED AS SOURCE AND TARGET"

Ein VSPECBINBUFFER wird von @JsonAdd als UTF-8-String behandelt. Sein Inhalt wird nicht als JSON geparst.
Soll eine bereits vorhandene JSON-Textdarstellung als echte JSON-Struktur eingebunden werden, muss diese zuvor beispielsweise mit @JsonLoad in ein VSPECHJSON (HJS) Handle umgewandelt werden.

Beispiel: JSON-Object erzeugen
HJSON:=@JsonCreate;
@JsonAdd(HJSON;"Max Mustermann";"Name");
@JsonAdd(HJSON;42;"Age";"I");
@JsonAdd(HJSON;1;"Active";"B");
@JsonAdd(HJSON;78.5;"Score");
JSONTEXT:=@JsonSerialize(HJSON;"A");
@JsonRelease(HJSON);

Die erzeugte JSON-Struktur entspricht:
{"Name":"Max Mustermann","Age":42,"Active":true,"Score":78.5}

Beispiel: Listen hinzufügen
HJSON:=@JsonCreate;
NAMES:="Anna":"Bernd":"Claudia";
VALUES:=10:20:30;
@JsonAdd(HJSON;NAMES;"Names");
@JsonAdd(HJSON;VALUES;"Values";"I");
JSONTEXT:=@JsonSerialize(HJSON;"A");
@JsonRelease(HJSON);

Die erzeugte JSON-Struktur entspricht:
{"Names":["Anna","Bernd","Claudia"],"Values":[10,20,30]}

Eine Liste wird dabei als zusammengehöriges JSON-Array gespeichert.

Beispiel: Verschachtelte JSON-Strukturen
HPERSON:=@JsonCreate;
HADDRESS:=@JsonCreate;
@JsonAdd(HADDRESS;"Berlin";"City");
@JsonAdd(HADDRESS;"Deutschland";"Country");
@JsonAdd(HPERSON;"Max Mustermann";"Name");
@JsonAdd(HPERSON;HADDRESS;"Address");
JSONTEXT:=@JsonSerialize(HPERSON;"A");
@JsonRelease(HADDRESS);
@JsonRelease(HPERSON);

Die erzeugte JSON-Struktur entspricht:
{
"Name":"Max Mustermann",
"Address":{
"City":"Berlin",
"Country":"Deutschland"
}
}

Ein als VALUE übergebenes VSPECHJSON (HJS) Handle wird direkt als JSON-Unterstruktur eingebunden.
@JsonAdd erzeugt dabei eine eigene Referenz auf die eingefügte JSON-Struktur. Das als VALUE übergebene Handle bleibt deshalb weiterhin gültig und kann unabhängig vom übergeordneten JSON-Handle mit @JsonRelease freigegeben werden.

Beispiel: JSON-Array
HJSON:=@JsonCreate("Array");
@JsonAdd(HJSON;"Text1");
@JsonAdd(HJSON;"Text2");
@JsonAdd(HJSON;100;"I");
@JsonAdd(HJSON;TRUE;"B");
JSONTEXT:=@JsonSerialize(HJSON;"A");
@JsonRelease(HJSON);

Die erzeugte JSON-Struktur entspricht:
["Text1","Text2",100,true]