TArray

Templated dynamic array

Windows
MacOS
Linux

Inheritance Hierarchy

References

Module

Core

Header

/Engine/Source/Runtime/Core/Public/Containers/Array.h

Include

#include "Containers/Array.h"

Syntax

template<typename InElementType, typename InAllocator>
class TArray

Remarks

Templated dynamic array

A dynamically sized array of typed elements. Makes the assumption that your elements are relocate-able; i.e. that they can be transparently moved to new memory without a copy constructor. The main implication is that pointers to elements in the TArray may be invalidated by adding or removing other elements to the array. Removal of elements is O(N) and invalidates the indices of subsequent elements.

Caution: as noted below some methods are not safe for element types that require constructors.

Variables

Name Description

Protected variable

ElementAllocato...

 

AllocatorInstance

Protected variable

SizeType

 

ArrayMax

Protected variable

SizeType

 

ArrayNum

Constructors

Name Description

Public function

TArray()

Constructor, initializes element number counters.

Public function

TArray

(
    std::initializer_list< InElementTyp...
)

Initializer list constructor

Public function

TArray

(
    const TArray< OtherElementType, Oth...
)

Copy constructor with changed allocator. Use the common routine to perform the copy.

Public function

TArray

(
    const TArray& Other
)

Copy constructor. Use the common routine to perform the copy.

Public function

TArray

(
    TArray&& Other
)

Move constructor.

Public function

TArray

(
    TArray< OtherElementType, OtherAllo...
)

Move constructor.

Public function

TArray

(
    const ElementType* Ptr,
    SizeType Count
)

Constructor from a raw array of elements.

Public function

TArray

(
    const TArray& Other,
    SizeType ExtraSlack
)

Copy constructor. Use the common routine to perform the copy.

Public function

TArray

(
    TArray< OtherElementType, Allocator...,
    SizeType ExtraSlack
)

Move constructor.

Destructors

Name Description

Public function

~TArray()

Destructor.

Functions

Name Description

Public function

SizeType

 

Add

(
    const ElementType& Item
)

Adds a new item to the end of the array, possibly reallocating the whole array to fit.

Public function

SizeType

 

Add

(
    ElementType&& Item
)

Adds a new item to the end of the array, possibly reallocating the whole array to fit.

Public function

ElementType ...

 

Add_GetRef

(
    const ElementType& Item
)

Adds a new item to the end of the array, possibly reallocating the whole array to fit.

Public function

ElementType ...

 

Add_GetRef

(
    ElementType&& Item
)

Adds a new item to the end of the array, possibly reallocating the whole array to fit.

Public function

SizeType

 

AddDefaulted

(
    SizeType Count
)

Adds new items to the end of the array, possibly reallocating the whole array to fit.

Public function

ElementType ...

 

AddDefaulted_GetRef()

Add a new item to the end of the array, possibly reallocating the whole array to fit.

Public function

SizeType

 

AddUninitialized

(
    SizeType Count
)

Adds a given number of uninitialized elements into the array.

Public function

SizeType

 

AddUnique

(
    ElementType&& Item
)

Adds unique element to array if it doesn't exist.

Move semantics version.

Public function

SizeType

 

AddUnique

(
    const ElementType& Item
)

Adds unique element to array if it doesn't exist.

Public function

SizeType

 

AddZeroed

(
    SizeType Count
)

Adds new items to the end of the array, possibly reallocating the whole array to fit.

Public function

ElementType ...

 

AddZeroed_GetRef()

Adds a new item to the end of the array, possibly reallocating the whole array to fit.

Public function

void

 

Append

(
    TArray< OtherElementType, OtherAllo...
)

Appends the specified array to this array.

Public function

void

 

Append

(
    std::initializer_list< ElementType ...
)

Adds an initializer list of elements to the end of the TArray.

Public function

void

 

Append

(
    const ElementType* Ptr,
    SizeType Count
)

Adds a raw array of elements to the end of the TArray.

Public function

void

 

Append

(
    const TArray< OtherElementType, Oth...
)

Appends the specified array to this array.

Allocator changing version.

Public function Const

RangedForCon...

 

begin()

Public function

RangedForIte...

 

begin()

DO NOT USE DIRECTLY STL-like iterators to enable range-based for loop support.

Public function

void

 

BulkSerialize

(
    FArchive& Ar,
    bool bForcePerElementSerialization
)

Bulk serialize array as a single memory blob when loading.

Public function Const

void

 

CheckAddress

(
    const ElementType* Addr
)

Checks that the specified address is not part of an element within the container.

Public function Const

void

 

CheckInvariants()

Checks array invariants: if array size is greater than zero and less than maximum.

Public function Const

bool

 

Contains

(
    const ComparisonType& Item
)

Checks if this array contains the element.

Public function Const

bool

 

ContainsByPredicate

