4.1. add (hinzufügen)

4.1. add (hinzufügen)

Die "add"-Operation führt eine der folgenden Funktionen aus, abhängig davon, worauf die Zielposition verweist:

• Wenn die Zielposition einen Array-Index angibt, wird ein neuer Wert am angegebenen Index in das Array eingefügt.

• Wenn die Zielposition ein Objektmitglied angibt, das noch nicht existiert, wird dem Objekt ein neues Mitglied hinzugefügt.

• Wenn die Zielposition ein Objektmitglied angibt, das existiert, wird der Wert dieses Mitglieds ersetzt.

Das Operationsobjekt MUSS ein "value"-Mitglied enthalten, dessen Inhalt den hinzuzufügenden Wert angibt.

Zum Beispiel:

{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }

Wenn die Operation angewendet wird, MUSS die Zielposition auf eines der folgenden verweisen:

• Die Wurzel des Zieldokuments - wobei der angegebene Wert zum gesamten Inhalt des Zieldokuments wird.

• Ein zu einem vorhandenen Objekt hinzuzufügendes Mitglied - wobei der bereitgestellte Wert an der angegebenen Stelle zu diesem Objekt hinzugefügt wird. Wenn das Mitglied bereits existiert, wird es durch den angegebenen Wert ersetzt.

• Ein zu einem vorhandenen Array hinzuzufügendes Element - wobei der bereitgestellte Wert an der angegebenen Stelle zum Array hinzugefügt wird. Alle Elemente am oder über dem angegebenen Index werden um eine Position nach rechts verschoben. Der angegebene Index DARF NICHT größer sein als die Anzahl der Elemente im Array. Wenn das "-"-Zeichen verwendet wird, um das Ende des Arrays zu indizieren (siehe [RFC6901]), hat dies den Effekt, den Wert an das Array anzuhängen.

Da diese Operation dazu konzipiert ist, zu vorhandenen Objekten und Arrays hinzuzufügen, wird ihre Zielposition oft nicht existieren. Obwohl somit der Fehlerbehandlungsalgorithmus des Zeigers aufgerufen wird, definiert diese Spezifikation das Fehlerbehandlungsverhalten für "add"-Zeiger so, dass dieser Fehler ignoriert und der Wert wie angegeben hinzugefügt wird.

Das Objekt selbst oder ein es enthaltendes Array muss jedoch existieren, und es bleibt ein Fehler, wenn dies nicht der Fall ist. Zum Beispiel ist ein "add" mit einer Zielposition von "/a/b", beginnend mit diesem Dokument:

{ "a": { "foo": 1 } }

kein Fehler, weil "a" existiert und "b" zu seinem Wert hinzugefügt wird. Es ist ein Fehler in diesem Dokument:

{ "q": { "bar": 2 } }

weil "a" nicht existiert.