ADD Clause
Syntax
add_clause ::=
path_expression [add_expression] expressionSemantics
The ADD clause is used to add new elements into one or more arrays. It consists of a target expression, which should normally return one or more array items, an optional position expression, which specifies the position within each array where the new elements should be placed, and a new-elements expression that returns the new elements to insert.
The ADD clause iterates over the sequence returned by the target expression. For each target item, if the item is not an array it is skipped. Otherwise, the position expression (if present) and the new-elements expression are computed for the current target array. These two expressions may reference the $ variable, which is bound to the current target array.
If the new-values expression returns nothing, the ADD is a no-op. Otherwise, each item returned by this expression is cast to the element type of the array. An error is raised if any of these casts fail. Otherwise, the new elements are inserted into the target array, as described below.
If the position expression is missing, or if it returns an empty result, the new elements are appended at the end of the target array. An error is raised if the position expression returns more than one item or a non-numeric item. Otherwise, the returned item is cast to an integer. If this integer is less than 0, it is set to 0. If it is greater or equal to the array size, the new elements are appended. Otherwise, if the integer position is P and the new-elements expression returns N items, the 1st item is inserted at position P, the 2nd at position P+1, and so on. The existing array elements at position P and afterwards are shifted N positions to the right.