TArray

class Core Blueprint Since 1.0

#include "Containers/Array.h"

Access: public

Description

The primary dynamic array container in Unreal Engine, equivalent to `std::vector`. Stores elements contiguously in memory. Supports UPROPERTY reflection for Blueprint integration and engine serialization. Provides ordered, random-access storage with amortized O(1) append.

Caveats & Gotchas

• TArray is not thread-safe. Protect concurrent access with locks or use thread-safe alternatives.
• Avoid storing raw UObject pointers in TArray across frames — use TArray<TObjectPtr<T>> or TArray<TWeakObjectPtr<T>> to cooperate with GC.
• Reserve() upfront when you know the final size to avoid repeated reallocations.
• Range-based for loops invalidate if you add/remove elements during iteration. Copy first or use a reverse index loop for removal.
• RemoveAt() is O(N) unless you use RemoveAtSwap() which is O(1) but does not preserve order.

Signature

template <typename InElementType, typename InAllocatorType = FDefaultAllocator> class TArray

Examples

Common TArray operations C++

TArray<int32> Numbers;
Numbers.Reserve(10);         // Preallocate
Numbers.Add(1);
Numbers.Add(2);
Numbers.Add(3);
Numbers.Insert(99, 0);       // Insert at index 0

// Iteration
for (int32 N : Numbers)
{
    UE_LOG(LogTemp, Log, TEXT("%d"), N);
}

// Find
int32 Idx = Numbers.IndexOfByKey(2); // Returns 2 (after insert)
bool bHas = Numbers.Contains(99);    // true

// Remove (preserves order, O(N))
Numbers.Remove(99);

// Sort
Numbers.Sort([](int32 A, int32 B) { return A < B; });

UPROPERTY declaration C++

UPROPERTY(EditAnywhere, BlueprintReadWrite)
TArray<FString> Names;

UPROPERTY()
TArray<TObjectPtr<UMyObject>> ManagedObjects; // GC-safe

Functions (63)

Utility 34 Add / Insert 5 Allocation 3 Heap Operations 6 Internal State 1 Query 3 Remove 4 Search 1 Serialization 6

Utility

34 ▼

Access	Type	Name	Description
public	function	TArray::Empty	Destructs all elements and sets Num to 0.
public	function	TArray::Insert	Inserts a single element at the specified index, shifting all subsequent elements right by one.
public	function	TArray::Pop	Removes and returns the last element of the array using move semantics.
public	function	TArray::Push	Appends an element to the end of the array, identical in behaviour to Add().
public	function	TArray::RemoveAt	Removes the element at Index, destructs it, and shifts all subsequent elements left to close the gap.
public	function	TArray::SetNum	Resizes the array to exactly NewNum elements, default-constructing any new elements if growing, and destructing trailing elements if shrinking.
public	function	TArray::Add	Appends an element to the end of the array and returns its index.
public	function	TArray::AddUnique	Adds an element only if it is not already present in the array.
public	function	TArray::ContainsByPredicate	Returns true if any element satisfies the predicate.
public	function	TArray::Emplace	Constructs a new element in-place at the end of the array using the provided constructor arguments.
public	function	TArray::Find	Searches for Item using operator== and returns true if found, setting Index to its position.
public	function	TArray::FindByPredicate	Returns a pointer to the first element for which Pred returns true, or nullptr if none match.
public	function	TArray::Heapify	Rearranges the array in-place into a valid max-heap ordered by operator< (min value at the root).
public	function	TArray::Num	Returns the number of elements currently in the array.
public	function	TArray::Remove	Removes all elements equal to Item and returns the number of elements removed.
public	function	TArray::RemoveAll	Removes all elements for which the predicate returns true, preserving order of remaining elements.
public	function	TArray::RemoveAtSwap	Removes the element at Index by filling its slot with element(s) from the end of the array.
public	function	TArray::Reserve	Pre-allocates memory for at least Number elements without changing the logical size.
public	function	TArray::Reset	Removes all elements (calls destructors) but retains allocated memory for reuse.
public	function	TArray::Shrink	Reallocates the backing buffer so it exactly fits the current number of elements, releasing any excess capacity (slack).
public	function	TArray::Sort	Sorts the array in-place using an introspective sort (introsort).
public	function	TArray::StableSort	Sorts the array in-place and guarantees that equal elements retain their original relative order.
public	function	TArray::Swap	Swaps two elements at the given indices after verifying both indices are in bounds.
public	function	TArray — deprecated bool shrinking overloads deprecated	Documents the UE 5.
public	function	TArray::AddUninitialized	Grows the array by Count elements without constructing them, returning the index of the first new slot.
public	function	TArray::CheckAddress	Asserts that the given address does not point into the array's current backing buffer.
public	function	TArray::CheckInvariants	Asserts (in Debug/Development builds only) that ArrayNum >= 0 and ArrayMax >= ArrayNum.
public	function	TArray::InsertDefaulted	Inserts Count default-constructed elements at Index, shifting existing elements right.
public	function	TArray::InsertDefaulted_GetRef	Inserts a single default-constructed element at Index and returns a reference to it.
public	function	TArray::InsertUninitialized	Opens a gap of Count uninitialized element slots at Index, shifting later elements right.
public	function	TArray::InsertZeroed	Inserts Count zero-initialized elements at Index by shifting existing elements right and then zeroing the new slots with FMemory::Memzero.
public	function	TArray::InsertZeroed_GetRef	Inserts a single zero-initialized element at Index and returns a reference to it, allowing immediate field-by-field initialization without a second array lookup.
protected	function	TArray::RangeCheck	Validates that an index is within the array bounds, triggering a checkf assertion on failure.
public	function	TArray::SwapMemory	Swaps two elements by directly exchanging their raw memory bytes via the global Swap template.

