List.InsertRange
ListInserts a list of values into a list at a specified index position.
Syntax
List.InsertRange(list as list, index as number, values as list) as listParameters
| Name | Type | Required | Description |
|---|---|---|---|
list | list | Yes | The original list. |
index | number | Yes | The zero-based index position at which to insert the values. |
values | list | Yes | The list of values to insert. |
Return Value
list — A new list with the values inserted at the given index.
Remarks
List.InsertRange returns a new list with the values list inserted at the specified zero-based index. All items at and after the insertion position are shifted right. The original list is not modified.
An index of 0 inserts at the very beginning. An index equal to the list length inserts at the end, equivalent to using List.Combine({list, values}). If the index is out of range (negative or greater than the list length), an error is raised. To insert a single value rather than a list of values, wrap it in a list literal: {myValue}.
This function is most useful when building a list programmatically and needing to splice values into a specific position. For replacing a range of items, use List.ReplaceRange. For removing items, use List.RemoveRange.
Examples
Example 1: Insert values in the middle of a list
List.InsertRange({1, 2, 5, 6}, 2, {3, 4})Result | |
|---|---|
| 1 | {1, 2, 3, 4, 5, 6} |
Example 2: Insert at the beginning
List.InsertRange({"B", "C", "D"}, 0, {"A"})Result | |
|---|---|
| 1 | {A, B, C, D} |
Example 3: Insert at the end
List.InsertRange({10, 20, 30}, 3, {40, 50})Result | |
|---|---|
| 1 | {10, 20, 30, 40, 50} |