(
    Predicate Pred
)

Checks if this array contains element for which the predicate is true.

Public function Const

void

 

CountBytes

(
    FArchive& Ar
)

Count bytes needed to serialize this array.

Public function Const

TConstIterat...

 

CreateConstIterator()

Creates a const iterator for the contents of this array

Public function

TIterator

 

CreateIterator()

Creates an iterator for the contents of this array

Public function

SizeType

 

Emplace

(
    ArgsType&&... Args
)

Constructs a new item at the end of the array, possibly reallocating the whole array to fit.

Public function

ElementType ...

 

Emplace_GetRef

(
    ArgsType&&... Args
)

Constructs a new item at the end of the array, possibly reallocating the whole array to fit.

Public function

void

 

EmplaceAt

(
    SizeType Index,
    ArgsType&&... Args
)

Constructs a new item at a specified index, possibly reallocating the whole array to fit.

Public function

ElementType ...

 

EmplaceAt_GetRef

(
    SizeType Index,
    ArgsType&&... Args
)

Constructs a new item at a specified index, possibly reallocating the whole array to fit.

Public function

void

 

Empty

(
    SizeType Slack
)

Empties the array. It calls the destructors on held items if needed.

Public function

RangedForIte...

 

end()

Public function Const

RangedForCon...

 

end()

Public function Const

TArray< Elem...

 

FilterByPredicate

(
    Predicate Pred
)

Filters the elements in the array based on a predicate functor.

Public function Const

bool

 

Find

(
    const ElementType& Item,
    SizeType& Index
)

Finds element within the array.

Public function Const

SizeType

 

Find

(
    const ElementType& Item
)

Finds element within the array.

Public function

ElementType ...

 

FindByKey

(
    const KeyType& Key
)

Finds an item by key (assuming the ElementType overloads operator== for the comparison).

Public function Const

const Elemen...

 

FindByKey

(
    const KeyType& Key
)

Finds an item by key (assuming the ElementType overloads operator== for the comparison).

Public function

ElementType ...

 

FindByPredicate

(
    Predicate Pred
)

Finds an element which matches a predicate functor.

Public function Const

const Elemen...

 

FindByPredicate

(
    Predicate Pred
)

Finds an element which matches a predicate functor.

Public function Const

bool

 

FindItemByClass

(
    SearchType** Item,
    SizeType* ItemIndex,
    SizeType StartIndex
)

Searches for the first entry of the specified type, will only work with TArray.

Public function Const

SizeType

 

FindLast

(
    const ElementType& Item
)

Finds element within the array starting from the end.

Public function Const

bool

 

FindLast

(
    const ElementType& Item,
    SizeType& Index
)

Finds element within the array starting from the end.

Public function Const

SizeType

 

FindLastByPredicate

(
    Predicate Pred
)

Searches the array for the last occurrence of an element which matches the specified predicate.

Public function Const

SizeType

 

FindLastByPredicate

(
    Predicate Pred,
    SizeType Count
)

Searches an initial subrange of the array for the last occurrence of an element which matches the specified predicate.

Public function Const

SIZE_T

 

GetAllocatedSize()

Helper function to return the amount of memory allocated by this container.

Public function

ElementType ...

 

GetData()

Helper function for returning a typed pointer to the first array entry.

Public function Const

const Elemen...

 

GetData()

Helper function for returning a typed pointer to the first array entry.

Public function Const

SizeType

 

GetSlack()

Returns the amount of slack in this array in elements.

Public function Const

uint32

 

GetTypeSize()

Helper function returning the size of the inner type.

Public function

void

 

Heapify

(
    const PREDICATE_CLASS& Predicate
)

Implicit heaps Builds an implicit heap from the array.

Public function

void

 

Heapify()

Builds an implicit heap from the array.

Public function

void

 

HeapPop

(
    ElementType& OutItem,
    const PREDICATE_CLASS& Predicate,
    bool bAllowShrinking
)

Removes the top element from the heap.

Public function

void

 

HeapPop

(
    ElementType& OutItem,
    bool bAllowShrinking
)

Removes the top element from the heap.

Public function

void

 

HeapPopDiscard

(
    const PREDICATE_CLASS& Predicate,
    bool bAllowShrinking
)

Removes the top element from the heap.

Public function

void

 

HeapPopDiscard

(
    bool bAllowShrinking
)

Removes the top element from the heap.

Public function

SizeType

 

HeapPush

(
    const ElementType& InItem,
    const PREDICATE_CLASS& Predicate
)

Adds a new element to the heap.

Public function

SizeType

 

HeapPush

(
    ElementType&& InItem,
    const PREDICATE_CLASS& Predicate
)

Adds a new element to the heap.

Public function

SizeType

 

HeapPush

(
    const ElementType& InItem
)

Adds a new element to the heap.

Public function

