List.ReplaceRange
ListReplaces a specified number of items in a list starting at a given index with items from a replacement list.
Syntax
List.ReplaceRange(list as list, index as number, count as number, replaceWith as list) as listParameters
| Name | Type | Required | Description |
|---|---|---|---|
list | list | Yes | The source list. |
index | number | Yes | The zero-based index at which replacement begins. |
count | number | Yes | The number of items to replace. |
replaceWith | list | Yes | The list of items to insert in place of the removed items. The replacement list can have a different length than count. |
Return Value
list — A new list with the specified range replaced by the items in replaceWith.
Remarks
List.ReplaceRange is a combined remove-and-insert operation: it removes count items starting at the zero-based index, then inserts the items from replaceWith at that same position. The replacement list can have a different number of items than were removed, allowing the result to grow or shrink.
The result list length is List.Count(list) - count + List.Count(replaceWith). If replaceWith is an empty list {}, this is equivalent to List.RemoveRange. If count is 0, no items are removed and replaceWith is inserted at index — equivalent to List.InsertRange.
An index of 0 starts the replacement from the very first item. The original list is not modified; a new list is returned. This function is the most flexible of the range-manipulation functions and can implement both insertion and deletion as special cases.
Examples
Example 1: Replace 2 items with 3 items
List.ReplaceRange({1, 2, 3, 4, 5}, 1, 2, {20, 25, 30})Result | |
|---|---|
| 1 | {1, 20, 25, 30, 4, 5} |
Example 2: Replace a single item at a given position
List.ReplaceRange({"A", "B", "C", "D"}, 2, 1, {"X"})Result | |
|---|---|
| 1 | {A, B, X, D} |
Example 3: Replace a range with a shorter list (shrink)
List.ReplaceRange({10, 20, 30, 40, 50}, 1, 3, {99})Result | |
|---|---|
| 1 | {10, 99, 50} |