Collection types

The collection types in this package extend and compliment the collections available in the Unity engine. This section outlines some key collection types you might want to use in your jobs and Burst compiled code.

Array-like types

The array-like types in this package extend the key array types in the UnityEngine.CoreModule namespace, which include Unity.Collections.NativeArray<T> and Unity.Collections.NativeSlice<T>. This package has the following array-like types:

Data structure	Description
NativeList<T>	A resizable list. Has thread and disposal safety checks.
UnsafeList<T>	A resizable list.
UnsafePtrList<T>	A resizable list of pointers.
NativeStream	A set of append-only, untyped buffers. Has thread and disposal safety checks.
UnsafeStream	A set of append-only, untyped buffers.
UnsafeAppendBuffer	An append-only untyped buffer.
NativeQueue<T>	A resizable queue. Has thread and disposal safety checks.
NativeRingQueue<T>	A fixed-size circular buffer. Has disposal safety checks.
UnsafeRingQueue<T>	A fixed-size circular buffer.
FixedList32Bytes<T>	A 32-byte list, which includes 2 bytes of overhead, so 30 bytes are available for storage. Max capacity depends upon T. FixedList32Bytes<T> has variants of larger sizes: - FixedList64Bytes<T> - FixedList128Bytes<T> - FixedList512Bytes<T> - FixedList4096Bytes<T>

There aren't any multi-dimensional array types, but you can pack all the data into a single dimension. For example, for an int[4][5] array, use an int[20] array instead (because 4 * 5 is 20).

If you're using the Entities package, a DynamicBuffer component is often the best choice for an array or list like collection.

Additionally, there are various extension methods in NativeArrayExtensions, ListExtensions, and NativeSortExtension.

Map and set types

Use these collection types in single threads when there is a low memory overhead:

Data structure	Description
NativeHashMap<TKey, TValue>	An unordered associative array of key-value pairs. Has thread and disposal safety checks.
UnsafeHashMap<TKey, TValue>	An unordered associative array of key-value pairs.
NativeHashSet<T>	A set of unique values. Has thread and disposal safety checks.
UnsafeHashSet<T>	A set of unique values.

Use these collection types in multithreaded situations, when there is a high memory overhead.

Data structure	Description
NativeParallelHashMap<TKey, TValue>	An unordered associative array of key-value pairs. Has thread and disposal safety checks.
UnsafeParallelHashMap<TKey, TValue>	An unordered associative array of key value pairs.
NativeParallelHashSet<T>	A set of unique values. Has thread and disposal safety checks.
UnsafeParallelHashSet<T>	A set of unique values.
NativeParallelMultiHashMap<TKey, TValue>	An unordered associative array of key value pairs. The keys don't have to be unique. For example, two pairs can have equal keys. Has thread and disposal safety checks.
UnsafeParallelMultiHashMap<TKey, TValue>	An unordered associative array of key value pairs. The keys don't have to be unique. For example, two pairs can have equal keys.

Additionally, there are various extension methods in NotBurstCompatible.Extensions and Unsafe.NotBurstCompatible.Extensions.

Bit arrays and bit fields

The following are arrays of bits:

Data structure	Description
BitField32	A fixed-size array of 32 bits.
BitField64	A fixed-size array of 64 bits.
NativeBitArray	An arbitrary sized array of bits. Has thread and disposal safety checks.
UnsafeBitArray	An arbitrary-sized array of bits.

String types

The following are string types:

Data structure	Description
NativeText	A UTF-8 encoded string. Mutable and resizable. Has thread and disposal safety checks.
UnsafeText	A UTF-8 encoded string. Mutable and resizable.
FixedString32Bytes	A 32-byte UTF-8 encoded string, including 3 bytes of overhead, so 29 bytes available for storage.
FixedString64Bytes	A 64-byte UTF-8 encoded string, including 3 bytes of overhead, so 61 bytes available for storage.
FixedString128Bytes	A 128-byte UTF-8 encoded string, including 3 bytes of overhead, so 125 bytes available for storage.
FixedString512Bytes	A 512-byte UTF-8 encoded string, including 3 bytes of overhead, so 509 bytes available for storage.
FixedString4096Bytes	A 4096-byte UTF-8 encoded string, including 3 bytes of overhead, so 4093 bytes available for storage.

There are further extension methods in FixedStringMethods.

Other types

Data structure	Description
NativeReference<T>	A reference to a single value. Functionally equivalent to an array of length 1. Has thread and disposal safety checks.
UnsafeAtomicCounter32	A 32-bit atomic counter.
UnsafeAtomicCounter64	A 64-bit atomic counter.

Enumerators

Most of the collections have a GetEnumerator method, which returns an implementation of IEnumerator<T>. The enumerator's MoveNext method advances its Current property to the next element:

NativeList<int> nums = new NativeList<int>(10, Allocator.Temp);

// Calculate the sum of all elements in the list.
int sum = 0;
var enumerator = nums.GetEnumerator();

// The first MoveNext call advances the enumerator to the first element.
// MoveNext returns false when the enumerator has advanced past the last element.
while (enumerator.MoveNext())
{
    sum += enumerator.Current;
}

// The enumerator is no longer valid to use after the array is disposed.
nums.Dispose();