SizeType

 

HeapPush

(
    ElementType&& InItem
)

Adds a new element to the heap.

Public function

void

 

HeapRemoveAt

(
    SizeType Index,
    const PREDICATE_CLASS& Predicate,
    bool bAllowShrinking
)

Removes an element from the heap.

Public function

void

 

HeapRemoveAt

(
    SizeType Index,
    bool bAllowShrinking
)

Removes an element from the heap.

Public function

void

 

HeapSort()

Performs heap sort on the array.

Public function

void

 

HeapSort

(
    const PREDICATE_CLASS& Predicate
)

Performs heap sort on the array.

Public function

ElementType ...

 

HeapTop()

Returns the top element from the heap (does not remove the element).

Public function Const

const Elemen...

 

HeapTop()

Returns the top element from the heap (does not remove the element).

Const version.

Public function Const

SizeType

 

IndexOfByKey

(
    const KeyType& Key
)

Finds an item by key (assuming the ElementType overloads operator== for the comparison).

Public function Const

SizeType

 

IndexOfByPredicate

(
    Predicate Pred
)

Finds an item by predicate.

Public function

void

 

Init

(
    const ElementType& Element,
    SizeType Number
)

Sets the size of the array, filling it with the given element.

Public function

SizeType

 

Insert

(
    const TArray< ElementType, OtherAll...,
    const SizeType InIndex
)

Inserts given elements into the array at given location.

Public function

SizeType

 

Insert

(
    const ElementType& Item,
    SizeType Index
)

Inserts a given element into the array at given location.

Public function

SizeType

 

Insert

(
    const ElementType* Ptr,
    SizeType Count,
    SizeType Index
)

Inserts a raw array of elements at a particular index in the TArray.

Public function

SizeType

 

Insert

(
    std::initializer_list< ElementType ...,
    const SizeType InIndex
)

Inserts given elements into the array at given location.

Public function

SizeType

 

Insert

(
    TArray< ElementType, OtherAllocator...,
    const SizeType InIndex
)

Inserts given elements into the array at given location.

Public function

SizeType

 

Insert

(
    ElementType&& Item,
    SizeType Index
)

Inserts a given element into the array at given location. Move semantics version.

Public function

ElementType ...

 

Insert_GetRef

(
    ElementType&& Item,
    SizeType Index
)

Inserts a given element into the array at given location. Move semantics version.

Public function

ElementType ...

 

Insert_GetRef

(
    const ElementType& Item,
    SizeType Index
)

Inserts a given element into the array at given location.

Public function

void

 

InsertDefaulted

(
    SizeType Index,
    SizeType Count
)

Inserts a given number of default-constructed elements into the array at a given location.

Public function

ElementType ...

 

InsertDefaulted_GetRef

(
    SizeType Index
)

Inserts a default-constructed element into the array at a given location.

Public function

void

 

InsertUninitialized

(
    SizeType Index,
    SizeType Count
)

Inserts a given number of uninitialized elements into the array at given location.

Public function

void

 

InsertZeroed

(
    SizeType Index,
    SizeType Count
)

Inserts a given number of zeroed elements into the array at given location.

Public function

ElementType ...

 

InsertZeroed_GetRef

(
    SizeType Index
)

Inserts a zeroed element into the array at given location.

Public function Const

bool

 

IsValidIndex

(
    SizeType Index
)

Tests if index is valid, i.e. greater than or equal to zero, and less than the number of elements in the array.

Public function

ElementType ...

 

Last

(
    SizeType IndexFromTheEnd
)

Returns n-th last element from the array.

Public function Const

const Elemen...

 

Last

(
    SizeType IndexFromTheEnd
)

Returns n-th last element from the array.

Const version of the above.

Public function Const

SizeType

 

Max()

Returns maximum number of elements in array.

Public function Const

SizeType

 

Num()

Returns number of elements in array.

Public function

ElementType

 

Pop

(
    bool bAllowShrinking
)

Pops element from the array.

Public function

void

 

Push

(
    ElementType&& Item
)

Pushes element into the array.

Public function

void

 

Push

(
    const ElementType& Item
)

Pushes element into the array.

Const ref version of the above.

Public function Const

void

 

RangeCheck

(
    SizeType Index
)

Checks if index is in array range.

Public function

SizeType

 

Remove

(
    const ElementType& Item
)

Removes as many instances of Item as there are in the array, maintaining order but not indices.

Public function

SizeType

 

RemoveAll

(
    const PREDICATE_CLASS& Predicate
)

Remove all instances that match the predicate, maintaining order but not indices Optimized to work with runs of matches/non-matches

Public function

void

 

RemoveAllSwap

(
    const PREDICATE_CLASS& Predicate,
    bool bAllowShrinking
)

Remove all instances that match the predicate

Public function

void

 

RemoveAt

