Struct NativeList<T>

An unmanaged, resizable list.

Namespace: Unity.Collections
Syntax
[NativeContainer]
public struct NativeList<T> : INativeDisposable, IDisposable, INativeList<T>, IEnumerable<T>, IEnumerable where T : struct
Type Parameters
Name Description
T

The type of the elements in the container.

Constructors

NativeList(Int32, Allocator)

Constructs a new list with the specified initial capacity and type of memory allocation.

Declaration
public NativeList(int initialCapacity, Allocator allocator)
Parameters
Type Name Description
Int32 initialCapacity

The initial capacity of the list. If the list grows larger than its capacity, the internal array is copied to a new, larger array.
Allocator allocator

A member of the Unity.Collections.Allocator enumeration.

NativeList(Allocator)

Constructs a new list using the specified type of memory allocation.

Declaration
public NativeList(Allocator allocator)
Parameters
Type Name Description
Allocator allocator

A member of the Unity.Collections.Allocator enumeration.
Remarks

The list initially has a capacity of one. To avoid reallocating memory for the list, specify sufficient capacity up front.

Properties

Capacity

The number of items that can fit in the list.

Declaration
public int Capacity { get; set; }
Property Value
Type Description
Int32

The number of items that the list can hold before it resizes its internal storage.
Implements
Remarks

Capacity specifies the number of items the list can currently hold. You can change Capacity to fit more or fewer items. Changing Capacity creates a new array of the specified size, copies the old array to the new one, and then deallocates the original array memory. You cannot change the Capacity to a size smaller than Length (remove unwanted elements from the list first).

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown if Capacity is set smaller than Length.

IsCreated

Reports whether memory for the container is allocated.

Declaration
public bool IsCreated { get; }
Property Value
Type Description
Boolean

True if this container object's internal storage has been allocated.
Remarks

Note that the container storage is not created if you use the default constructor. You must specify at least an allocation type to construct a usable container.

Warning: the IsCreated property can't be used to determine whether a copy of a container is still valid. If you dispose any copy of the container, the container storage is deallocated. However, the properties of the other copies of the container (including the original) are not updated. As a result the IsCreated property of the copies still return true even though the container storage has been deallocated. Accessing the data of a native container that has been disposed throws a InvalidOperationException exception.

IsEmpty

Reports whether container is empty.

Declaration
public bool IsEmpty { get; }
Property Value
Type Description
Boolean

True if this container empty.
Implements

Item[Int32]

Retrieve a member of the contaner by index.

Declaration
public T this[int index] { get; set; }
Parameters
Type Name Description
Int32 index

The zero-based index into the list.
Property Value
Type Description
T

The list item at the specified index.
Implements
Exceptions
Type Condition
IndexOutOfRangeException

Thrown if index is negative or >= to Length.

Length

The current number of items in the list.

Declaration
public int Length { get; set; }
Property Value
Type Description
Int32

The item count.
Implements

Methods

Add(T)

Adds an element to the list.

Declaration
public void Add(in T value)
Parameters
Type Name Description
T value

The struct to be added at the end of the list.
Remarks

If the list has reached its current capacity, it copies the original, internal array to a new, larger array, and then deallocates the original.

AddNoResize(T)

Adds an element to the list.

Declaration
public void AddNoResize(T value)
Parameters
Type Name Description
T value

The value to be added at the end of the list.
Remarks

If the list has reached its current capacity, internal array won't be resized, and exception will be thrown.

AddRange(Void*, Int32)

Adds elements from a buffer to this list.

Declaration
public void AddRange(void *elements, int count)
Parameters
Type Name Description
Void* elements

A pointer to the buffer.
Int32 count

The number of elements to add to the list.
Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown if count is negative.

AddRange(NativeArray<T>)

Adds the elements of a NativeArray to this list.

Declaration
public void AddRange(NativeArray<T> elements)
Parameters
Type Name Description
NativeArray<T> elements

The items to add.

AddRangeNoResize(Void*, Int32)

Adds elements from a buffer to this list.

Declaration
public void AddRangeNoResize(void *ptr, int length)
Parameters
Type Name Description
Void* ptr

A pointer to the buffer.
Int32 length

The number of elements to add to the list.
Remarks

If the list has reached its current capacity, internal array won't be resized, and exception will be thrown.

Exceptions
Type Condition
ArgumentOutOfRangeException

Thrown if length is negative.

AddRangeNoResize(NativeList<T>)

Adds elements from a list to this list.

