Inserts new values or modifies existing values at the specified index of a given array, and returns the resulting array.
updatearray( array, index, value )
array: (Any Type Array) The array to modify.
index: (Integer or Integer Array) The one-based index or array of indices at which to update the array.
value: (Any Type or Any Type Array) The new value or values to add or replace existing values.
Any Type Array
This function works with complex data types structures in the same way as simple structures. For example, assume you have a Case data type with a notes
field that represents a list of Notes. When an array of cases
is passed in as the input array, an array of cases returns. When an array of cases.notes
is passed in, an array of notes returns.
The index value must be greater than or equal to 1.
Unless the new value is null, the list of indices must match the list of new values; otherwise, a runtime error returns with this message: The list of indices and list of new values must be of equal length. The list of indices has <value> items. The list of new values has <value> items.
If the type of the new value cannot be cast to the input array type, a runtime error returns with this message: Cannot cast from type <newValueType> to type <inputType>
.
When the input array is a single value (not an array), there will be a runtime error with this message: An array is expected as the first parameter.
For example: updatearray(1, 1, 200)
returns an error
When the index is less than or equal to zero, there will be a runtime error with this message: An invalid index is present (<index>). Indices must be greater or equal to one.
For example: updatearray({1, 2, 3}, 0, 200)
returns an error
If the index is null, or an empty list, the input array is returned with no changes.
If the index is not a number (e.g., a list of nulls, or a string), there will be a runtime error with this message: The indices are not of the expected type. Type of indices: <type passed in>. Type expected: <type expected>.
Update One Item in the Array:
updatearray({1, 2, 3}, 2, 200)
returns 1, 200, 3
Update Multiple Items in the Array:
updatearray({1, 2, 3}, {2, 3}, {200, 300})
returns 1, 200, 300
Update Multiple Items in the Array with the Same Value:
updatearray({1, 2, 3}, {2, 3}, 300)
returns 1, 300, 300
Update One or More Items with Values of a Different Type:
updatearray({1, 2, 3}, 2, "20")
returns 1, 20, 3
Append One or More Items to an Array:
updatearray({1, 2, 3}, 5, 500)
returns 1, 2, 3, null, 500
updatearray({1, 2, 3}, {1, 5}, {100, 500})
returns 100, 2, 3, null, 500
Null Out One or More Items in an Array:
updatearray({1, 2, 3}, 2, pv!Multiple[2])
returns 1, null, 3
where pv!Multiple[2]
has a null value
updatearray({1, 2, 3}, {2, 3}, pv!Multiple[2])
returns 1, null, null
where pv!Multiple[2]
has a null value
updatearray({1, 2, 3}, {4, 5}, pv!Multiple[2])
returns 1, 2, 3, null, null
where pv!Multiple[2]
has a null value
Update a Null Array:
updatearray({tointeger(null)}, 2, 200)
returns null, 200
Update an Empty Array:
updatearray({}, {2, 3}, 3)
returns null, 3, 3
Inserting a Value into an Index of an Array: If you plan to use this function on a node output and simply want to insert one or more values into an array, check out the Is Stored at Index operator discussed in this help topic which provides this specific functionality.
insert(): Use this function if your index is less than or equal to count(array)+1
.
append(): Use this function if you simply want to append values onto the end of the array.