(
    SizeType Index
)

Removes an element (or elements) at given location optionally shrinking the array.

Public function

void

 

RemoveAt

(
    SizeType Index,
    CountType Count,
    bool bAllowShrinking
)

Removes an element (or elements) at given location optionally shrinking the array.

Public function

void

 

RemoveAtSwap

(
    SizeType Index,
    CountType Count,
    bool bAllowShrinking
)

Removes an element (or elements) at given location optionally shrinking the array.

Public function

void

 

RemoveAtSwap

(
    SizeType Index
)

Removes an element (or elements) at given location optionally shrinking the array.

Public function

SizeType

 

RemoveSingle

(
    const ElementType& Item
)

Removes the first occurrence of the specified item in the array, maintaining order but not indices.

Public function

SizeType

 

RemoveSingleSwap

(
    const ElementType& Item,
    bool bAllowShrinking
)

Removes the first occurrence of the specified item in the array.

Public function

SizeType

 

RemoveSwap

(
    const ElementType& Item
)

Removes item from the array.

Public function

void

 

Reserve

(
    SizeType Number
)

Reserves memory such that the array can contain at least Number elements.

Public function

void

 

Reset

(
    SizeType NewSize
)

Same as empty, but doesn't change memory allocations, unless the new size is larger than the current array.

Public function

void

 

SetNum

(
    SizeType NewNum,
    bool bAllowShrinking
)

Resizes array to given number of elements.

Public function

void

 

SetNumUninitialized

(
    SizeType NewNum,
    bool bAllowShrinking
)

Resizes array to given number of elements. New elements will be uninitialized.

Public function

void

 

SetNumUnsafeInternal

(
    SizeType NewNum
)

Does nothing except setting the new number of elements in the array.

Public function

void

 

SetNumZeroed

(
    SizeType NewNum,
    bool bAllowShrinking
)

Resizes array to given number of elements. New elements will be zeroed.

Public function

void

 

Shrink()

Shrinks the array's used memory to smallest possible to store elements currently in it.

Public function

void

 

Sort()

Sorts the array assuming < operator is defined for the item type.

Public function

void

 

Sort

(
    const PREDICATE_CLASS& Predicate
)

Sorts the array using user define predicate class.

Public function

void

 

StableSort()

Stable sorts the array assuming < operator is defined for the item type.

Public function

void

 

StableSort

(
    const PREDICATE_CLASS& Predicate
)

Stable sorts the array using user defined predicate class.

Public function

void

 

Swap

(
    SizeType FirstIndexToSwap,
    SizeType SecondIndexToSwap
)

Element-wise array element swap.

This version is doing more sanity checks than SwapMemory.

Public function

void

 

SwapMemory

(
    SizeType FirstIndexToSwap,
    SizeType SecondIndexToSwap
)

Element-wise array memory swap.

Public function Const

const Elemen...

 

Top()

Returns the top element, i.e. the last one.

Const version of the above.

Public function

ElementType ...

 

Top()

Returns the top element, i.e. the last one.

Public function

void

 

VerifyHeap

(
    const PREDICATE_CLASS& Predicate
)

Verifies the heap.

Operators

Name Description

Public function Const

bool

 

operator!=

(
    const TArray& OtherArray
)

Inequality operator.

Public function Const

const Elemen...

 

operator[]

(
    SizeType Index
)

Array bracket operator. Returns reference to element at give index.

Const version of the above.

Public function

ElementType ...

 

operator[]

(
    SizeType Index
)

Array bracket operator. Returns reference to element at give index.

Public function

TArray &

 

operator+=

(
    std::initializer_list< ElementType ...
)

Appends the specified initializer list to this array.

Public function

TArray &

 

operator+=

(
    const TArray& Other
)

Appends the specified array to this array. Cannot append to self.

Public function

TArray &

 

operator+=

(
    TArray&& Other
)

Appends the specified array to this array. Cannot append to self.

Move semantics version.

Public function

TArray &

 

operator=

(
    const TArray< ElementType, OtherAll...
)

Assignment operator.

Public function

TArray &

 

operator=

(
    TArray&& Other
)

Move assignment operator.

Public function

TArray &

 

operator=

(
    std::initializer_list< InElementTyp...
)

Initializer list assignment operator.

Public function

TArray &

 

operator=

(
    const TArray& Other
)

Assignment operator.

Public function Const

bool

 

operator==

(
    const TArray& OtherArray
)

Equality operator.

Typedefs

Select Skin
Light
Dark

Welcome to the new Unreal Engine 4 Documentation site!

We're working on lots of new features including a feedback system so you can tell us how we are doing. It's not quite ready for use in the wild yet, so head over to the Documentation Feedback forum to tell us about this page or call out any issues you are encountering in the meantime.

We'll be sure to let you know when the new system is up and running.

Post Feedback