4.1. add (追加)
4.1. add (追加)
"add" 操作は, ターゲット位置が参照する内容に応じて, 以下の機能のいずれかを実行します:
-
ターゲット位置が配列インデックスを指定する場合, 指定されたインデックスで配列に新しい値が挿入されます。
-
ターゲット位置がまだ存在しないオブジェクトメンバーを指定する場合, オブジェクトに新しいメンバーが追加されます。
-
ターゲット位置が存在するオブジェクトメンバーを指定する場合, そのメンバーの値が置き換えられます。
操作オブジェクトは, 追加する値を指定する内容を持つ "value" メンバーを含まなければなりません。
例えば:
{ "op": "add", "path": "/a/b/c", "value": [ "foo", "bar" ] }
操作が適用される場合, ターゲット位置は以下のいずれかを参照しなければなりません:
-
ターゲット文書のルート - この場合, 指定された値がターゲット文書の全内容になります。
-
既存のオブジェクトに追加するメンバー - この場合, 提供された値が指定された場所でそのオブジェクトに追加されます。メンバーが既に存在する場合は, 指定された値で置き換えられます。
-
既存の配列に追加する要素 - この場合, 提供された値が指定された場所で配列に追加されます。指定されたインデックス以上の要素はすべて右に 1 つずつシフトされます。指定されたインデックスは配列内の要素数より大きくてはなりません。配列の末尾をインデックスするために
"-"文字が使用される場合 ([RFC6901] を参照), これは配列に値を追加する効果があります。
この操作は既存のオブジェクトと配列に追加するように設計されているため, そのターゲット位置は存在しないことがよくあります。したがってポインタのエラー処理アルゴリズムが呼び出されますが, この仕様では "add" ポインタのエラー処理動作をそのエラーを無視し, 指定どおりに値を追加するように定義しています。
ただし, オブジェクト自体またはそれを含む配列は存在する必要があり, そうでない場合はエラーのままです。たとえば, 次の文書から始めて, ターゲット位置が "/a/b" の "add":
{ "a": { "foo": 1 } }
はエラーではありません, なぜなら "a" が存在し, "b" がその値に追加されるからです。次の文書ではエラーです:
{ "q": { "bar": 2 } }
なぜなら "a" が存在しないからです。