array:put

Returns an array containing all the members of a supplied array, except for one member which is replaced with a new value.

Signature

array:put(
    $array as array(*), 
    $position as xs:integer, 
    $member as item()*
) as array(*)

Properties

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

Rules

The result is an array whose size is array:size($array), in which all members in positions other than $position are the same as the members in the corresponding position of $array, and the member in position $position is $member.

The result is equivalent to the result of the expression $array => array:remove($position) => array:insert-before($position, $member).

Error Conditions

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

This error will always occur if $array is empty.

Examples

The expression array:put(["a", "b", "c"], 2, "d") returns ["a", "d", "c"].

The expression array:put(["a", "b", "c"], 2, ("d", "e")) returns ["a", ("d", "e"), "c"].

The expression array:put(["a"], 1, ["d", "e"]) returns [["d", "e"]].