Description
Inserts a single element at the specified index, shifting all subsequent elements right by one. Returns the insertion index. Overloads also accept a const-ref, an initializer list, another TArray, or a raw pointer + count for batch insertion.
Caveats & Gotchas
- • Insert calls CheckAddress() internally to detect the case where &Item is already inside the container being modified. Passing a reference to an element of the same array is therefore caught (assert in Debug builds) — but only for single-element overloads; the raw-pointer batch overload does not have this guard.
- • Inserting near the front of a large array is O(N) due to the element shift. If order doesn't matter, consider Add() + swap, or use TDeque for frequent front/middle insertions.
- • Returns the insertion index (same as the passed-in Index), not the new array size. This is consistent with Add() semantics.
Signature
SizeType Insert(ElementType&& Item, SizeType Index)Parameters
| Name | Type | Description | Default |
|---|---|---|---|
| Item | ElementType&& | The element to insert. | — |
| Index | SizeType | The position to insert at. Existing elements at and after this index are shifted right. | — |
Return Type
SizeType Examples
Insert a single element at a known position C++
TArray<FString> Tags;
Tags.Add(TEXT("alpha"));
Tags.Add(TEXT("gamma"));
Tags.Insert(TEXT("beta"), 1);
// Tags is now {"alpha", "beta", "gamma"} Batch insert from another array C++
TArray<int32> Base = {1, 4, 5};
TArray<int32> Extra = {2, 3};
Base.Insert(Extra, 1);
// Base is now {1, 2, 3, 4, 5}Tags
Version History
Introduced in: 4.0
| Version | Status | Notes |
|---|---|---|
| 5.6 | stable | — |
Feedback
Was this helpful?