Struct NativeList<T>

An unmanaged, resizable list.

Namespace: Unity.Collections

Syntax

[NativeContainer]
public struct NativeList<T> : INativeDisposable, IDisposable, INativeList<T>, IIndexable<T>, IEnumerable<T>, IEnumerable where T : struct

Type Parameters

Name	Description
T	The type of the elements.

Remarks

The elements are stored contiguously in a buffer rather than as linked nodes.

Constructors

NativeList(Int32, AllocatorManager.AllocatorHandle)

Initializes and returns a NativeList.

Declaration

public NativeList(int initialCapacity, AllocatorManager.AllocatorHandle allocator)

Parameters

Type	Name	Description
Int32	initialCapacity	The initial capacity of the list.
AllocatorManager.AllocatorHandle	allocator	The allocator to use.

NativeList(AllocatorManager.AllocatorHandle)

Initializes and returns a NativeList with a capacity of one.

Declaration

public NativeList(AllocatorManager.AllocatorHandle allocator)

Parameters

Type	Name	Description
AllocatorManager.AllocatorHandle	allocator	The allocator to use.

Properties

Capacity

The number of elements that fit in the current allocation.

Declaration

public int Capacity { get; set; }

Property Value

Type	Description
Int32	The number of elements that fit in the current allocation.

Implements

INativeList<T>.Capacity

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if the new capacity is smaller than the length.

IsCreated

Whether this list has been allocated (and not yet deallocated).

Declaration

public readonly bool IsCreated { get; }

Property Value

Type	Description
Boolean	True if this list has been allocated (and not yet deallocated).

IsEmpty

Whether this list is empty.

Declaration

public readonly bool IsEmpty { get; }

Property Value

Type	Description
Boolean	True if the list is empty or if the list has not been constructed.

Implements

INativeList<T>.IsEmpty

Item[Int32]

The element at a given index.

Declaration

public T this[int index] { get; set; }

Parameters

Type	Name	Description
Int32	index	An index into this list.

Property Value

Type	Description
T	The value to store at the index.

Implements

INativeList<T>.Item[Int32]

Exceptions

Type	Condition
IndexOutOfRangeException	Thrown if index is out of bounds.

Length

The count of elements.

Declaration

public int Length { get; set; }

Property Value

Type	Description
Int32	The current count of elements. Always less than or equal to the capacity.

Implements

IIndexable<T>.Length

Remarks

To decrease the memory used by a list, set Capacity after reducing the length of the list.

Methods

Add(in T)

Appends an element to the end of this list.

Declaration

public void Add(in T value)

Parameters

Type	Name	Description
T	value	The value to add to the end of this list.

Remarks

Length is incremented by 1. If necessary, the capacity is increased.

AddNoResize(T)

Appends an element to the end of this list.

Declaration

public void AddNoResize(T value)

Parameters

Type	Name	Description
T	value	The value to add to the end of this list.

Remarks

Length is incremented by 1. Will not increase the capacity.

Exceptions

Type	Condition
Exception	Thrown if incrementing the length would exceed the capacity.

AddRange(Void*, Int32)

Appends the elements of a buffer to the end of this list.

Declaration

public void AddRange(void *ptr, int count)

Parameters

Type	Name	Description
Void*	ptr	The buffer to copy from.
Int32	count	The number of elements to copy from the buffer.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if count is negative.

AddRange(NativeArray<T>)

Appends the elements of an array to the end of this list.

Declaration

public void AddRange(NativeArray<T> array)

Parameters

Type	Name	Description
NativeArray<T>	array	The array to copy from.

Remarks

Length is increased by the number of new elements. Does not increase the capacity.

Exceptions

Type	Condition
Exception	Thrown if the increased length would exceed the capacity.

AddRangeNoResize(Void*, Int32)

Appends elements from a buffer to the end of this list.

Declaration

public void AddRangeNoResize(void *ptr, int count)

Parameters

Type	Name	Description
Void*	ptr	The buffer to copy from.
Int32	count	The number of elements to copy from the buffer.

Remarks

Length is increased by the count. Will not increase the capacity.

Exceptions

Type	Condition
Exception	Thrown if the increased length would exceed the capacity.

AddRangeNoResize(NativeList<T>)

Appends the elements of another list to the end of this list.

Declaration

public void AddRangeNoResize(NativeList<T> list)

Parameters

Type	Name	Description
NativeList<T>	list	The other list to copy from.

Remarks

Length is increased by the length of the other list. Will not increase the capacity.

Exceptions

Type	Condition
Exception	Thrown if the increased length would exceed the capacity.

