Array

Related Docs

• Working with TArrays
• Working with TSets
• Working with TMaps

Epic discourages the use of C++ Standard Library containers in Unreal Engine, and instead provides its own set of containers, which are optimized for the engine's architecture and mechanisms. They are also more compatible with the Reflection System and the Garbage Collector.

TArray<T> is your typical dynamic array, and is very similar to std::vector in memory management. TArrays support pushing and popping elements from the back in (amortized) constant time, and \(O(n)\) queries, insertions and removals. They also support range-based for loops.

TArray<int32> Arr;
Arr.Add(0);
Arr.Add(1);
Arr.Remove(1);
int32 Total = 0;
for (auto& Element : StrArr) {
    Total += Element;
}

TArrays can be converted into a binary heap data structure, providing constant time access to the minimum element, and logarithmic time insertion and removal of elements. Existing arrays can be heapified by calling Heapify().

Arr.Heapify();
Arr.HeapPush(3);
Arr.HeapPush(1);
Arr.HeapPush(2);
int32 Top = Arr.HeapTop(); // Top: 1

Another feature of TArrays is support for slack memory, which can be reserved and released using the Reserve and Shrink methods, respectively. Reset is another way to free up some room. It drops all elements but does not relinquish memory.

TArray<int32> Arr;
Arr.Reserve(100);
Arr.Add(1);
Arr.Shrink();

TSet<T> is similar to std::unordered_set, a container for unique unordered elements which supports adding, finding, and removing elements in constant time. It also supports range-based for loops, and slack memory reservation.

TSet<FString> FruitSet;
FruitSet.Add(TEXT("Pear")); // Returns the temporary index
FruitSet.Emplace(TEXT("Orange")); // Avoids creating temporaries
FruitSet.Append(OtherSet); // All elements from OtherSet are added
FString* PtrBanana = FruitSet.Find(TEXT("Banana")); // Returns nullptr
FruitSet.Contains(TEXT("Apple")); // Evaluates to false
FruitSet.Remove(TEXT("Orange")); // Removes "Orange"
FruitSet.Reserve(10); // Allocates memory for 10 elements

TMap<K,V> and TMultiMap<K,V> are Unreal's equivalent to std::unordered_map and std::unordered_multimap. They are containers for key-value pairs (with unique keys, in the case of TMaps), and support adding, finding, and removing elements in constant time. Many of the methods are similar to those of TSets.

TMap<int32, FString> FruitMap;
FruitMap.Add(5, TEXT("Banana"));
FruitMap.Emplace(3, TEXT("Orange"));
FruitMap.Append(OtherMap);
for (auto& Elem : FruitMap) { 
    // In range-based loops, each element exposes Key and Value properties
    ... Elem.Key ... Elem.Value ...
}
if (FruitMap.Contains(3)) { 
    // Always check that the map contains the key before using operator[]
    ... FruitMap[3] ... 
}
FString* Ptr8 = FruitMap.Find(8); // nullptr