Add / Insert

5 ▼

Access	Type	Name	Description
public	function	TArray::Append	Appends all elements from Source to the end of this array in a single allocation.
public	function	TArray::Init	Resets the array to Number elements, every one a copy of Element.
public	function	TArray::AddDefaulted	Appends Count new elements at the end of the array, each default-constructed via DefaultConstructItems.
public	function	TArray::AddZeroed	Appends Count new elements at the end of the array, zero-initialising their memory via FMemory::Memzero.
public	function	TArray::EmplaceAt	Constructs a new element in-place at the given index, shifting all subsequent elements right by one.

Allocation

3 ▼

Access	Type	Name	Description
public	function	TArray::SetNumUninitialized	Resizes the array to exactly NewNum elements without initialising any newly added memory.
public	function	TArray::SetNumZeroed	Resizes the array to exactly NewNum elements.
public	function	TArray::SetNumUnsafeInternal	Directly sets the internal element count without touching memory, running destructors, or reallocating.

Heap Operations

6 ▼

Access	Type	Name	Description
public	function	TArray::HeapPop	Removes and returns the top element (the maximum under the current predicate) from the heap, then re-heapifies the remaining elements.
public	function	TArray::HeapPopDiscard	Removes the top element from the heap without returning it, then re-heapifies.
public	function	TArray::HeapPush	Inserts an element into the array while maintaining max-heap order, sifting the new element up to its correct position.
public	function	TArray::HeapSort	Sorts the array in ascending order using heap sort.
public	function	TArray::HeapRemoveAt	Removes an arbitrary element at the given index from the heap, then restores heap order by sifting the replacement element both up and down as needed.
public	function	TArray::VerifyHeap	Asserts (via check()) that the array satisfies the heap property under the given predicate.

Internal State

1 ▼

Access	Type	Name	Description
public	function	TArray — UE_REQUIRES constraint	Template constraint applied to TArray cross-type constructors and assignment operators.

Query

3 ▼

Access	Type	Name	Description
public	function	TArray::Contains	Returns true if the array contains at least one element equal to Item.
public	function	TArray::IsEmpty	Returns true if the array contains no elements.
public	function	TArray::FindLast	Searches the array from the end toward the front and returns the index of the last element equal to Item, or INDEX_NONE if not found.

Remove

4 ▼

Access	Type	Name	Description
public	function	TArray::RemoveSingle	Removes the first occurrence of Item from the array while preserving element order.
public	function	TArray::RemoveAllSwap	Removes all elements satisfying Predicate using RemoveAtSwap internally, which replaces each removed element with the last element rather than shifting.
public	function	TArray::RemoveSingleSwap	Removes the first occurrence of Item using RemoveAtSwap — the removed slot is filled by the last element, making the actual removal O(1) after the O(N) linear search.
public	function	TArray::RemoveSwap	Removes all occurrences of Item using RemoveAtSwap, which fills each removed slot with the last element.

Search

1 ▼

Access	Type	Name	Description
public	function	TArray::FindItemByClass	Searches a TArray of UObject pointers for the first element whose runtime class matches (via IsA) the template parameter SearchType.

Serialization

6 ▼

Access	Type	Name	Description
public	function	TArray::AppendHash	A static method that feeds the element type's layout descriptor into a SHA1 hash.
public	function	TArray::BulkSerialize	Serializes the entire array as a raw memory blob during loading, bypassing per-element serialization for significant performance gains.
public	function	TArray::CopyUnfrozen	Reconstructs a live TArray from a frozen (WriteMemoryImage) binary representation by placement-constructing a new TArray at Dst and copying element data through the allocator's CopyUnfrozen path.
public	function	TArray::CountBytes	Reports the array's current and peak memory usage to an accounting archive by calling Ar.
public	function	TArray::ToString	Converts the frozen memory image representation of this TArray to a human-readable string by delegating to the allocator's ToString.
public	function	TArray::WriteMemoryImage	Serialises this TArray into a frozen memory image via FMemoryImageWriter.

Properties

Access	Type	Name	Description
protected	property	TArray::AllocatorInstance	The allocator object responsible for managing the raw memory backing the array.
protected	property	TArray::ArrayMax	Stores the number of elements the array can hold before a reallocation is needed.
protected	property	TArray::ArrayNum	Stores the number of elements currently held in the array.

Version History

Introduced in: 1.0

Version	Status	Notes
5.6	stable	—
5.0	stable	TObjectPtr support added for UPROPERTY arrays.

Feedback

Was this helpful?