Struct NativeList<T>

An unmanaged, resizable list.

Namespace: Unity.Collections

Syntax

public struct NativeList<T> : IEnumerable<T>, IEnumerable, IDisposable where T : struct

Type Parameters

Name	Description
T	The type of the elements in the list.

Constructors

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.

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.

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.

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
ArgumentException	Thrown if Capacity is set smaller than Length.

IsCreated

Reports whether memory for the list is allocated.

Declaration

public bool IsCreated { get; }

Property Value

Type	Description
Boolean	True if this list object's internal storage has been allocated.

Remarks

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

Item[Int32]

Retrieve a member of the list 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.

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; }

Property Value

Type	Description
Int32	The item count.

Methods

Add(T)

Adds an element to the list.

Declaration

public void Add(T value)

Parameters

Type	Name	Description
T	value

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(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.

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.

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.

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

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 writer instance.

Declaration

public NativeArray<T> AsParallelReader()

Returns

Type	Description
NativeArray<T>

AsParallelWriter()

Returns parallel reader instance.

Declaration

public NativeArray<T> AsParallelWriter()

Returns

Type	Description
NativeArray<T>

Clear()

Clears the list.

Declaration

public void Clear()

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 or NativeArray to copy into this list.

Remarks

The array to be copied must have a length equal to or greater than the current 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

Returns

Type	Description
JobHandle	A new job handle containing the prior handles as well as the handle for the job that deletes the container.

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.

GetEnumerator()

Declaration

public NativeArray<T>.Enumerator GetEnumerator()

Returns

Type	Description
NativeArray.Enumerator<>

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.

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 list length, resizing if necessary, without initializing memory.

Declaration

public void ResizeUninitialized(int length)

Parameters

Type	Name	Description
Int32	length	The new length of the list.

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

NativeArrayExtensions.Contains<T, U>(NativeList<T>, U)

NativeArrayExtensions.IndexOf<T, U>(NativeList<T>, U)

JobNativeMultiHashMapVisitKeyValue.Schedule<TJob, TKey, TValue>(TJob, NativeMultiHashMap<TKey, TValue>, Int32, JobHandle)

JobNativeMultiHashMapVisitKeyMutableValue.Schedule<TJob, TKey, TValue>(TJob, NativeMultiHashMap<TKey, TValue>, Int32, JobHandle)

NativeSortExtension.Sort<T, U>(NativeList<T>, U)

JobUnsafeMultiHashMapVisitKeyValue.Schedule<TJob, TKey, TValue>(TJob, UnsafeMultiHashMap<TKey, TValue>, Int32, JobHandle)

JobUnsafeMultiHashMapVisitKeyMutableValue.Schedule<TJob, TKey, TValue>(TJob, UnsafeMultiHashMap<TKey, TValue>, Int32, JobHandle)

NativeListUnsafeUtility.GetUnsafePtr<T>(NativeList<T>)

NativeListUnsafeUtility.GetUnsafeReadOnlyPtr<T>(NativeList<T>)