Declaration
public void AddRangeNoResize(NativeList<T> list)
Parameters
Type Name Description
NativeList<T> list

Other container to copy elements from.
Remarks

If the list has reached its current capacity, internal array won't be resized, and exception will be thrown.

AsArray()

This list as a NativeArray.

Declaration
public NativeArray<T> AsArray()
Returns
Type Description
NativeArray<T>

A NativeArray "view" of the list.
Remarks

The array is not a copy; it references the same memory as the original list. You can use the NativeArray API to manipulate the list.

AsDeferredJobArray()

Provides a NativeArray that you can pass into a job whose contents can be modified by a previous job.

Declaration
public NativeArray<T> AsDeferredJobArray()
Returns
Type Description
NativeArray<T>

A NativeArray that can be passed to one job as a "promise" that is fulfilled by a previous job.
Remarks

Pass a deferred array to a job when the list is populated or modified by a previous job. Using a deferred array allows you to schedule both jobs at the same time. (Without a deferred array, you would have to wait for the results of the first job before you scheduling the second.)

Examples

The following example populates a list with integers in one job and passes that data to a second job as a deferred array. If you tried to pass the list directly to the second job, that job would get the contents of the list at the time you schedule the job and would not see any modifications made to the list by the first job.

using UnityEngine;
using Unity.Jobs;
using Unity.Collections;

public class DeferredArraySum : MonoBehaviour
{
   public struct ListPopulatorJob : IJob
   {
       public NativeList<int> list;

       public void Execute()
       {
           for (int i = list.Length; i < list.Capacity; i++)
           {
               list.Add(i);
           }
       }
   }

   public struct ArraySummerJob : IJob
   {
       [ReadOnly] public NativeArray<int> deferredArray;
       public NativeArray<int> sum;

       public void Execute()
       {
           sum[0] = 0;
           for (int i = 0; i < deferredArray.Length; i++)
           {
               sum[0] += deferredArray[i];
           }
       }
   }

   void Start()
   {
       var deferredList = new NativeList<int>(100, Allocator.TempJob);

       var populateJob = new ListPopulatorJob()
       {
           list = deferredList
       };

       var output = new NativeArray<int>(1, Allocator.TempJob);
       var sumJob = new ArraySummerJob()
       {
           deferredArray = deferredList.AsDeferredJobArray(),
           sum = output
       };

       var populateJobHandle = populateJob.Schedule();
       var sumJobHandle = sumJob.Schedule(populateJobHandle);

       sumJobHandle.Complete();

       Debug.Log("Result: " + output[0]);

       deferredList.Dispose();
       output.Dispose();
   }
}

AsParallelReader()

Returns parallel reader instance.

Declaration
public NativeArray<T>.ReadOnly AsParallelReader()
Returns
Type Description
NativeArray.ReadOnly<>

Parallel reader instance.

AsParallelWriter()

Returns parallel writer instance.

Declaration
public NativeList<T>.ParallelWriter AsParallelWriter()
Returns
Type Description
NativeList.ParallelWriter<>

Parallel writer instance.

Clear()

Clears the list.

Declaration
public void Clear()
Implements
Remarks

List Capacity remains unchanged.

CopyFrom(T[])

Overwrites this list with the elements of an array.

Declaration
public void CopyFrom(T[] array)
Parameters
Type Name Description
T[] array

A managed array to copy into this list.

CopyFrom(NativeArray<T>)

Overwrites this list with the elements of an array.

Declaration
public void CopyFrom(NativeArray<T> array)
Parameters
Type Name Description
NativeArray<T> array

NativeArray to copy into this list.

Dispose()

Disposes of this container and deallocates its memory immediately.

Declaration
public void Dispose()

Dispose(JobHandle)

Safely disposes of this container and deallocates its memory when the jobs that use it have completed.

Declaration
public JobHandle Dispose(JobHandle inputDeps)
Parameters
Type Name Description
JobHandle inputDeps

The job handle or handles for any scheduled jobs that use this container.
Returns
Type Description
JobHandle

A new job handle containing the prior handles as well as the handle for the job that deletes the container.
Implements
Remarks

You can call this function dispose of the container immediately after scheduling the job. Pass the JobHandle returned by the Job.Schedule method using the jobHandle parameter so the job scheduler can dispose the container after all jobs using it have run.

ElementAt(Int32)

Declaration
public T ElementAt(int index)
Parameters
Type Name Description
Int32 index
Returns
Type Description
T
Implements

