fn:insert-before

Returns a sequence constructed by inserting an item or a sequence of items at a given position within an existing sequence.

Signature

fn:insert-before(
    $target as item()*, 
    $position as xs:integer, 
    $inserts as item()*
) as item()*

Properties

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

Rules

The value returned by the function consists of all items of $target whose index is less than $position, followed by all items of $inserts, followed by the remaining elements of $target, in that order.

Notes

If $target is the empty sequence, $inserts is returned. If $inserts is the empty sequence, $target is returned.

If $position is less than one (1), the first position, the effective value of $position is one (1). If $position is greater than the number of items in $target, then the effective value of $position is equal to the number of items in $target plus 1.

The value of $target is not affected by the sequence construction.

Examples

let $abc := ("a", "b", "c")

The expression fn:insert-before($abc, 0, "z") returns ("z", "a", "b", "c").

The expression fn:insert-before($abc, 1, "z") returns ("z", "a", "b", "c").

The expression fn:insert-before($abc, 2, "z") returns ("a", "z", "b", "c").

The expression fn:insert-before($abc, 3, "z") returns ("a", "b", "z", "c").

The expression fn:insert-before($abc, 4, "z") returns ("a", "b", "c", "z").