array:insert-before

Returns an array containing all the members of the supplied array, with one additional member at a specified position.

Signature

array:insert-before(
    $array as array(*), 
    $position as xs:integer, 
    $member as item()*
) as array(*)

Properties

This function is deterministic, context-independent, and focus-independent.

Rules

The function returns an array of size array:size($array) + 1 containing all members from $array whose position is less than $position, then a new member given by $member, and then all members from $array whose position is greater than or equal to $position. Positions are counted from 1.

The result is equivalent to the result of the expression array:join( (array:subarray($array, 1, $position - 1), [$member], array:subarray($array, $position)) )

Error Conditions

A dynamic error occurs [ERRFOAY0001] if $position is not in the range 1 to array:size($array) + 1 inclusive.

Notes

Setting $position to 1 has the effect of prepending the new member at the start of the array. Setting $position to the value array:size($array) + 1 delivers the same result as array:append($array, $member).

Examples

The expression array:insert-before(["a", "b", "c", "d"], 3, ("x", "y")) returns ["a", "b", ("x", "y"), "c", "d"].

The expression array:insert-before(["a", "b", "c", "d"], 5, ("x", "y")) returns ["a", "b", "c", "d", ("x", "y")].

The expression array:insert-before(["a", "b", "c", "d"], 3, ["x", "y"]) returns ["a", "b", ["x", "y"], "c", "d"].