GetEnumerator()

Declaration
public NativeArray<T>.Enumerator GetEnumerator()
Returns
Type Description
Unity.Collections.NativeArray.Enumerator<>

GetUnsafeList()

Return internal UnsafeList*

Declaration
public UnsafeList*GetUnsafeList()
Returns
Type Description
UnsafeList*

InsertRangeWithBeginEnd(Int32, Int32)

Inserts a number of items into a container at a specified zero-based index.

Declaration
public void InsertRangeWithBeginEnd(int begin, int end)
Parameters
Type Name Description
Int32 begin

The zero-based index at which the new elements should be inserted.
Int32 end

The zero-based index just after where the elements should be removed.
Exceptions
Type Condition
ArgumentException

Thrown if end argument is less than begin argument.
ArgumentOutOfRangeException

Thrown if begin or end arguments are not positive or out of bounds.

RemoveAt(Int32)

Truncates the list by removing the item at the specified index, and shifting all remaining items to replace removed item. The list is shortened by one.

Declaration
public void RemoveAt(int index)
Parameters
Type Name Description
Int32 index

The index of the item to delete.
Remarks

This method of removing item is useful only in case when list is ordered and user wants to preserve order in list after removal In majority of cases is not important and user should use more performant RemoveAtSwapBack.

RemoveAtSwapBack(Int32)

Truncates the list by replacing the item at the specified index with the last item in the list. The list is shortened by one.

Declaration
public void RemoveAtSwapBack(int index)
Parameters
Type Name Description
Int32 index

The index of the item to delete.
Exceptions
Type Condition
ArgumentOutOfRangeException

If index is negative or >= Length.

RemoveRangeSwapBackWithBeginEnd(Int32, Int32)

Truncates the list by replacing the item at the specified index range with the items from the end the list. The list is shortened by number of elements in range.

Declaration
public void RemoveRangeSwapBackWithBeginEnd(int begin, int end)
Parameters
Type Name Description
Int32 begin

The first index of the item to remove.
Int32 end

The index past-the-last item to remove.
Exceptions
Type Condition
ArgumentException

Thrown if end argument is less than begin argument.
ArgumentOutOfRangeException

Thrown if begin or end arguments are not positive or out of bounds.

RemoveRangeWithBeginEnd(Int32, Int32)

Truncates the list by removing the items at the specified index range, and shifting all remaining items to replace removed items. The list is shortened by number of elements in range.

Declaration
public void RemoveRangeWithBeginEnd(int begin, int end)
Parameters
Type Name Description
Int32 begin

The first index of the item to remove.
Int32 end

The index past-the-last item to remove.
Remarks

This method of removing item(s) is useful only in case when list is ordered and user wants to preserve order in list after removal In majority of cases is not important and user should use more performant RemoveRangeSwapBackWithBeginEnd.

Exceptions
Type Condition
ArgumentException

Thrown if end argument is less than begin argument.
ArgumentOutOfRangeException

Thrown if begin or end arguments are not positive or out of bounds.

Resize(Int32, NativeArrayOptions)

Changes the list length, resizing if necessary.

Declaration
public void Resize(int length, NativeArrayOptions options)
Parameters
Type Name Description
Int32 length

The new length of the list.
NativeArrayOptions options

Memory should be cleared on allocation or left uninitialized.

ResizeUninitialized(Int32)

Changes the container length, resizing if necessary, without initializing memory.

Declaration
public void ResizeUninitialized(int length)
Parameters
Type Name Description
Int32 length

The new length of the container.

ToArray()

A copy of this list as a NativeArray.

Declaration
public T[] ToArray()
Returns
Type Description
T[]

A NativeArray containing copies of all the items in the list.

ToArray(Allocator)

A copy of this list as a NativeArray allocated with the specified type of memory.

Declaration
public NativeArray<T> ToArray(Allocator allocator)
Parameters
Type Name Description
Allocator allocator

A member of the Unity.Collections.Allocator enumeration.
Returns
Type Description
NativeArray<T>

A NativeArray containing copies of all the items in the list.

Operators

Implicit(NativeList<T> to NativeArray<T>)

This list as a NativeArray.

Declaration
public static implicit operator NativeArray<T>(NativeList<T> nativeList)
Parameters
Type Name Description
NativeList<T> nativeList

A NativeList instance.
Returns
Type Description
NativeArray<T>

A NativeArray containing all the items in the list.
Remarks

The array is not a copy; it references the same memory as the original list.

Extension Methods