Text.Insert
TextInserts a text value into another text value at the specified offset position.
Syntax
Text.Insert(text as nullable text, offset as number, newText as text) as nullable textParameters
| Name | Type | Required | Description |
|---|---|---|---|
text | text | Yes | The original text value. |
offset | number | Yes | The zero-based position at which to insert newText. |
newText | text | Yes | The text value to insert. |
Return Value
text — A new text value with newText inserted at the given offset.
Remarks
Text.Insert inserts newText into text at the zero-based offset position. All characters at and after offset are shifted right, and the inserted content takes their place. The result is always longer than the original by the length of newText.
If text is null, the function returns null. An offset of 0 prepends newText to the beginning. An offset equal to the length of text appends newText to the end. An out-of-range offset raises an error.
This function is equivalent to: Text.Start(text, offset) & newText & Text.End(text, Text.Length(text) - offset)
Use Text.Insert when you know the exact position at which to insert content. If you need to replace characters at a position rather than insert between them, use Text.ReplaceRange. If you need to remove characters at a position, use Text.RemoveRange. For adding a prefix or suffix unconditionally, simple string concatenation with & is clearer.
Examples
Example 1: Insert a separator into a formatted code
Text.Insert("5551234567", 3, "-")Result | |
|---|---|
| 1 | 555-1234567 |
Example 3: Insert a region code into a product identifier
Text.Insert("Widget-001", 6, "-East")Result | |
|---|---|
| 1 | Widget-East-001 |