4.1. add (aggiungi)
4.1. add (aggiungi)
L'operazione "add" esegue una delle seguenti funzioni, a seconda di ciò a cui fa riferimento la posizione di destinazione:
-
Se la posizione di destinazione specifica un indice di array, un nuovo valore viene inserito nell'array all'indice specificato.
-
Se la posizione di destinazione specifica un membro oggetto che non esiste ancora, viene aggiunto un nuovo membro all'oggetto.
-
Se la posizione di destinazione specifica un membro oggetto che esiste, il valore di quel membro viene sostituito.
L'oggetto operazione DEVE contenere un membro "value" il cui contenuto specifica il valore da aggiungere.
Ad esempio:
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }
Quando l'operazione viene applicata, la posizione di destinazione DEVE fare riferimento a uno dei seguenti:
-
La radice del documento di destinazione - nel qual caso il valore specificato diventa l'intero contenuto del documento di destinazione.
-
Un membro da aggiungere a un oggetto esistente - nel qual caso il valore fornito viene aggiunto a quell'oggetto nella posizione indicata. Se il membro esiste già, viene sostituito dal valore specificato.
-
Un elemento da aggiungere a un array esistente - nel qual caso il valore fornito viene aggiunto all'array nella posizione indicata. Tutti gli elementi all'indice specificato o superiori vengono spostati di una posizione a destra. L'indice specificato NON DEVE essere maggiore del numero di elementi nell'array. Se viene utilizzato il carattere
"-"per indicizzare la fine dell'array (vedere [RFC6901]), ciò ha l'effetto di aggiungere il valore all'array.
Poiché questa operazione è progettata per aggiungere a oggetti e array esistenti, la sua posizione di destinazione spesso non esisterà. Sebbene venga quindi invocato l'algoritmo di gestione degli errori del puntatore, questa specifica definisce il comportamento di gestione degli errori per i puntatori "add" per ignorare tale errore e aggiungere il valore come specificato.
Tuttavia, l'oggetto stesso o un array che lo contiene deve esistere, e rimane un errore se questo non è il caso. Ad esempio, un "add" con una posizione di destinazione di "/a/b" che inizia con questo documento:
{ "a": { "foo": 1 } }
non è un errore, perché "a" esiste e "b" verrà aggiunto al suo valore. È un errore in questo documento:
{ "q": { "bar": 2 } }
perché "a" non esiste.