AsArray()

Returns a native array that aliases the content of this list.

Declaration

public NativeArray<T> AsArray()

Returns

Type	Description
NativeArray<T>	A native array that aliases the content of this list.

AsDeferredJobArray()

Returns an array that aliases this list. The length of the array is updated when the length of this array is updated in a prior job.

Declaration

public NativeArray<T> AsDeferredJobArray()

Returns

Type	Description
NativeArray<T>	An array that aliases this list and whose length can be specially modified across jobs.

Remarks

Useful when a job populates a list that is then used by another job.

If you pass both jobs the same list, you have to complete the first job before you schedule the second: otherwise, the second job doesn't see the first job's changes to the list's length.

If instead you pass the second job a deferred array that aliases the list, the array's length is kept in sync with the first job's changes to the list's length. Consequently, the first job doesn't have to be completed before you can schedule the second: the second job simply has to depend upon the first.

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 we tried to pass the list directly to the second job, that job would not see any modifications made to the list by the first job. To avoid this, we instead pass the second job a deferred array that aliases the list.

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

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

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

   // Sums all numbers from deferred.
   public struct Sum : IJob
   {
       [ReadOnly] public NativeArray<int> deferred;
       public NativeArray<int> sum;

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

   void Start()
   {
       var list = new NativeList<int>(100, Allocator.TempJob);
       var deferred = list.AsDeferredJobArray(),
       var output = new NativeArray<int>(1, Allocator.TempJob);

       // The Populate job increases the list's length from 0 to 100.
       var populate = new Populate { list = list }.Schedule();

       // At time of scheduling, the length of the deferred array given to Sum is 0.
       // When Populate increases the list's length, the deferred array's length field in the
       // Sum job is also modified, even though it has already been scheduled.
       var sum = new Sum { deferred = deferred, sum = output }.Schedule(populate);

       sum.Complete();

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

       list.Dispose();
       output.Dispose();
   }
}

AsParallelReader()

Returns a parallel reader of this list.

Declaration

public NativeArray<T>.ReadOnly AsParallelReader()

Returns

Type	Description
NativeArray.ReadOnly<>	A parallel reader of this list.

AsParallelWriter()

Returns a parallel writer of this list.

Declaration

public NativeList<T>.ParallelWriter AsParallelWriter()

Returns

Type	Description
NativeList.ParallelWriter<>	A parallel writer of this list.

Clear()

Sets the length to 0.

Declaration

public void Clear()

Implements

INativeList<T>.Clear()

Remarks

Does not change the capacity.

CopyFrom(NativeArray<T>)

Overwrites the elements of this list with the elements of an equal-length array.

Declaration

public void CopyFrom(NativeArray<T> array)

Parameters

Type	Name	Description
NativeArray<T>	array	An array to copy into this list.

Exceptions

Type	Condition
ArgumentException	Thrown if the array and list have unequal length.

Dispose()

Releases all resources (memory and safety handles).

Declaration

public void Dispose()

Dispose(JobHandle)

Creates and schedules a job that releases all resources (memory and safety handles) of this list.

Declaration

public JobHandle Dispose(JobHandle inputDeps)

Parameters

Type	Name	Description
JobHandle	inputDeps	The dependency for the new job.

Returns

Type	Description
JobHandle	The handle of the new job. The job depends upon inputDeps and releases all resources (memory and safety handles) of this list.

Implements

INativeDisposable.Dispose(JobHandle)

ElementAt(Int32)

Returns a reference to the element at an index.

Declaration

public ref T ElementAt(int index)

Parameters

Type	Name	Description
Int32	index	An index.

Returns

Type	Description
T	A reference to the element at the index.

Implements

IIndexable<T>.ElementAt(Int32)

Exceptions

Type	Condition
IndexOutOfRangeException	Thrown if index is out of bounds.

GetEnumerator()

Returns an enumerator over the elements of this list.

Declaration

public NativeArray<T>.Enumerator GetEnumerator()

Returns

Type	Description
Unity.Collections.NativeArray.Enumerator<>	An enumerator over the elements of this list.

GetUnsafeList()

Returns the internal unsafe list.

Declaration

public UnsafeList<T>*GetUnsafeList()

Returns

Type	Description
UnsafeList<T>*	The internal unsafe list.

Remarks

Internally, the elements of a NativeList are stored in an UnsafeList.

InsertRangeWithBeginEnd(Int32, Int32)

Shifts elements toward the end of this list, increasing its length.

Declaration

public void InsertRangeWithBeginEnd(int begin, int end)

