Replace

Description

The Replace operation finds the index of a data element. In List Utils, there are 4 functions for Replace:

• The listutils:replace_index function replaces an element at an index.
• The listutils:replace_last function replaces the last matching element.
• The listutils:replace_first function replaces the first matching element.
• The listutils:replace_all function replaces all matching elements. It is recommended to use the listutils:replace_last function instead of the listutils:replace_first function, because the former has a more efficient implementation.

Usage

Input

Using listutils:replace_last, listutils:replace_first and listutils:replace_all

Input is given using the listutils:in storage:

Field	Meaning
List	The list that contains the element.
Data	The element to replace.
ReplaceData	The element to replace the Data element with.

Using listutils:replace_index

When using the listutils:replace_index function, Data is not used. Instead, the $listutils.index listutils.in score should be used to pass the index to be replaced to the function. List should still be used as a list that contains the index to replace, and ReplaceData should still be used as the element to replace the data at the index with.

After defining the input, run one of the listutils:replace functions.

Comparison functions

Various comparison functions can be used to match elements. For more about comparison functions, see the Comparison Functions page.

Errors

Errors that display when executing the listutils:replace functions as a player in debug mode.

Error	Message
TBD	TBD

Return values

Success

The success of the operation is stored in the $listutils.success listutils.out score. This score is 1 on success and 0 otherwise. Success will be 0 when the type of the element to insert is not the same as the type of all other elements in the list, or the element to replace is not in the list, or if the index provided is out of bounds.

Result

The result of the operation is stored in the List field in the listutils:out storage. This result contains the list with matching element(s) replaced.

Additionally, the $listutils.result listutils.out score contains the amount of elements replaceddwhen using replace_all.

When using replace_index, the replaced element is stored inside the Data field in the listutils:out storage.

Example

Take the example list ExampleList: ["foo", "Hello World!", "foo", "bar"] in the listutils:examples storage. We want to replace all occurrences of "foo" with "baz":

# Add List to the input.
data modify storage listutils:in List set from storage listutils:examples ExampleList
# Add Data to the input.
data modify storage listutils:in Data set value "foo"
# Add ReplaceData to the input.
data modify storage listutils:in ReplaceData set value "baz"
# Call the function.
function listutils:replace_all

This would return 2 as the result in $listutils.result listutils.out (replaced 2 elements) and would yield the list ["baz", "Hello World!", "baz", "bar"].