Parameters

Type	Name	Description
Int32	begin	The index of the first element that will be shifted up.
Int32	end	The index where the first shifted element will end up.

Remarks

Right-shifts elements in the list so as to create 'free' slots at the beginning or in the middle.

The length is increased by end - begin. If necessary, the capacity will be increased accordingly.

If end equals begin, the method does nothing.

The element at index begin will be copied to index end, the element at index begin + 1 will be copied to end + 1, and so forth.

The indexes begin up to end are not cleared: they will contain whatever values they held prior.

Exceptions

Type	Condition
ArgumentException	Thrown if end < begin.
ArgumentOutOfRangeException	Thrown if begin or end are out of bounds.

RemoveAt(Int32)

Removes the element at an index, shifting everything above it down by one. Decrements the length by 1.

Declaration

public void RemoveAt(int index)

Parameters

Type	Name	Description
Int32	index	The index of the item to remove.

Remarks

If you don't care about preserving the order of the elements, RemoveAtSwapBack(Int32) is a more efficient way to remove elements.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if index is out of bounds.

RemoveAtSwapBack(Int32)

Copies the last element of this list to the specified index. Decrements the length by 1.

Declaration

public void RemoveAtSwapBack(int index)

Parameters

Type	Name	Description
Int32	index	The index to overwrite with the last element.

Remarks

Useful as a cheap way to remove an element from this list when you don't care about preserving order.

Exceptions

Type	Condition
IndexOutOfRangeException	Thrown if index is out of bounds.

RemoveRange(Int32, Int32)

Removes N elements in a range, shifting everything above the range down by N. Decrements the length by N.

Declaration

public void RemoveRange(int index, int count)

Parameters

Type	Name	Description
Int32	index	The index of the first element to remove.
Int32	count	The number of elements to remove.

Remarks

If you don't care about preserving the order of the elements, Unity.Collections.NativeList`1.RemoveRangeSwapBackWithBeginEnd(System.Int32,System.Int32) is a more efficient way to remove elements.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if index is out of bounds, count is negative, or index + count exceeds the length.

RemoveRangeSwapBack(Int32, Int32)

Copies the last N elements of this list to a range in this list. Decrements the length by N.

Declaration

public void RemoveRangeSwapBack(int index, int count)

Parameters

Type	Name	Description
Int32	index	The index of the first element to overwrite.
Int32	count	The number of elements to copy and remove.

Remarks

Copies the last count elements to the indexes index up to index + count.

Useful as a cheap way to remove elements from a list when you don't care about preserving order.

Exceptions

Type	Condition
ArgumentOutOfRangeException	Thrown if index is out of bounds, count is negative, or index + count exceeds the length.

Resize(Int32, NativeArrayOptions)

Sets the length of this list, increasing the capacity if necessary.

Declaration

public void Resize(int length, NativeArrayOptions options)

Parameters

Type	Name	Description
Int32	length	The new length of this list.
NativeArrayOptions	options	Whether to clear any newly allocated bytes to all zeroes.

ResizeUninitialized(Int32)

Sets the length of this list, increasing the capacity if necessary.

Declaration

public void ResizeUninitialized(int length)

Parameters

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

Remarks

Does not clear newly allocated bytes.

SetCapacity(Int32)

Sets the capacity.

Declaration

public void SetCapacity(int capacity)

Parameters

Type	Name	Description
Int32	capacity	The new capacity.

ToArray()

Returns a managed array containing a copy of this list's content.

Declaration

public T[] ToArray()

Returns

Type	Description
T[]	A NativeArray containing copies of all the items in the list.

ToArray(AllocatorManager.AllocatorHandle)

Returns an array containing a copy of this list's content.

Declaration

public NativeArray<T> ToArray(AllocatorManager.AllocatorHandle allocator)

Parameters

Type	Name	Description
AllocatorManager.AllocatorHandle	allocator	The allocator to use.

Returns

Type	Description
NativeArray<T>	An array containing a copy of this list's content.

TrimExcess()

Sets the capacity to match the length.

Declaration

public void TrimExcess()

Operators

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

Returns a native array that aliases the content of a list.

Declaration

public static implicit operator NativeArray<T>(NativeList<T> nativeList)

Parameters

Type	Name	Description
NativeList<T>	nativeList	The list to alias.

Returns

Type	Description
NativeArray<T>	A native array that aliases the content of the list.

Extension Methods

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

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

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

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

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

Extensions.ToArrayNBC<T>(NativeList<T>)

Extensions.CopyFromNBC<T>(NativeList<T>, T[])

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

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